Arduino programming guide series

09

Confusing keywords? follow the source code trail

A student asked me: What is the meaning of a “weird” keyword used in a constructor? It was the keyword “POSITIVE” in one of the constructors from the LiquidCrystal_I2C class.

This keyword indeed is not part of the C or C++ language. 

So what could it be?

It is a keyword that has been defined in an included class or the current sketch.

To find out exactly where it is defined, you must follow the trail of added classes, load the open-source code in your text editor, and find out where the mysterious keyword is defined.

I have converted this student question into an example so I can show you how you can go about finding the origin of a keyword that you can readily recognize.

Here is the exchange between the student an myself:

Student question (verbatim):

My IDE is not accepting the keyword POSITIVE in the lcdi2c declaration line of code.


Why do we insert the library in this foramt("RTClib.h")rather than this format(<RTClib.h>)?

Here's my response:

You probably have the wrong library installed. There are a few around with the same name.

The constructor that you refer to accepts keywords for controlling the backlit. In line 197 of the LCD.h file, these keywords are defined using a typedef construct (more about this here). The name of this typedef is t_backlightPol.

In line 61 of the LiquidCrystal_I2C.h, which is the constructor we use in the sketch, this keyword (POSITIVE) is used via the t_backlightPol typedef. It's just easier to remember and understand what the purpose of the parameter is when we use simple words instead of things like 1, 0, HIGH, LOW.

The pre-processor of the compiler (the program that works out where the different parts that make up your program are, as well as a few other things) will decide how to insert the file that you want to include into your program based on whether the name is within brackets or double-quotes.

If you use brackets, then the pre-processor will look for a header file and insert it into your program at the location of the include statement.

If you use a double-quote, then the pre-processor will look for the file (header or not, it doesn't matter), and also insert it into your program at the location of the include statement.

In the case of #include "RTClib.h", we include a header file so I guess we could have used #include <RTClib.h> instead (you may want to try and see if that works).

The details are available in the C standard document (PDF – N1570 Committee Draft, April 12, 2011). See section 6.10.2, "Source file inclusion." The difference between the two methods is very subtle, and my self-don't fully understand it (nor I am curious to do). The preprocessor is responsible for the implementation of this standard, and I know that different preprocessors follow slightly different approaches.

"Arduino programming" series

New to the Arduino?

Arduino Step by Step Getting Started is our most popular course for beginners.

This course is packed with high-quality video, mini-projects, and everything you need to learn Arduino from the ground up. We'll help you get started and at every step with top-notch instruction and our super-helpful course discussion space.

>