How to use formatting strings in user-defined functions?

Question

I want to write a function to print characters on an LCD in a similar way that printf/sprintf does using formatting strings.

Discontinuity

How is what you want to do different from using fprintf() with a file stream that is opened so you can write to the LCD? How is what you want different from using snprintf() to format a string that you can then convey to the LCD using some other function? (Or, in other words, what haven't you told us about your situation? How are you going to get the information to the LCD?) – Trinee

Answer 1

You may use sprintf function to format the strings and print to LCD.

 char buffer[50]; 
 int a = 10, b = 20, c; 
 c = a + b; 
 sprintf(buffer, "Sum of %d and %d is %d", a, b, c); 

Now the buffer will have the formatted strings

Danette

Answer 2

You could write a variadic function and pass the parameters on to vsnprintf():

#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>

void display(int foo, int bar, char const *format, ...)
{
    va_list arglist;
    va_start(arglist, format);

    int length = vsnprintf(NULL, 0, format, arglist);
    char *buffer = malloc(length * sizeof *buffer); 
    vsnprintf(buffer, length, format, arglist);
    va_end(arglist);

    puts(buffer);
    free(buffer);
}

int main(void)
{
    display(42, 13, "%s %d %f", "Hello", 99, 100.13);
}

Escudo

Great usage of vsnprintf! Your example is perfect for PCs, but not perfect for memory-constrained or real-time environments such as microcontrollers. I explain more in detail here: https://mcmap.net/q/21098/-how-to-use-formatting-strings-in-user-defined-functions. – Balladeer

You have a bug: replace int length = vsnprintf(NULL, 0, format, arglist); with int length = vsnprintf(NULL, 0, format, arglist) + 1;. The +1 is necessary to allow space for the null terminator, as vsnprintf() returns "The number of characters that would have been written if n had been sufficiently large, not counting the terminating null character." (Source: cplusplus.com/reference/cstdio/vsnprintf). I tested it conclusively here: onlinegdb.com/rySMA9BI4. – Balladeer

Answer 3

This answer takes the best parts of all of the other answers and puts them into one. I consider it to be the best way to do this given all factors, and will explain in more detail after presenting the example.

Summary:

Here's a full example, including with basic error checking in the function. Here I create a printf-like function called lcd_printf(), which works exactly like printf(). It uses vsnprintf() to store a formatted string into a statically-allocated buffer. You can then send this buffer to the LCD display at the location indicated by my comment.

Example Code:

lcd_print.h:

// For info on the gcc "format" attribute, read here under the section titled 
// "format (archetype, string-index, first-to-check)": 
// https://gcc.gnu.org/onlinedocs/gcc-8.2.0/gcc/Common-Function-Attributes.html#Common-Function-Attributes.
int lcd_printf(const char * format, ...) __attribute__((format(printf, 1, 2)));

lcd_print.c:

#include "lcd_print.h"

#include <stdarg.h> // for variable args: va_list
#include <stdio.h>  // for vsnprintf()
#include <limits.h> // for INT_MIN

// `printf`-like function to print to the LCD display.
// Returns the number of chars printed, or a negative number in the event of an error. 
// Error Return codes: 
//     1. INT_MIN if vsnprintf encoding error, OR
//     2. negative of the number of chars it *would have printed* had the buffer been large enough (ie: buffer would 
//     have needed to be the absolute value of this size + 1 for null terminator)
int lcd_printf(const char * format, ...)
{
    int return_code;

    // Formatted string buffer: make as long as you need it to be to hold the longest string you'd ever want 
    // to print + null terminator
    char formatted_str[128]; 

    va_list arglist;
    va_start(arglist, format);

    // Produce the formatted string; see vsnprintf documentation: http://www.cplusplus.com/reference/cstdio/vsnprintf/
    int num_chars_to_print = vsnprintf(formatted_str, sizeof(formatted_str), format, arglist); 
    va_end(arglist);

    if (num_chars_to_print < 0)
    {
        // Encoding error
        return_code = INT_MIN;
        return return_code; // exit early
    }
    else if (num_chars_to_print >= sizeof(formatted_str))
    {
        // formatted_str buffer not long enough
        return_code = -num_chars_to_print;
        // Do NOT return here; rather, continue and print what we can
    }
    else
    {
        // No error
        return_code = num_chars_to_print;
    }

    // Now do whatever is required to send the formatted_str buffer to the LCD display here.

    return return_code;
}

main.c:

#include "lcd_print.h"

int main(void)
{
    int num1 = 7;
    int num2 = -1000;
    unsigned int num3 = 0x812A;

    lcd_printf("my 3 numbers are %i, %i, 0x%4X\n", num1, num2, num3);

    return 0;
}

Explanation & comparison to alternate approaches:

@Harikrishnan points out you should use sprintf(). This is on the right track, and is a valid, but less versatile and complete approach. Creating a new variadic function which uses vsnprintf(), as @Swordfish and I have done, is better.

@Swordfish does a fantastic demonstration of the proper usage of vsnprintf() in order to create your own printf()-like variadic function. His example (aside from lacking error handling) is the perfect template for a custom printf()-like implementation which relies on dynamic memory allocation. His first call to vsnprintf(), with a NULL destination buffer, does nothing more than determine how many bytes he needs to allocate for the formatted string (this is an ingenious and commonly-used trick for this application), and his second call to vsnprintf() actually creates the formatted string. For non-real-time applications which also have large amounts of RAM (ex: PC applications) this is the perfect approach. However, for microcontrollers I strongly recommend against it because:

1. It is non-deterministic. Calling free() can take different (and indeterminable before-hand) amounts of time to complete each time you call it. This is because the heap memory becomes fragmented over time. This means this approach is not good for real-time systems.
   • For more information about various heap implementations for malloc() and free(), review the 5 heap implementations, for example, described by FreeRTOS here: https://www.freertos.org/a00111.html. Search this page for "deterministic".
2. It is unbounded. It will attempt to malloc() ANY amount of memory required for the formatted string. This is bad, as it is more prone to stack-overflow. On safety-critical microcontroller-based systems, stack overflow needs to be strongly guarded against. A preferred approach is to use statically-allocated memory like I have done, with a fixed maximum size.

Additionally, it is lacking the GCC "format" attribute, which is a nice touch (more on this below).

@P__J__ mentions the GCC "format" attribute. My example uses this as well.

If using the GCC compiler, or any other compiler which has something similar, this is highly recommended to add to any custom printf()-like function you make.

The GCC documentation, under the section called format (archetype, string-index, first-to-check), states:

The format attribute specifies that a function takes printf, scanf, strftime or strfmon style arguments that should be type-checked against a format string.

In other words, it provides extra protections and checks to your custom printf()-like function at compile time. This is good.

For our case, simply use printf as the archetype, and a number for the string-index and first-to-check parameters.

The parameter string-index specifies which argument is the format string argument (starting from 1), while first-to-check is the number of the first argument to check against the format string.

Since non-static C++ methods have an implicit this argument, the arguments of such methods should be counted from two, not one, when giving values for string-index and first-to-check.

In other words, here are some valid example usages for this attribute applied to printf()-like function prototypes:

• In C:

  int lcd_printf(const char * format, ...) __attribute__((format(printf, 1, 2))); // 1 is the format-string index (1-based), and 2 is the variadic argument (`...`) index (1-based)
  int lcd_printf(my_type my_var, const char * format, ...) __attribute__((format(printf, 2, 3))); // 2 is the format-string index (1-based), and 3 is the variadic argument (`...`) index (1-based)
  int lcd_printf(my_type my_var, my_type my_var2, const char * format, my_type my_var3, ...) __attribute__((format(printf, 3, 5))); // 3 is the format-string index (1-based), and 5 is the variadic argument (`...`) index (1-based)
  

• In C++:

  int lcd_printf(const char * format, ...) __attribute__((format(printf, 2, 3))); // 2 is the format-string index (2-based), and 3 is the variadic argument (`...`) index (2-based)
  int lcd_printf(my_type my_var, const char * format, ...) __attribute__((format(printf, 3, 4))); // 3 is the format-string index (2-based), and 4 is the variadic argument (`...`) index (2-based)
  int lcd_printf(my_type my_var, my_type my_var2, const char * format, my_type my_var3, ...) __attribute__((format(printf, 4, 6))); // 4 is the format-string index (2-based), and 6 is the variadic argument (`...`) index (2-based)
  

Read more in my other answer here: How should I properly use __attribute__ ((format (printf, x, y))) inside a class method in C++?.

So, putting everything above together, you get the ideal solution for microcontrollers, which I've presented above.

Balladeer

Answer 4

as most commnly used arm compiler is gcc I will only focus on this one. The compiler can check the format & the prameters same as printf does

__attribute__ ((format (printf...

From the gcc documentation

format (archetype, string-index, first-to-check) The format attribute specifies that a function takes printf, scanf, strftime or strfmon style arguments which should be type-checked against a format string. For example, the declaration:

          extern int
          my_printf (void *my_object, const char *my_format, ...)
                __attribute__ ((format (printf, 2, 3)));


causes the compiler to check the arguments in calls to my_printf for consistency with the printf style format string argument

my_format.

The parameter archetype determines how the format string is interpreted, and should be printf, scanf, strftime or strfmon. (You

can also use printf, scanf, strftime or strfmon.) The parameter string-index specifies which argument is the format string argument (starting from 1), while first-to-check is the number of the first argument to check against the format string. For functions where the arguments are not available to be checked (such as vprintf), specify the third parameter as zero. In this case the compiler only checks the format string for consistency. For strftime formats, the third parameter is required to be zero.

In the example above, the format string (my_format) is the second argument of the function my_print, and the arguments to check start

with the third argument, so the correct parameters for the format attribute are 2 and 3.

The format attribute allows you to identify your own functions which take format strings as arguments, so that GCC can check the

calls to these functions for errors. The compiler always (unless -ffreestanding is used) checks formats for the standard library functions printf, fprintf, sprintf, scanf, fscanf, sscanf, strftime, vprintf, vfprintf and vsprintf whenever such warnings are requested (using -Wformat), so there is no need to modify the header file stdio.h. In C99 mode, the functions snprintf, vsnprintf, vscanf, vfscanf and vsscanf are also checked. Except in strictly conforming C standard modes, the X/Open function strfmon is also checked as are printf_unlocked and fprintf_unlocked. See Options Controlling C Dialect. format_arg (string-index) The format_arg attribute specifies that a function takes a format string for a printf, scanf, strftime or strfmon style function and modifies it (for example, to translate it into another language), so the result can be passed to a printf, scanf, strftime or strfmon style function (with the remaining arguments to the format function the same as they would have been for the unmodified string). For example, the declaration:

          extern char *
          my_dgettext (char *my_domain, const char *my_format)
                __attribute__ ((format_arg (2)));


causes the compiler to check the arguments in calls to a printf, scanf, strftime or strfmon type function, whose format string argument

is a call to the my_dgettext function, for consistency with the format string argument my_format. If the format_arg attribute had not been specified, all the compiler could tell in such calls to format functions would be that the format string argument is not constant; this would generate a warning when -Wformat-nonliteral is used, but the calls could not be checked without the attribute.

Titanic