Expanding #include

The C/C++ preprocessor interpreted the #include directives we put in arduino_skel.cpp. It hit that directive, went out and got the do_nothing.cpp file, and copied that code into a file along with arduino_skell.cpp, before the whole business got sent to the C++ compiler. That’s the most common job for the preprocessor.

Macro Expansion

Preprocessor macros are extraordinarily useful. They’re also extremely common in the microcontroller world (like Arduino), because they take no memory at runtime. None. A variable can get pretty heavy, memory-wise, when you’re dealing with only 4KB of memory, so having constants in that kind of environment is a waste. I used them a ton in my previous book, Junk Box Arduino, to substitute for Arduino constants with ambiguous names, to substitute for binary bit patterns, and so forth. Here’s an example.

If you’ve done any Arduino port programming, you know that those port names change depending on what model of Arduino you’re on. By abstracting them in a macro, it meant that if you moved my code to say, an Arduino Mega, you just had to change portb or ddrb, instead of modifying the whole program. That’s how macros are expanded. The first term is the macro, the second is its value. So we’re defining Control_Port and telling the preprocessor to substitute portb every time it sees Control_Port, ddrb for every Control_DDR, and 3.14 for every pi. Macros can do a lot more than that. They can take parameters and do math and string operations on them. The C/C++ precompiler is, itself, a fairly complete programming language.

In a contest called “Obfuscated C,” the story goes, a programmer wrote an entire sieve of Eratosthenes in precompiler macros, and the only C code was the code that printed out the list of prime numbers that was the result. If memory serves, he won the brand new “Best Abuse of the Preprocessor” award. Once compiled, of course, his program would have taken no time to run, since the prime numbers were already generated. It would have taken a long time to compile though. I don’t use preprocessor functions in this book. They’re tricky and hard to read, and they’re well documented online.

Conditional Compilation

C and C++ are funny animals. You can sometimes find yourself in a corner where you have to #include something twice. In arduino_skel.cpp, the function setup() calls the function do_nothing(). Suppose do_nothing() calls a third function that is also called by main in arduino_skel. Function order can get very fussy, and at times with complex programs, it’s possible to get stuck in a situation where there’s no right answer when a function can be defined. The C/C++ solution to this conundrum is the function prototype. We’ll get to those in later chapters, but the short version is, it provides a placeholder definition for a function to be formally defined later. These, in turn, are often stored in .h files and included at compile time.

Here’s where conditional compilation matters. You often break out those function definitions in separate files, but put the skeletons together in the same file. Your compiler will complain if you include the header file twice. Here’s how the preprocessor fixes that for you. In your program file and in all the function definition files, you can put this.

What’s happening here? Well, #ifndef is “if not defined.” If the macro header_included is not defined, it means that the header file has not been included. The next lines are what happen if header_included is not defined. We define it, and then we include the header file.

The last line ends the #ifndef statement. This bit of preprocessor code will #include the header file only if it hasn’t already been loaded. When the precompiler goes to roll this particular file into the one big file it will feed to the compiler, if header_included is already defined, it won’t run the #include "header.h". I’ve intended the ifdef code here like we would in C++ and C, but it’s often not written that way.

But you can do more with conditional compilation. To get back to the code we talked about in the “Macro Expansion” section, let’s say I knew my Arduino sketch was going to be run on more than one type of Arduino. I could put something like this in:

You’re not limited to putting #ifdefs before the C++ code, either. If you have a function that is specific to one processor but not another, you can #ifdef that function out based on what processor you’re using.

We won’t use #ifdef much, if at all, but it’s a useful thing.

Objects

An object is a way to put data and code in a single entity. It’s like if the toolkit in your car (I’m dating myself again, aren’t I?) had literally all the tools you’d ever need to work on the car, and only that car. Every other kind of car has its own tools, and even if my car is the same as your car, each of our cars has its own toolbox, and we can’t use each other’s.

Classes

So now that you’ve got a grasp of what an object is, and what it’s made of, the next obvious question is, “how do you make them?”

There are two steps. Bear this in mind. It’s one of the things that confused me about C++ for a long time. Two steps. The first is to define what we want the object to be. That definition is called a class.

A class defines the attributes and methods of the object and gives them their names. For the previous example, it might look like this:

Lugs and the cheater_bar function are private, but lug_wrench is public. It’s important, so I’ll repeat it. A class is not an object. Nothing is actually created by a class. If I put this code in arduino_skel. cpp , it will compile, but it won’t do anything. If I tried to call lug_wrench(), I’d get an error.

Let There Be Objects

When you turn a class into an object, it’s exactly the same as creating a variable. Same idea, same syntax.

This declares an object called My_VW of the type car_and_tools.

Now an object exists. Let’s create another one.

Done. If I want to use the lug_wrench() method of My_VW, I can call it like this:

I can’t do anything to My_Wifes_Subaru calling methods on My_VW. My_Wifes_Subaru has its own lug wrench, and I’d call it like this.

I can’t touch the lugs attribute of either object because they’re defined in the class as private. I can’t touch the cheater_bar() method in either object because they’re defined in the class as private. I know, I’m repeating myself, but these are the fundamentals of object-oriented programming. Do they make sense now?

Good. Enough lecture. Let’s go write a program.

Rules

The rules of tic-tac-toe are pretty simple. You and your opponent take turns placing Xs and Os on the board until one or the other (or more often neither) of you gets three in a row horizontally, vertically, or diagonally. (Yeah, the Elle King song is running through my head now too. Sorry.) So the program needs to represent the board in data. It needs to be able to tell if someone won. And it needs a way for players to put their data in. If that sounds like there’s an object involved, you’ve got a good ear.

Objects

There’s only one object we need in this program. It’s called the_board, of the class board. Go ahead and write that down. We need a class called board.

Attributes

The board class needs to store all the moves in the game. To make it easy to picture how all this code works, we’ll represent those moves as a two-dimensional array of chars. (Single characters.) Yes, a boolean would use less memory. Don’t worry about it. You’re programming a Raspberry Pi now. Your Pi has at least 256MB of RAM. The fact that we’re using nine bytes of RAM to store data we could fit in nine bits doesn’t matter. We’ll call it board_data.

No code outside the board object needs to talk to board_data, so we’ll make it private. So write that down in the board class.

Methods

The board class needs to be able to see if anyone has won. While that method needs to be accessed from the outside, it’s going to be a huge monster of a method. Let’s break it down further.

If you think about it, you can check all the possible victory conditions with three types of checks. A check across, a check vertically, and a check diagonally. So let’s create methods to do those things. No code outside the board object needs to access these smaller methods, so we’ll make them private. We’ll fill the actual code in later.

We’ll need a public method so that code outside an object of the board class can see if the board is in a winning state. But by now, there’s something that should have you screaming at me. The board_data array is not initialized. Anywhere. That is a great way to get pseudo-random results, and that’s not what we’re looking for, so we need to create two public methods: one to initialize the array, and one to check to see if a player has won.

Actually we need more methods than that. We need a method to display the board on the terminal window. We also need a way for players to make their moves. Okay. Let’s write all those down too.

Actually wait.

The only time we’re going to call the method that initializes the board_data array is when the object is first instantiated. It’d be nice if C++ could just call that for us, wouldn’t it? It can. If you name a public method the same thing as the class name, it’s called the constructor, and C++ will call it when the object is created. As the name might suggest, there is also a destructor, if you need one. It’s also a public method and it’s the class name again, only with a tilde (~) in front of it. Like this:

C++ actually has a default constructor and destructor, so if you don’t have to do anything special for one or the other, you don’t need to include one. We need a constructor to initialize board_ data , but the default destructor is just fine. So let’s write that down too.

It’s more complicated than a sketch, but not much more complicated. You may have written sketches with objects already. If so, you’re ahead of the game. If not, and you’re looking at the class and wondering how much worse this is going to get, the answer is not much. Most of the complexity is right here in the skeleton. Each of those methods is straightforward code. You’ve done functions harder than these if you’ve done much Arduino programming. And with all the heavy lifting done in objects of the board class, main() is pretty simple too, as you’ll see.

So let’s get coding.

The Class

Here’s the actual board class, in all its glory, comments intact.

We just declared the constructor. You noticed, right?

I use boolean logic a lot. It’s very important to differentiate between a binary and (&) and a logical and (&&). A binary and (&) takes two binary values and returns a third. If you pass it a char, that’s eight bits. Say, 0b00000001 and 0b00000011. If you and those two values together, you get 0b00000001. Only the leading 1 is true in both values. The point is, binary ands don’t work at all when you pass them a boolean variable (true or false). For that you need a boolean, or logical, and (&&). If it sounds like I chased my tail for some time writing this program because I forgot that, I did.

By the by: 0bxxxx is notation for a binary literal, just as 0x precedes hexadecimal literals. It’s part of the C++ standard as of 2014, and was part of GNU C++ long before that. If you’re also coding for the Arduino, I strongly recommend against using their B prefix for binary values. It only works with values up to eight bits. 0b always works.

Just in case you didn’t already know, // is an alternative notation for comments. Multiline comments are surrounded with /* and */.

Main

So with most of the game taken care of in the board object class, what’s left for main to do? Not a whole lot, and that’s fine. The ideal main() doesn’t do a lot of heavy lifting. The idea is that somehow objects in code might be reusable without a lot of custom code to make them go in main(). How realistic that is, I don’t honestly know, but that’s the ideal.

Our main needs to do three things, really. It needs to instantiate a board class object, display the board, then loop back and forth between players, display the board and getting moves until someone wins.

And that’s exactly what it does.

Note that main must return an integer variable. This tells Linux whether or not there were errors during the program’s run.

Cout Is Not Serial.print

It’s tempting to use std:: cout just the same as we used serial.print in Arduino. They are not the same thing. Because this is C++, cout and cin are objects. The commands we’re actually issuing are << (the stream insertion operator) and >> (the stream extraction operator). They are formatted input and output operators, and they’re smart enough (barely) to recognize what type of variable or attribute they’re being asked to put data into or get data out of. The problem is, the stream may have other stuff in it. For cout , this is seldom a problem. For cin , it can make quite a mess, because anything left in the stream will be read the next time cin is accessed. In later programs we’ll get into more serious input protection, when we need it. For tictac.cpp, just bear in mind that if you feed it bad input values, it will go into an infinite loop and give you an error message. By default, C++ and its ancestor C are horrible at handling user input in general, but especially character strings. I guarantee you that you’ll miss the Arduino string class long before we’re done. We’ll use a better mechanism as we get into later chapters.