I often recommend avoiding the String class in Arduino programs, but I never took the time to show you the alternatives. In this article, I’ll teach you how to format complex strings without the String class. What do I mean by that? You know, this kind of things:

// https://api.github.com/bblanchon/repos?page=2
String url = String("https://api.github.com/") + user + "/repos?page=" + page;

What’s the problem with the String class?

But why should we avoid the String class? As I explained in a previous article, heap fragmentation is a major concern in embedded programming. To prevent fragmentation, you should always allocate blocks of the same size, or better, don’t use the heap at all.

The problem with the String class is that it forces you to use the heap and allocates blocks of variables size. Use several String instances in your program, and soon, the RAM is full of holes like Swiss cheese.

Back to basics

So how can we get rid of the String class? We’ll take some distance with C++ for a moment and get back to plain old C. As you probably know, we can use any C feature in C++, and that what we’re going to do in this article: we’ll formats strings as C programmers do.

First, let’s look at how the C language models strings. In C, a string is a contiguous sequence of characters ended by a 0. We call this last byte the “terminator” because it marks the end of the sequence. The picture below shows how the bytes of the string “hello” are laid out in RAM.

Keep this picture in mind because every time you write a string literal, this is exactly what goes in memory, whether you use the String class or not. Indeed, the String class is just a fancy wrapper on top of a C string. Everything you can do with the String class, you can also do with a C string, even if it’s usually more complicated.

String formatting in C

If you’ve done any C programming, you probably used the printf() function, which writes things to the terminal. printf() is the equivalent of Arduino’s Serial.print().

The major difference between printf() and Serial.print() is that, before passing the things you want to write, you must tell printf() the type of those things. For example, suppose you have a float that contains the weight of something, and you want to display it. On Arduino you would write:

Serial.print(weight);

In C, you would write:

printf("%f", weight);

As you see, we need to pass an extra argument that specifies the type. In this case, %f means that we are passing a floating-point value. We’ll see more examples in a moment, but first, let me explain how this relates to strings.

Storing the result

As you know, Serial.print() sends information to the serial port but doesn’t store it. Similarly, printf() sends information to the terminal but doesn’t store anything. To save the result of in a string, we need to use another function called sprintf(). This function takes the destination string as an additional argument. The destination comes first in the argument list, before the format and before the values you want to write.

If we go back to our previous example, to store the string on Arduino you would probably write:

String s = weight;

In C, you would write;

char s[16];
sprintf(s, "%f", weight);

As you can see, the C version is a little more verbose. In addition to calling sprintf(), we need to allocate the sequence of characters. In this case, we used a simple char array large enough to store the string with the terminator.

Now you can see a major difference between the two approaches: the Arduino version uses a String, which allocates the right number of bytes in the heap, whereas the C version allocates a fixed number of bytes in the stack.

You probably worry about the overhead caused by the unused bytes in the array. You’re right, there can be up to 14 unused bytes in the array, but this is nothing compared to what you loose from the heap management data and from the heap fragmentation. Moreover, this is a local variable, so we’ll reclaim the memory as soon as it gets out of scope.

Buffer overflows

No, I’m not worried about the memory overhead, but I’m seriously concerned about buffer overflows. What happens if you’ve been too cheap when allocating the string and the actual content is longer than expected. I’ll tell you what happens: bad things! sprintf() is not aware of the capacity of the destination buffer, so it continues to write as if nothing happened.

In practice, it overrides the bytes that follow the buffer in RAM. For example, if there is an integer variable stored just after the buffer, the value of this variable will change. This is what we call a buffer overflow, and it’s a real security issue. Not only a buffer overflow may crash your program, but it also allows hackers to modify the memory of your process and change its behavior.

To protect your program against buffer overflows, you must use another variant of printf(), called snprintf(), which supports an additional parameter to specify the capacity of the destination buffer. Here it is in action:

char s[16];
snprintf(s, 16, "%f", weight);

As you can see, we pass the size of the buffer as the second parameter of snprintf(); I used the literal 16, but we could use sizeof(s) instead.

Placeholders

We saw how we could use snprintf() to convert a float to a string, is that all we can do? Of course not, that was just an introduction; snprintf() is very flexible as we’ll see now.

First, let’s see how we can put this float in a sentence. Imagine we want to generate the string "weight = {weight} kg". With the String class, you would do something like:

String s = String("weight = ") + weight + String(" kg")

From the programmer’s point of view, this line of code is OK: it does the job and is fairly readable. However, from the processor standpoint, this line of code is horrible: it requires 4 allocations in the heap and possibly several memory duplications. That’s way too much work for such a simple task.

Now, let’s see how we would write the same line with snprintf():

char s[32];
snprintf(s, sizeof(s), "weight = %f kg", weight);

The syntax is a bit more clunky, but as soon as you get used to it (and every C programmer got used to it before you), it reads fairly well too. As you can see, the %f that was our complete format specification is now a placeholder for the value.

If you want to format your number in a certain way, you can say so in the format string. For example, if you want four digits after the decimal point, you can write:

snprintf(s, sizeof(s), "weight = %.4f kg", weight);

As a reminder, this is how you would do with the String class:

String s = String("weight = ") + String(weight, 4) + String(" kg");

Which one is the most readable now?

Other types

I think you get the idea; let’s talk about other value types. Remember that you must adapt the format specifier to the type of the value. %f was only for floats; for other types, you must use other specifiers like %i, %h, or %s. The table below summarizes the most common format specifiers:

*: not supported by the Arduino Core for AVR

You can find the complete list on Wikipedia. There is also a shorter version in Appendix B of the K&R book, which I recommend.

Mixing types

Of course, we can use several placeholders when we have several values. Suppose we want to create the string "{name} is {age} years old" from the two variables name (a string) and age (an integer). To do that, we call snprintf() like this:

snprintf(s, sizeof(s), "%s is %i years old", name, age);

As you see, we use the %s format for the string and %i for the integer. In this case, I assumed the string was a const char*. Indeed, snprintf() is a C function, so it knows nothing about C++ objects, it only supports C strings. If instead, we have a String object, we would have to get the pointer to the internal C string, like that:

snprintf(s, sizeof(s), "%s is %i years old", name.c_str(), age);

Also, notice the order of the arguments: the values appear in the same order as the placeholders. This is a constraint imposed by printf functions: the arguments must be in the same order as the placeholders in the format string.

Format string errors

What happens if you pass the arguments in the wrong order? For %i, it’s not so bad, snprintf() would treat name as an integer instead of a string. In practice, it would print the address of the string in decimal. Things get way worse for the %s because snprintf() would treat the integer as a string: it would look at the bytes at the address specified in the integer and print them until it finds the terminator. In practice, this would print garbage in the destination buffer.

Here too, we have a potential security issue. If there is a mismatch between the format specifier and the types of the arguments, the program may disclose information that an attacker could exploit. For example, it could display the value of a pointer value, or even reveal the complete content of the RAM.

Fortunately, the compiler is your friend: it issues a warning when it detects a mismatch in a printf-like function. That’s yet another reason why you should never ignore warnings.

Because this verification is done by the compiler, it can only work if the format string is available at compile-time. In other words, it only works if you pass a constant as the format string. Remember this: Never use a variable as the format string, always use a constant.

In particular, never ever use a string that comes from user input as the format string because it would be an easy target for the aspiring hacker. When I say “a user input,” I mean anything that comes from the outside of the code, including configuration files and HTTP requests or responses. Ignoring this commandment would open the door to a format string attack.

The Holy Grail

Before we say goodbye, I’ll like to present my all-time favorite function of the whole Arduino ecosystem. It’s snprintf_P(), but I call it “the holy grail” because it’s a hidden treasure that does everything one would want. It is identical to snprintf() except that it reads the format string from the Flash memory, and therefore reduces the RAM consumption. See it in action here:

snprintf_P(s, sizeof(s), PSTR("%s is %i years old"), name, age);

Note that I used the PSTR() macro instead of F() because snprintf_P() expects a regular char pointer and not a const __FlashStringHelper*.

Conclusion

I’ll conclude this article with my usual advice: stop using the String class.

Start today. Replace instances one after the other. Soon your program will become more reliable because it won’t rely on the status of the heap to run correctly.

Getting rid of the String class is a step forward in making your code portable. By avoiding Arduino specific classes and sticking with standard functions, you allow your code to be compiled for other platforms. For example, you could decide to run some parts of your program on your development machine for testing.

And for the very few situations where you must use a String, for example, if a library forces you to use this class (and there are quite a few), use the 8 tips I showed in my previous article.

In most Arduino programs, the principal source of fragmentation is the String class. Because it uses the heap behind the scenes, you don’t realize that allocation happens.

No, this article is not another rant about the String class; on the contrary, we’ll see how we can improve our programs while keeping the String class.

Why bother?

At first, I wanted to write an article to explain why the String class is terrible, and how easy it is to avoid it. However, I realized that advising you to rewrite a huge part of your code is not very pleasant nor helpful.

Indeed, the String class has some design flaws, but it’s not all bad. First, it provides an intuitive syntax that is familiar to Java and C# programmers, so it certainly helps beginners. Second, the String class provides a convenient means to bring a Flash string into the RAM temporarily, as we’ll see.

Avoiding heap allocation is not always possible. Many Arduino cores (most notably the ones for ESP8266 and ESP32) put a very low limit on the stack size, so it’s not possible to put large strings there. In this case, using the String class makes perfect sense.

Finally, some libraries (for example ESP8266WebServer) force us to use the String class. Yes, it drives me crazy too, but I still prefer reusing the library than writing my own.

For all these reasons, we need ways to make efficient programs while still using the String class.

What I mean by “efficient”

Before showing you how to improve the efficiency of the program, I need to clarify what I mean. In this article, “being efficient” means:

1. using as little RAM as possible
2. using as few CPU cycles as possible
3. reducing heap fragmentation

To reduce the RAM usage, we ensure that only one copy of a string is present at any given time.

To use fewer CPU cycles, we avoid moving bytes from one place to another.

To reduce the heap fragmentation, we must reduce the number of allocation and use blocks of constant size.

Code instrumentation

To benchmark the efficiency of the tips presented here, I modified the original String class to make it logs each allocation and each duplication. For example, it logs the calls to malloc(), free(), and strcpy(). It also watches the calls to realloc() which are very important because this function both allocates and moves bytes.

As usual, you’ll find the code samples on GitHub. In this article, each code snippet starts with a number indicating to the corresponding function in the sample project.

Tip 1: Initialize from Flash string

When you define a string literal, the compiler adds it to the “global” area¹, meaning that all the characters are always in the RAM whether you’re using them or not.

Here is an example:

// #1
void sayHello() {
   String s = "hello";
   send(s);
}

The six bytes composing the string “hello” (including the terminator) are present in RAM during the whole execution of the program. When sayHello() runs, the constructor of String makes a copy in the heap.

This program is inefficient because we have two copies of the same strings in the RAM. To improve it, we can prevent the compiler from putting the literal in the RAM, and to keep it in the Flash memory. The PROGMEM attribute allows doing that, but since it’s not very convenient, Arduino provices the F() macro.

Here is the fixed version:

// #2
void sayHello() {
   String s = F("hello");
   send(s);
}

Now, the 6 bytes are copied in the RAM only when sayHello() executes.

Flash strings can significantly improve the efficiency of your program, but they have a few gotchas, as we saw in a previous article.

Tip 2: Use c_str() instead of toCharArray()

Suppose, you have a String s and need to call a function send() that takes an argument of type const char*. There are two ways to convert a String to a char pointer.

The first is to call toCharArray() which copies all the characters to an array:

// #3
char tmp[32]
s.toCharArray(tmp, sizeof(tmp));
send(tmp);

The second way is to call c_str() which returns a pointer to the internal buffer of the String:

// #4
send(s.c_str());

By calling c_str() we avoid a costly duplication, but we must be careful with the returned pointer because it remains valid only if the String is unchanged. Also, be aware that, c_str() can return nullptr.²

Tip 3: Pass by reference

Compare these two function declarations:

// #5
void passByValue(String s);

// #6
void passByRef(const String& s);

We can call both functions with a String instance, but the first one receives a copy, whereas the second receives a reference to the original.

Passing objects by reference is much more efficient than passing by value; there are very few exceptions to this rule.³

Tip 4: If you must pass by value, move the String

If you’re stuck with a library that forces you to pass a String by value, you can avoid the duplication by using the “move semantics” of C++11.

Suppose you constructed a String s; the normal way to pass s to a function is to write:

// #5
passByValue(s);

However, if you know you’ll not use the s after the call, you can “move” the object:

// #7
passByValue(move(s));

move() replicates the standard std::move() that Arduino lacks. This function converts s to a String&&, allowing to call the “move-constructor” of String. This constructor rips off the content of s to create the argument for passByValue(), so we cannot use s after that.

Tip 5: Mutate a String instead of creating temporaries

The + operator offers a nice syntax for composing Strings. Unfortunately, each call to this operator creates one or more temporary (read “hidden”) instances of String.

For example, the following line requires six allocations in the heap:

// #8
String path = String("/api/") + RESOURCE + "?key=" + API_KEY;

To reduce the number of allocations, we need to avoid the + operator. Instead, we can call the += operator which modifies the left-side argument instead of creating a new String.

By rewriting the line above, we can reduce the number of allocations to four:

// #9
String path("/api/");
path += RESOURCE;
path += "?key=";
path += API_KEY;

Tip 6: Call reserve()

We can further reduce the number of allocations by calling reserve() which allocates a buffer of the specified size. If we reserve enough room, the String doesn’t need to reallocate the buffer when we call +=.

The following version makes only two allocations:

// #10
String path;
path.reserve(63);
path += "/api/";
path += RESOURCE;
path += "?key=";
path += API_KEY;

Reducing the number of allocations is not the only benefit of reserve(); it also allow us to control the size of the allocation (64 in the snippet above). That’s excellent because using blocks of constant size reduces the heap fragmentation, as we saw in the previous article.

Tip 7: Pass a null string to the constructor

In the snippet above, we used the default constructor of String, which constructs the instance from an empty string.

In other words:

String s;

is identical to

String s("");

Unfortunately, this constructor allocates a block in the heap, even if we don’t use this block at all. It allocates only one byte, so it’s not a big deal, but we can avoid it by passing a null to the constructor.

The following version requires only one allocation:

// #11
String path((char *)0);
path.reserve(63);
path += "/api/";
path += RESOURCE;
path += "?key=";
path += API_KEY;

NOTE 1: this tip is irrelevant in Arduino cores that implement SSO (Small String Optimization), such as ESP8266’s and ESP32’s.

NOTE 2: some Arduino cores (notably Teensy’s) already pass NULL as the initial value.

Tip 8: Compose the string at compile time

The C++ language allows concatenating string literals at compile time; they simply need to be separated by spaces.

For example:

const char* s = "hello" "world";

is identical to:

const char* s = "helloworld";

To leverage this feature with our previous example, we must substitute RESOURCE and API_KEY with two string literals. The simplest way is to define two macros that the preprocessor expands before the compiler parses the code.

// #12
#define RESOURCE "outdoor_temp"
#define API_KEY "0123456789"
String path = "/api/" RESOURCE "?key=" API_KEY;

By doing all more work at compile time, we reduce the work at runtime.

Of course, this trick only works when you compose a String with constants, but they don’t have to be string literals. Indeed, there are many tricks that the preprocessor can do, but that’s the topic for another article.

Conclusion

More than ever, I invite you to check out the code samples on GitHub because you’ll see the calls to malloc(), realloc(), free() and strcpy() for each of the examples above. I included the output of the program in the README file, so you don’t have to run the program yourself.

The implementation of String is part on the Arduino core, so theoretically the tips shown in this article could be irrelevant for some boards. However, because all the cores were forked from the original one for AVR, they are very likely to have the same String implementation.

I’ll see you soon with another article; meanwhile, check out that repository !

Believe or not, the answers to these three questions are the same: you have a heap fragmentation problem. In this article, we’ll see what it means and how to fix it.

What is the heap?

The “heap” is the area of the RAM where the dynamic memory allocation happens. Every time you call malloc(), you reserve a block of memory in the heap.

Similarly, every time you call new, you reserve a block in the heap. Because new calls malloc() and delete calls free(), everything we’ll see equally applies to new and delete.

Very often, your program allocates heap memory without explicitly calling malloc(). For example, when you create a String object, the constructor allocates some space in the heap to store the characters.

What is heap fragmentation?

When you call free() to release a block, you create a hole of unused memory. After some time, the heap becomes a swiss cheese with many holes.

Here is a simplified view with an imaginary heap of 30 bytes:

The holes count as free memory, so there are 20 bytes available. However, we are unable to allocate 20 bytes because there is not a consecutive block of 20 free bytes.

This phenomenon is what we call “heap fragmentation.” It’s an inefficient utilization of the RAM that prevents a program from using the full capacity of the microcontroller.

When does fragmentation happen?

Suppose you just released a block of memory and therefore created a hole in the heap.

Is that always a problem? There are three possibilities.

First possibility: you allocate another block of the same size. The new block takes the place left by the old one. No hole remains.

Second possibility: you allocate a smaller block. The new block fits in the hole but doesn’t fill it. A small hole remains.

Third possibility: you allocate a larger block. The new block cannot fit in the hole, so it’s allocated further in the heap. A big hole remains.

As you see, only a program that allocates and releases blocks of different size increases the heap fragmentation.

An example

Now that we get the theory, let’s see a concrete example.

Consider a loop() function that downloads the weather forecasts from a web server. It first saves the response a big String; then it extracts the date, the city, the temperature, the humidity, and the weather description in five Strings of various size.

String serverResponse;
String date, city, temperature, humidity, description;
void loop() {
   serverResponse = downloadFromServer();
   date = extractDate(serverResponse);
   city = extractCity(serverResponse);
   temperature = extractTemperature(serverResponse);
   description = extractDescription(serverResponse);
}

The first iteration of loop() is OK: it allocates the Strings in the heap but doesn’t release them, so no fragmentation happens.

Then, each iteration creates new Strings to replace the old ones. The new Strings allocate new blocks and the old Strings release the old blocks.

Here is the problem: every time the server returns a different response, the sizes of the blocks change. As we saw, allocation of varying sizes creates holes in the heap, which increases the fragmentation.

Measuring the fragmentation

There are several formal definitions for the fragmentation; in this article, I’ll use this simple definition:

Let’s try some numbers in this formula. Suppose you have 1KB of free RAM.

• At 0% (no fragmentation), you can allocate 1KB in one shot.
• At 25%, you can allocate 750B in one shot.
• At 50%, you can only allocate 500B in one shot.
• At 75%, you can only allocate 250B in one shot.

A value of 50% or more is considered high and can seriously impede your program, as we’ll see.

How fragmentation evolves over time

Now that we have a formal definition, let’s write a program that will show the evolution of the fragmentation over time.

Computing the fragmentation

To compute the fragmentation percentage, we apply the formula and multiply by 100:

float getFragmentation() {
  return 100 - getLargestAvailableBlock() * 100.0 / getTotalAvailableMemory();
}

As you can guess, getLargestAvailableBlock() returns the size of the largest allocable block, and getTotalAvailableMemory() returns the total free memory.

Writing these two functions is the trickiest part of this program because they are dependent on the platform. In the code samples, I implemented a version for AVR (Arduino UNO et al.) and another for ESP8266.

Drilling holes

To produce fragmentation, we saw that we could use a few Strings of various size and replace them repeatedly.

The easiest way to do that is to have an array of String and to replace them with random values:

String strings[NUMBER_OF_STRINGS];

for (String &s : strings)
   s = generateRandomString();

As the name suggests, generateRandomString() returns a String whose length varies from one call to the other:

String generateRandomString() {
  String result;
  int len = random(SMALLEST_STRING, LARGEST_STRING);
  while (len--) result += '?';
  return result;
}

This program roughly simulates the weather forecast example.

The results

I obtained the following graph with 20 strings whose length varied from 10 to 50 characters. The program ran on an Arduino UNO.

As you see, when the program starts, the fragmentation is close to zero and then increases irregularly until it stabilizes at about 70%.

I encourage you to tweak the settings to see the effect on the fragmentation. In particular, you’ll see that when SMALLEST_STRING and LARGEST_STRING are equals, i.e., if the Strings are all of the same sizes, no fragmentation occurs.

Why is heap fragmentation bad?

We saw how fragmentation increases, now let’s talk about the consequences of a high fragmentation level.

Consequence 1: Unreliable program

By definition, a high fragmentation level means you have a lot of free memory, but you can only allocate small blocks. If your program needs a bigger block, it will not get it and will stop working.

Consequence 2: Degraded performance

A highly fragmented heap is slower because the memory allocator takes more time to find the best hole, the so-called “best-fit.”

If it’s so huge, why nobody talks about it?

Heap fragmentation is a solved problem for most programmers, but not for us Arduino programmers. Let’s see how other platforms handle the problem.

Solution 1: Virtual memory

The programs running on our computers use Virtual Memory. The value of the pointer is not the physical location in the RAM; instead, the CPU translates the address on the fly. This decoupling allows defragmenting the RAM without moving anything but requires dedicated hardware that we do not have on our microcontrollers.

Solution 2: Optimized allocators

Either as part of the standard library or as a linked library, C++ programs running on a computer embeds a heap allocator that is much more efficient than what we have on our Arduinos.

The most common optimization is to gather small blocks into bins: one bin for blocks of 4 bytes, one bin for 8 bytes, etc. Thanks to this technique the small objects don’t contribute to and are not affected by the fragmentation.

Solution 3: Short string optimization

Even if the C++ standard doesn’t mandate it, all implementations of std::string support the “Small String Optimization,” or SSO. std::string stores short strings locally and only uses the heap for long strings.

By reducing the number of small objects in the heap, the SSO reduces the fragmentation. Unfortunately, the String class doesn’t perform SSO in Arduino.

Solution 4: Heap compacting

In languages with managed memory, the garbage collector moves the memory blocks to squash the holes.

We cannot use this technique in C++ because moving a block would change its address, so all pointers to this block would be invalid.

Solution 5: Memory pool

Instead of allocating many small blocks, a program can allocate only one big block and divide it as it needs. Within this block, the program is free to use any allocation strategy.

For example, ArduinoJson implements this technique with DynamicJsonBuffer.

So what can I do to reduce heap fragmentation?

None of these techniques applies to our Arduino programs, which means we have to code in a way that reduces the fragmentation.

Strategy 1: Avoid heap (in particular, avoid String)

In many cases, we can avoid dynamic allocation. Instead of allocating objects in the heap, we place them in the stack or in the globals. By design, these two areas are not fragmented.

For example, we could replace all String objects with plain old char[]. Not only we would reduce the fragmentation, but we would also create a smaller and faster executable.

Strategy 2: Short object lifetime

Short-lived objects have a small impact on the heap fragmentation. They rapidly come and go, leaving the heap in the same state.

Long-lived objects, however, have a substantial impact on the heap fragmentation. They book their room and stick here for a long time, leaving the heap with an unmovable block in the middle.

So, if you still needed another reason to avoid global variables, there you have it.

Strategy 3: Constant allocation

As we saw, repeated allocations of the same size don’t cause fragmentation; so, we could keep our objects in the heap but always use the same size.

For example, if we have a string that can have between 10 and 100 characters, we could always reserve 100 characters:

myString.reserve(100);

As curious as it sounds, allocating more memory than strictly necessary allows more efficient utilization of the RAM.

Conclusion

This article was unusually long, I hoped you’ve gone through it.

Here is what you need to remember:

1. Fragmentation is an inefficient utilization of the RAM.
2. Arduino programs, more than others, are affected by fragmentation.
3. It’s our responsibility as programmers to fight against fragmentation.

As usual, you’ll find the source code of the examples on GitHub.

I’ll see you soon with another article!

What if I tell you that using NULL is considered as a code smell for experienced C++ developers? And, what if I tell you that most C++ coding standards now forbids using NULL entirely?

Read on if you want to know why!

Why do we use NULL in the first place?

Very often, we need a way to express that a variable contains no value. In a C program, we do that by declaring a pointer and make it refer to a special address that can never point to something real: zero. For instance, we could declare an empty color string like that:

const char* color = 0;

But that wouldn’t be very clear, would it? That’s why C programmers insist on using the symbol NULL to identify an empty pointer clearly. So, to follow best practices, we should write:

const char* color = NULL;

As long as we stay in the realm of the C language, everything is fine and you can (and should) still use NULL.

What most people think NULL is?

I believe most people think that NULL is defined like that:

#define NULL ((void*)0)

Indeed, it is the right definition for the C language. It works because the language implicit converts void* to T* for any type T.

C++, however, with its strong-typing philosophy, doesn’t implicitly convert from void* to T*.

Let’s try:

#define NULL ((void*)0)
const char* color = NULL;

A C compiler accepts these two lines without any problem, but a C++ compiler returns the following error:

error: invalid conversion from 'void*' to 'const char*' [-fpermissive]

To work around this error, we would have to cast NULL explicitly:

#define NULL ((void*)0)
const char* color = reinterpret_cast<const char*>(NULL);

Ugly, isn’t it?

What NULL really is?

We saw that the definition of NULL in C++ could not be the same as the definition in C. So, what is it?

Well, it is very likely to be defined like that:

#define NULL 0

I know, it’s quite disappointing… The C++ standard allows other definitions but, from my experience, it’s often defined to 0.

Why does that make a difference?

OK, NULL is not a void* but an int, so what? No big deal!

Well, maybe not a big deal, but still very annoying in certain situations.

For example:

const char *color = NULL;
String colorStr1(color);
String colorStr2(NULL);

At first sight, colorStr1 and colorStr2 look identical. So, if we compare them, they should be equal, right?

if (colorStr1== colorStr2) {
  Serial.println("colorStr1 == colorStr2");
} else {
  Serial.println("colorStr1 != colorStr2");
}

If you run this program, it displays colorStr1 != colorStr2, proving that the Strings differ.

Let’s print them:

Serial.print("colorStr1 = ");
Serial.println(colorStr1);
Serial.print("colorStr2 = ");
Serial.println(colorStr2);

These four line produces the following output:

colorStr1 =
colorStr2 = 0

Strange, isn’t it?

Problem 1: NULL messes with functions overloading

We saw that the definition of NULL exposes an inconsistency in the String class. To understand the reason, let’s look at a simpler version of the same problem. We declare two functions, like that:

void f(const char*);
void f(int);

Since these functions have the same name, they are overloads, meaning that the compiler calls one or the other depending on the type of the argument. Remember that function overloading is available in C++, but not in C.

So, guess which overload is chosen when we call:

f(NULL);

If you’re like me, your first deduction was that this line should call the overload taking a char-pointer. However, after what we saw earlier, you should understand why it calls the other overload. Indeed, as far as the compiler is concerned, it’s identical to calling f() like that:

f(0);

How is that related to the String problem? Simple! By passing NULL to the constructor, we just called the wrong overload, the one that takes an integer and converts it to a string.

Problem 2: NULL messes with template type deduction

We saw that the strange definition of NULL pushes the compiler to select the wrong overload but is it the only problem? Unfortunately no, it also confuses the template type deduction. Imaging we declare this template function:

template<typename T>
void printValue(T value);

Then, we specialize it for integer and pointer:

template <>
void printValue<int>(int value) {
  Serial.print("Integer: ");
  Serial.println(value, DEC);
}

template <>
void printValue<void *>(void *value) {
  Serial.print("Pointer: 0x");
  Serial.println((intptr_t)value, HEX);
}

Now, if we call printValue(NULL), it will print:

Integer: 0

I know there are better ways to solve this problem; I show you this example because it illustrates the problem with NULL. With this program, we see that the compiler deduces the template type to be an integer, while we imagined it would be some pointer type.

Let’s see how this type deduction thing can affect your program on the real life. Imaging you use ArduinoJson 5, and you write something like that:

DynamicJsonBuffer jb;
JsonObject& obj= jb.parseObject("{\"id\":0}");
if (obj["id"] == NULL) {
  Serial.println("ERROR: id is missing");
}

This program displays an error, even if the key id is present in the object, because the compiler believes you wrote:

if (obj["id"] == 0) {

So, you see, this template type deduction can have real implications.

By the way, if you want to fix this program, see JsonObject::containsKey().

The solution

I told you that C++ programmers banned NULL from their code-base, but what do they use instead?

Instead of NULL, they use nullptr, a new keyword introduced in C++11.

• Like NULL, nullptr implicitly converts to T* for any type T.
• Unlike NULL, nullptr is not an integer so it cannot call the wrong overload.
• Unlike NULL, nullptr has its own type, nullptr_t, so the compiler makes correct type deductions.

Are there any drawbacks to using nullptr instead of NULL? No, unless you target old compilers that don’t support C++11, which is very unlikely.

Mitigations

Before wrapping up, I’d like to clarify something I skipped to simplify this article.

The C++ standard committee knows there is a lot of existing code using NULL that would become safer if it was using nullptr instead. So, in the C++11 standard, they allowed the definition of NULL to be:

// either
#define NULL 0
// or
#define NULL nullptr
// both are legal in C++11

From my experience, the standard library defines NULL as 0, not as nullptr. However, what the C++11 standard allows us it to replace it in our code-base to make our old code safer with a single line in the right header.

Compiler writers are also well aware of the problems with NULL, so they implemented a special case allowing them to issue a warning when appropriate. For example, when we call f(NULL) as we did earlier, the compiler produces the following warning:

warning: passing NULL to non-pointer argument 1 of 'void f(int, int)' [-Wconversion-null]

You always look at the warnings, right?

Conclusion

I could have written this article with just one single line:

Don’t use NULL, use nullptr instead

That’s not the way I work. I don’t just tell people what to do; I explain why they should do it. Understanding the rationale behind the language features is what will make you a great C++ developer, so stay tuned to read more articles like this one.

By the way, if you want to practice at home, download the samples for this article on github.com/bblanchon/cpp4arduino.

See you soon!

Why this optimization?

Have you ever written the exact same string several times in the same program? I know it happens to me all the time. For example, I could write:

color = "black";

and, later in the code, I would write:

strcmp(color, "black");

As you can see, I wrote the string literal “black” twice, does this mean that the program contains two copies of “black”? More importantly, does it mean that the program loads two copies in the RAM?

Fortunately, the answer is no to the two questions. Thanks to the string interning optimization, only one copy of each literal is stored in the program (i.e., in the Flash memory), and so only one is loaded in the RAM.

Demonstration

Demonstrating that string interning stores only one copy of two identical string literals is straightforward: we just need to compare the pointers. If the pointers refer to the same address, it means that there is only one copy in the RAM.

Here is a simple program that you can run on your Arduino:

const char* s1 = "black";
const char* s2 = "black";
Serial.println((intptr_t)s1);
Serial.println((intptr_t)s2);

As you can see, I cast the pointer to intptr_t to display its value, i.e. the address it points to. intptr_t is an integer whose size matches the size of a pointer. On most machines, intptr_t is identical to int.

On my Arduino UNO, the program above displays:

s1 = 309
s2 = 309

As you can see, the two values are identical, proving that the optimization worked.

An optimization performed by the compiler

In C++, the compiler performs the string interning, so the deduplication can only happen at compile time. It means that if your program assembles to identical strings in RAM, there would be two copies. In other words, the optimization works only for the strings known at compile time: the string literals.

In other languages, like C# or Java, the string interning also happens at runtime, because the .NET Runtime or the Java Virtual Machine implements this optimization. In C++, we don’t have a runtime environment that could perform this optimization, so we only have it at compile time.

If for some odd reason, you want to disable this optimization, GCC (the compiler behind Arduino) supports the flag -fno-merge-constants. By the way, the same optimization deduplicates floating point literals.

Defeating the optimization

Unfortunately, this optimization is very fragile: there are many ways to break it. We saw that it works fine with const char*:

// Number of copies: 1 in Flash, 1 in RAM
const char* s1 = "black";
const char* s2 = "black";

If instead, we change the type to char[], the program makes a copy of the literal when it creates the variables:

// Number of copies: 1 in Flash, 3 in RAM
const char s1[] = "black";
const char s2[] = "black";

Similarly, if we change the type to String, the constructor makes a copy of the string:

// Number of copies: 1 in Flash, 3 in RAM
String s1 = "black";
String s2 = "black";

Flash String

Do you think the compiler deduplicates Flash strings (also known as Progmem strings) in the same way? Unfortunately, no.

Again, it’s very easy to verify, we just need to reuse the same snippet, changing only the types of the variables:

// Number of copies: 2 in Flash, 0 in RAM
const char s1[] PROGMEM = "black";
const char s2[] PROGMEM = "black";
Serial.println((intptr_t)s1);
Serial.println((intptr_t)s2);

When I run this program on my Arduino UNO, it displays:

s1 = 122
s2 = 116

As you can see, the addresses are different, proving that the optimization didn’t work.

Unlike our previous examples, these addresses refer to the Flash memory, not to the RAM. Indeed, the attribute PROGMEM instructs the compiler not to load the string in the RAM but, instead, to point to the location in the “program memory.”

You could be tempted to keep the PROGMEM attribute and change the type to char* instead of char[], but if you do that, the compiler simply ignores the attribute:

// WRONG: doesn't do what you think!
// Number of copies: 1 in Flash, 2 in RAM
const char s1* const PROGMEM = "black";
const char s2* const PROGMEM = "black";

Now, what about the macro F() that we see in all Arduino examples, it’s good, right? I’m afraid it’s not good at all… I would even say that it’s worse because it gives you a false sense of rightfulness. Indeed, the syntax is so close to the classic string literal that we believe it behaves the same way.

Again, it’s very easy to demonstrate:

// Number of copies: 2 in Flash, 0 in RAM
const __FlashStringHelper* s1 = F("black");
const __FlashStringHelper* s2 = F("black");

Sadly, many people believe they are following best practices by calling F() everywhere, but in reality, they are bloating their programs with useless copies of the same string.

This limitation is one of the many reasons I avoid Flash strings in my programs; I only use them for long, unique, and rarely used strings, like log messages.

Comparing strings

Now that we’ve seen the benefits of string interning and all the ways we can defeat the optimization, let’s talk about one major pitfall: the comparison of strings with the operator ==.

If you use the operator == on pointer types, it compares the addresses, not the content. As we saw, two identical strings can have the same address when string interning works, or different addresses when string interning doesn’t apply.

Let see an example:

const char* color = "black";
if (color == "black") { // true because of string interning
  // ...
}

All is well, but it stops working as soon as one of the strings is not included in the optimization, like in the example:

const char color[] = "black";
if (color  == "black") { // false because color holds a copy
  // ...
}

That is why it is crucial never to use the operator == to compare strings in char*. Instead, we must use strcmp(), a function from the C standard library that compares characters one by one and returns 0 if the two strings match (it also returns -1 or +1 depending on the lexicographical order, but it’s not our concern here).

const char color[] = "black";
if (strcmp(color, "black") == 0) { // true because it compare each character
  // ...
}

Admittedly, this program is less readable, less expressive, and more error-prone, but that’s our legacy from the C language.

An alternative is to use the String class. Indeed, this class overloads the operator ==, so you can safely compare Strings:

String color = "black";
if (color  == "black") { // true because it calls String::operator==()
  // ..
}

However, that’s not a reason to use this class everywhere, because it comes with its own baggage, namely heap allocation and string duplication, but that’s a topic for another article.

Conclusion

String interning is a powerful optimization, but it can be easily defeated. In particular, beware of the macro F() that pretends to work like a string literal but bloats your program with multiple copies of the same string.

I thought you might want to run the same tests on your microcontroller, so I uploaded to GitHub a sample program that shows the addresses of strings of various types. You can find it at github.com/bblanchon/cpp4arduino.

That’s all I have to say about string interning. I hope you learned something today; if so, share with your friends. If you want more articles like this, you can subscribe to the mailing list. See you soon!