sprintf()<\/code> and snprintf()<\/code>. This allows you to combine different data types in a character array, display results in tabular form, select number systems and much more.<\/p>\r\n\r\nThis article is intended to provide an overview of the various possibilities of sprintf()<\/code> or snprintf()<\/code> and their siblings sprintf_P()<\/code>, snprintf_P()<\/code> and printf()<\/code>. Some board packages do not support the formatting of decimal numbers using these functions. In these cases, you can take a detour via dtostrf()<\/code>.<\/p>\r\n\r\nThe options for formatting output with Serial.print()<\/code> and escape sequences are very limited. But to bring all formatting options together in one place, I will also go into this.<\/p>\n\nWhat you can expect in this article:<\/p>\r\n
\r\n- Formatted output with the Serial.print() options<\/a><\/li>\r\n
- escape sequences<\/a><\/li>\r\n
- Formatted output with sprintf() Co<\/a>
\r\n\r\n- Overview of the functions<\/a>\r\n
\r\n- sprintf()<\/a><\/li>\r\n
- snprintf()<\/a><\/li>\r\n
- printf() \/ Serial.printf()<\/a><\/li>\r\n
- Save SRAM with sprintf_P and snprintf_P()<\/a><\/li>\r\n<\/ul>\r\n<\/li>\r\n
- Using format specifiers<\/a>\r\n
\r\n- The conversion specifier<\/a><\/li>\r\n
- The sub-specifiers<\/a><\/li>\r\n<\/ul>\r\n<\/li>\r\n
- Example sketches<\/a><\/li>\r\n<\/ul>\r\n<\/li>\r\n
- Formatted output with dtostrf()<\/a>\r\n
\r\n- Example sketch dtostrf()<\/a><\/li>\r\n<\/ul>\r\n<\/li>\r\n
- Example sketch for tabular output<\/a><\/li>\r\n<\/ul>\r\n\n
Formatted output with the Serial.print() options<\/h2>\n\n
If you pass a number to the function Serial.print()<\/code> or Serial.println()<\/code>, you can format it using a second parameter:<\/p>\r\nSerial.print(val, format);<\/code><\/p>\r\nFor format<\/code> you have the following options: <\/p>\r\n\r\n- You can define the number base for integers<\/strong>:
\r\n- HEX<\/strong>: Base 16, hexadecimal system<\/li>\r\n
- DEC<\/strong>: Base 10, decimal system (standard),<\/li>\r\n
- OCT<\/strong>: Base 8, octal system<\/li>\r\n
- BIN<\/strong>: Base 2, binary system<\/li>\r\n<\/ul>\r\n<\/li>\r\n
- For decimal numbers,<\/strong> you specify the number of decimal places (default: 2). The last digit is rounded. <\/li>\r\n<\/ul>\r\n
Here is a small example sketch:<\/p>\r\n\n
void setup() {\r\n Serial.begin(115200);\r\n \/\/ delay(1000); \/\/uncomment if your serial monitor is blank\r\n int a = 193;\r\n float f = PI; \/\/ PI = 3.1415926...\r\n Serial.println(\"Output of 193 (dec.):\");\r\n Serial.print(\"Hexadecimal: \"); Serial.println(a, HEX);\r\n Serial.print(\"Decimal : \"); Serial.println(a, DEC);\r\n Serial.print(\"Octal : \"); Serial.println(a, OCT);\r\n Serial.print(\"Binary : \"); Serial.println(a, BIN);\r\n Serial.println(\"\\nOutput of Pi:\"); \/\/ here, I already used an escape sequence\r\n Serial.print(\"1 decimal place : \"); Serial.println(f, 1);\r\n Serial.print(\"2 decimal places: \"); Serial.println(f, 2);\r\n Serial.print(\"3 decimal places: \"); Serial.println(f, 3);\r\n}\r\n\r\nvoid loop() {}<\/pre>\r\n\nAnd here is the output:<\/p>\r\n\n![\"Formatted](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2024\/08\/output_serial_print_format.png\")
<\/a>Formatted output with Serial.print()<\/figcaption><\/figure>\n\nSaving SRAM with the F-Macro<\/h4>\n\n
Constant text, i.e. everything in quotation marks in the above sketch, is an SRAM eater. With the F macro, you ensure that the character string to be output is not stored in the SRAM but in the flash: <\/p>\r\n
Serial.println(F(\"Output String\"));<\/code><\/p>\r\nThis has nothing to do with formatting, but it should be noted here for the sake of completeness because I will discuss a corresponding variant of the sprintf()<\/code> function below. <\/p>\r\n\nEscape sequences<\/h2>\n\n
Escape sequences offer you further options for formatting the output of Serial.print()<\/code> or outputting special characters. The use of escape sequences is not limited to Serial.print()<\/code>, but can be used in all string objects or character arrays. <\/p>\r\n\nvoid setup() {\r\n Serial.begin(115200);\r\n \/\/ delay(1000); \/\/uncomment if your serial monitor is blank\r\n Serial.print(\"\\\\n outputs a line feed \\n\");\r\n Serial.println(\"\\\\r outputs a carriage return \\r\"); \r\n Serial.println(\"\\\\xXX outputs the ASCII character of 0xXX, e.g. \\\\x41: \\x41\");\r\n Serial.println(\"\\\\uXXXX outputs the unicode character of 0xXXXX, e.g. \\\\u21C4: \\u21C4\");\r\n Serial.println(\"\\\\t outputs a tab, e.g.: 12\\t34 \");\r\n Serial.println(\"\\\\\\\" outputs \\\"\");\r\n Serial.println(\"\\\\\\' outputs \\'\");\r\n Serial.println(\"\\\\\\\\ outputs \\\\\");\r\n Serial.print(\"Serial.println() of \"); int numOfChars = Serial.println(\"12345\");\r\n Serial.print(\" ...prints \"); Serial.print(numOfChars); Serial.println(\" characters!\");\r\n}\r\n\r\nvoid loop() {}\r\n<\/pre>\r\n\nThe output is:<\/p>\r\n\n![\"Formatted](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2024\/08\/output_escape_seq_eng.png\")
<\/a>Output of escape_sequences.ino<\/figcaption><\/figure>\n\nIn the last line, you can see that Serial.println(\"...\")<\/code> generates two more characters than you might expect. This is due to the “hidden” carriage return and line feed. The function corresponds to Serial.print(\"...\\r\\n\")<\/code>. <\/p>\r\n\nFormatted output with sprintf() Co<\/h2>\n\nOverview of the functions<\/h3>\n\n
With the functions sprintf()<\/code>, snprintf()<\/code> printf()<\/code> and snprintf_P()<\/code> you have incomparably more powerful tools at your disposal.<\/p>\r\n\nsprintf()<\/h4>\n\n
sprintf()<\/code> is defined as follows:<\/p>\r\nint sprintf ( char *buf, const char *format, ... );<\/code><\/p>\r\nHere, format<\/code> contains the characters to be output and, if necessary, placeholders for variables with formatting instructions. These placeholders are also called format specifiers. They can be recognized by the preceding percent sign. The variables themselves are appended in the order in which their format specifiers appear, separated by commas: <\/p>\r\nsprintf(buf, \"... format_specifier_1 ... format_specifier_2 ... format_specifier_3....\", variable_1, variable_2, variable_3, ..,);<\/code><\/p>\r\nThe result is saved in the character array buf<\/code> and can be output via Serial.print()<\/code>.<\/p>\r\n\nsnprintf() vs. sprintf()<\/h4>\n\n
The function sprintf()<\/code> writes the character string defined in format<\/code> to buf<\/code>, regardless of whether you have reserved enough memory for it or not. If buf<\/code> is too small, you simply write beyond it – with unforeseeable consequences (see below). <\/p>\r\nThe snprintf()<\/code> function is safer. It differs from sprintf()<\/code> by the concrete specification of the number of characters to be read in (here: “n”): <\/p>\r\nint snprintf ( char *buf, size_t n, const char * format, ... );<\/code><\/p>\r\nIf you specify “n” with sizeof(buf)<\/code>, you are on the safe side. At worst, part of what you wanted to spend will lost, but at least you won’t have any problems due to unwanted overwriting of memory. <\/p>\r\nEven though I recommend snsprintf()<\/code>, I will use sprintf()<\/code> in the rest of the article to focus on the formatting options. <\/p>\r\n\nprintf() \/ Serial.printf()<\/h4>\n\n
You may be wondering whether you can save yourself the detour via the character array buf<\/code>. In fact, you can use the Serial.printf()<\/code> function on some microcontroller boards (e.g. ESP32), but not, for example, on the classic AVR-based Arduinos. <\/p>\r\nint Serial.printf(const char * format, ....);<\/code><\/p>\r\nIf the board of your choice supports printf()<\/code>, then you can simply transfer everything from sprintf()<\/code>. However, you should consider whether you really want to write your sketches board-specifically. <\/p>\r\nThe printf()<\/code> function (i. e. not: Serial.printf()<\/code>) is generally available:<\/p>\r\nint printf (const char * format, ... );<\/code><\/p>\r\nHowever, you cannot simply generate an output on the serial monitor because its input and output is not defined. If you are interested in details and a workaround, look here<\/a> and here<\/a>. <\/p>\r\n\nSaving SRAM with sprintf_P() and snprintf_P()<\/h4>\n\n
With the variants sprintf_P()<\/code> and snprintf_P()<\/code> you can achieve that format<\/code> is not read from the SRAM, but from flash:<\/p>\r\nint sprintf_P ( char *buf, const char* PSTR(format), ... );<\/code><\/p>\r\nint snprintf_P ( char *buf, size_t n, const char* PSTR(format), ... );<\/code><\/p>\r\nThe PSTR macro is similar to the F macro. However, the latter is incompatible with sprintf_P()<\/code> and snprintf_P()<\/code>. If you want to know exactly: The F macro returns __FlashStringHelper*<\/code>, but sprintf_P()<\/code> and snprintf_P()<\/code> expect const char*<\/code> as a parameter. And this is exactly what the PSTR macro generates. <\/p>\r\n\nUsing format specifiers<\/h3>\n\n
A format specifier consists of the percent sign, some optional sub-specifiers and the conversion specifier:<\/p>\r\n\n
% [flags] [width] [.precision] [length] conversion specifier<\/p>\r\n\n
The conversion specifier<\/h4>\n\n
You use the conversion specifier to define what you want to output the placeholders as. The conversion specifier must, of course, be compatible with the variable to be output. Here are the options: <\/p>\r\n\n![\"Options](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2024\/08\/conv_format_specifier__eng.png\")
<\/a>Options for the conversion specifier<\/figcaption><\/figure>\n\nNot all conversion specifiers are supported by all board packages. Users of AVR-based boards, e.g. Arduino UNO R3, classic Arduino Nano etc., will miss the options for decimal numbers (decimal numbers = fixed-point and floating-point numbers) the most. There is a detour via dtostrf()<\/code>, which we will come to below. <\/p>\r\n\nThe sub-specifiers<\/h4>\n\n
You have the following options for the flag<\/strong>:<\/p>\r\n\n![\"Formatted](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2024\/08\/sprintf_flags_engl.png\")
<\/a>Flags for the format specifier<\/figcaption><\/figure>\n\nThe width<\/strong> is the minimum width for the character string defined in the format specifier. If the character string is longer than defined in “width” or the same length, then “width” has no effect. If the character string is shorter than width, the difference is filled with spaces or zeros (see flags). <\/p>\r\n\nThe effect of precision<\/strong> depends on the conversion specifier:<\/p>\r\n\r\n- f, e, E, a, A<\/strong>: the precision specifies the number of decimal places.<\/li>\r\n
- g, G<\/strong>: the precision specifies the total number of digits before and<\/em> after the decimal point.<\/li>\r\n
- d, i, o, u, x, X<\/strong>: the precision specifies the minimum width. Any spaces are filled with leading zeros. <\/li>\r\n
- s<\/strong>: the precision specifies the maximum number of characters to be output. Characters exceeding this are truncated. <\/li>\r\n<\/ul>\r\n\n
The effect of the length<\/strong> also depends on the conversion specifier:<\/p>\r\n\r\n- l (small “L”): <\/strong>turns d, i, o, u, x, X into a “long int” or an “unsigned long int”.<\/li>\r\n
- ll (small “Ls”)<\/strong>: turns d, i, o, u, x, X into a “long long int” or an “unsigned long long int”.<\/li>\r\n
- L<\/strong>: turns f into a long double.<\/li>\r\n<\/ul>\r\n\n
Example sketches<\/h3>\n\nBasic example<\/h4>\n\n
The following sketch illustrates how to use the format specifiers in sprintf()<\/code>, snprintf()<\/code> and snprintf_P()<\/code>. I will initially dispense with sub-specifiers: <\/p>\r\n\nvoid setup() {\r\n Serial.begin(115200);\r\n char buf[60]; \/\/ more than enough capacity\r\n int a = 42;\r\n char str[] = \"universe\";\r\n sprintf(buf, \"%d is the meaning of life, %s %s\", a, str, \"and everything\");\r\n Serial.println(buf);\r\n snprintf(buf, 26, \"%d is the meaning of life, %s %s\", a, str, \"and everything\");\r\n Serial.println(buf);\r\n snprintf(buf, sizeof(buf), \"%d is the meaning of life, %s %s\", a, str, \"and everything\");\r\n Serial.println(buf);\r\n snprintf_P(buf, sizeof(buf), PSTR(\"%d is the meaning of life, %s %s\"), a, str, \"and everything\");\r\n Serial.println(buf);\r\n}\r\n\r\nvoid loop() {}<\/pre>\r\n\nHere is the output:<\/p>\r\n\n![\"\"](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2024\/08\/output_spintf_basics.png\")
<\/a>Output of sprintf_snprintf_snprintf_P_basic.ino<\/figcaption><\/figure>\n\nCalculation of buf<\/h5>\n\n
When calculating the size of the “target string” (buf<\/code>), it should be noted that the number of characters to be output is taken as the basis and not the size of the variable. Example: An integer uses 2 bytes on an AVR-based Arduino. However, how much memory the integer value requires in buf<\/code> depends on the number of digits and possibly on the formatting parameters (additional signs, spaces, “0x” etc.). <\/p>\r\nDon’t forget to reserve one character for the null terminator.<\/p>\r\n
Here you can see what can happen if you define a size for buf<\/code> that is too small:<\/p>\r\n\nvoid setup() {\r\n Serial.begin(115200);\r\n char buf[5]; \r\n char buf2[6];\r\n char str[] = \"1234567890\";\r\n sprintf(buf, \"%s\", str);\r\n Serial.print(\"buf : \");\r\n Serial.println(buf);\r\n sprintf(buf2, \"%s\", str);\r\n Serial.print(\"buf2: \");\r\n Serial.println(buf2);\r\n Serial.print(\"buf : \");\r\n Serial.println(buf); \r\n}\r\n\r\nvoid loop() {}<\/pre>\r\n\nThe output, tested on an Arduino Nano, is:<\/p>\r\n\n![\"\"](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2024\/08\/output_wrong_buf_size.png\")
<\/a>Output of wrong_buf_size.ino on an Arduino Nano<\/figcaption><\/figure>\n\nAs you can see, the error only becomes apparent after the string has been written to buf2<\/code> and its remainder, which does not fit into the reserved memory, “protrudes” into the memory reserved for buf<\/code>. <\/p>\r\n\nOn an ESP32, the SRAM is organized differently. Here, buf<\/code> is overwritten “coming from the other side”: <\/p>\r\n\n![\"\"](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2024\/08\/output_wrong_buf_size_esp32-1.png\")
<\/a>Output of wrong_buf_size.ino on an ESP32<\/figcaption><\/figure>\n\nExample: formatted output of integers<\/h4>\n\n
The next example sketch plays with some sub-specifiers for integers.<\/p>\r\n\n
\r\nvoid setup() {\r\n Serial.begin(115200);\r\n char buf[50];\r\n int a = 193;\r\n sprintf(buf, \"Default integer (signed) : %i\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Defined width, right-justify : %5d%5d\", a, a+a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Defined width, left-justify : %-5d%-5d\", a, a+a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Defined width, preceeding zeros: %05d\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"With sign : %+d\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Hexadecimal, lowercase : %x \", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Hexadecimal, uppercase : %X\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Hexadecimal, with \\\"0X\\\" : %#X\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Octal : %o\", a);\r\n Serial.println(buf);\r\n Serial.print(\"No binary option for sprintf : \"); Serial.println(a, BIN);\r\n sprintf(buf, \"Long integer : %ld\", 1234567890);\r\n Serial.println(buf);\r\n sprintf(buf, \"%-31s%s%05d\", \"Alternative output\", \": \", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Address of buf : %p\", buf);\r\n Serial.println(buf);\r\n}\r\n\r\nvoid loop() {}<\/pre>\r\n <\/p>\r\n<\/div>\r\n\n
Because I wanted to focus on the essentials, I have not used the full range of formatting options, for example to align the colons. However, to show how this can be done, I have made an exception for the formatting of the penultimate output line (“Alternative output”). <\/p>\r\n
Here is the output:<\/p>\r\n\n![\"\"](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2024\/08\/output_sprintf_integers_engl.png\")
<\/a>Ausgabe von sprintf_integers.ino<\/figcaption><\/figure>\n\nExample: formatted output of decimal numbers<\/h4>\n\n
As already mentioned, formatting of decimal numbers using sprintf()<\/code> does not work on the AVR-based microcontroller boards. I have tried the following sketch on an ESP32 board: <\/p>\r\n\nvoid setup() {\r\n Serial.begin(115200);\r\n char buf[60];\r\n double a = PI; \/\/ PI = 3.1415926...\r\n sprintf(buf, \"Default double : %f\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Specified length and precision: %6.2f\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Scientific notation, lowercase: %e\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \" \\\" , with length and precision: %10.3e\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Scientific notation, uppercase: %E\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Shortest, lowercase : %g\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Shortest, lowercase : %g\", 1000000 * a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Shortest, uppercase : %G\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Shortest, uppercase : %G\", 1000000 * a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Hex floating point, lowercase : %a\", a);\r\n Serial.println(buf);\r\n sprintf(buf, \"Hex floating point, uppercase : %A\", a);\r\n Serial.println(buf);\r\n}\r\n\r\nvoid loop() {}\r\n<\/pre>\r\n\n
![\"\"](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2024\/08\/output_sprintf_floats_eng-1.png\")
<\/a>![\"\"](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2024\/08\/output_dtostr_eng.png\")
<\/a>