API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

STD_STRLPRINTF()

Brew Release
Brew MP 1.0.2
See Also
None
Description

The functions std_strlprintf() and std_vstrlprintf() write formatted output to a string. These functions guarantee NUL-termination of the output buffer when its size is greater than zero.
A format string is copied to the output buffer, except for conversion specifiers contained within the format string. Conversion specifiers begin with a "%" and specify some action that consumes an argument from the argument list.
Conversion specifiers have the following form:
  
       %[FLAGS] [WIDTH] [.PRECISION] [TYPE] CONV


CONV is the only required field. It is always a single character, and determines the action to be taken. Supported values are:
    CONV | Description
   ======|=======================================================
     c   | Output a single character.
         |
     s   | Output a NUL-terminated single-byte character string.
         |
    d, i | Ouptut a signed decimal integer. 
         |
     u   | Output an unsigned decimal integer. 
         |
     o   | Output an unsigned octal integer.
         |
     x   | Output an unsigned hexadecimal integer, using
         | lower case digits.
         |
     X   | Output an unsigned hexadecimal integer, using
         | upper case digits.
         |
     p   | Output a pointer value as eight hexadecimal digits,
         | using upper case digits.

The next argument from the argument list supplies the value to be formatted and output.
FLAGS, WIDTH, and PRECISION can modify the formatting of the value.
FLAGS consists of one or more of the following characters:
   
   Flag | Meaning                                      
   =====|=================================================================
     +  | Prefix positive numbers with "+" (%d and %i only).
   -----|-----------------------------------------------------------------
     -  | When padding to meet WIDTH, pad on the right.
   -----|-----------------------------------------------------------------
     0  | Pad with '0' characters when padding on the left to meet WIDTH.
   -----|-----------------------------------------------------------------
   blank| Prefix positive numbers with " " (%d and %i only).
   space|
   -----|-----------------------------------------------------------------
     #  | With %x or %X: prefixes non-zero values with "0x"/"0X".
        | With %o, ensure the value begins with "0" (increasing PRECISION
        |    if necessary).
        | Ignored for all other CONV specifiers.
   -----|-----------------------------------------------------------------


WIDTH is an unsigned decimal integer or the character "*".
WIDTH gives the minimum number of characters to be written. The formatted value will be padded with spaces until the minimum size is met; it never causes a value to be truncated The sign of the WIDTH integer selects between left and right padding. Padding will be on the left unless the "-" flag is specified.
When "*" is used, an 'int' argument is consumed from the argument list and used as the WIDTH. A negative argument specifies padding on the right, and its absolute value gives the amount of padding.
If the "0" flags is specified, any padding on the left will consist of "0" characters. An exception to this rule is that the "0" flag is ignored when precision is specified for a numeric value.
PRECISION is a non-negative decimal integer or "*" preceded by ".".
When PRECISION accompanies any of the numeric conversions, it specifies the minimum number of digits to output. Values are padded on the left with '0' to meet the specified size. PRECISION defaults to 1 for numbers.
When PRECISION accompanies other conversions, it specifies the maximum number of characters from the value to output. The value will be truncated to ensure that at most PRECISION characters are output.
TYPE provides information about the type of arguments. This is used to determine the size of integer arguments. Values larger than 'int' can be properly obtained from the argument list. Their behavior should be considered undefined for CONV operations other than integer formatting.
   
    TYPE  | Meaning                                      
   =======|=====================
     hh   | sizeof(char)
   -------|---------------------
      h   | sizeof(short)
   -------|---------------------
      l   | sizeof(long)
   -------|---------------------
    L, ll | sizeof(long long)
   -------|---------------------
      j   | sizeof(int64)
   -------|---------------------
      z   | sizeof(size_t)
   -------|---------------------


For 64-bit integers, "ll" may be the most widely-supported type specifier in other printf implementation, but "j" has been introduced in ISO C99. This implementation supports both.
Note that arguments to variadic functions are promoted to 'int' when smaller than 'int', so 'h' and 'hh' have no observable effect. Static analysis tools that understand standard format string syntax may use this information for other purposes.
Params
pszDest
[out]:
output buffer, where output will be placed
nDestSize
[]:
size of pszDest in bytes
pszFmt
[]:
format string
Interface
Prototype
  •    int std_strlprintf(char *pszDest, int nDestSize, 
                          const char *pszFmt, ...);
Return

  • The size required to hold the entire untruncated output, NOT including NUL-termination.
Side Effect
  • None
Comments
Notable omissions from std_strlprintf() are lack of support for floating point and lack of support for "%n".