Format Strings for Printing :: QUARC Communications

navigation bar

Format Strings for Printing

Format string are much like format strings for the C library function printf. It generally contains text as well as format specifiers. Format specifiers are used to format input data and are preceded by the '%' character. For example, the format string "The value is %f" contains one format specifier: "%f", which indicates that a single-precision floating-point value should be formatted. Hence, the output in this case might look like "The value is 3.14".

The general form of a format specifier is:

%<flags><field with>.<precision><modifier><argument type>[<code units>](<dimension>)

The '<' and '>' characters delimit the name of a component of the format specifier and are not included in the actual format string. All other characters are literals that are included in the format string, including '[', ']', '(' and ')'. All components are optional except the argument type, which is required. Note also that the ability to specify the maximum number of code units and an array dimension goes beyond the capability of the C library printf function.

The components of a format specifier are:

flags:

use alternate form

%b	-	prefixes output with 0b
%e	-	always includes the radix
%f	-	always includes the radix
%g	-	always includes the radix
%o	-	prefixes output with 0
%p	-	prefixes output with 0x
%x	-	prefixes output with 0x

use leading zeros instead of blanks to fill the field width

left justify the output within the field width

<space>

use a leading blank to indicate a positive number

use a '+' to indicate a positive number

separate group of digits into thousands

field width:

The width in characters (not code units) of the resulting output. Specify a positive integer to use a fixed field width. Specify a '*' character to indicate a variable field width. In this case, an extra input is required which allows the field width to be specified dynamically via the input.

precision:

Specify a positive integer to use a fixed precision. Specify a '*' character to indicate a variable precision. In this case, an extra input is required which allows the precision to be specified dynamically via the input. The precision is interpreted differently depending on the argument type:

%e	=	the number of fractional digits displayed
%f	=	the number of fractional digits displayed
%g	=	the number of significant digits displayed
%s	=	the maximum number of characters (not code units, if code units argument specified) displayed

modifier:

hh	=	integer argument is a char.
h	=	integer argument is a short. Character argument is a char. String argument is a multibyte string.
I8	=	integer argument is an 8-bit integer (t_int8). Character argument is a UTF-8 character (t_uint8). String argument is a UTF-8 string.
I16	=	integer argument is a 16-bit integer (t_int16). Character argument is a UTF-16 character (t_uint16). String argument is a UTF-16 string.
I32	=	integer argument is a 32-bit integer (t_int32). Floating-point argument is a 32-bit float (t_single). Character argument is a UTF-32 character (t_uint32). String argument is a UTF-32 string.
I64	=	integer argument is a 64-bit integer (t_int64). Floating-point argument is a 64-bit float (t_double).
j	=	integer argument is an intmax_t.
l	=	integer argument is a long. Floating-point argument is double. Character argument is a wchar_t. String argument is a wide string.
ll	=	integer argument is a long long (64-bit integer).
L	=	floating-point argument is a long double.
q	=	integer argument is a long long (64-bit integer).
t	=	integer argument is a ptrdiff_t.
w	=	Character argument is a wchar_t. String argument is a wide string.
z	=	integer argument is a size_t.

argument type:

b	=	print the unsigned integer argument in binary, alternate form uses 0b as the prefix
B	=	print the unsigned integer argument in binary, alternate form uses 0B as the prefix
c	=	print a character
C	=	print a wide character
d	=	print a signed integer value
e	=	print a floating-point value in exponential form e.g. 3.1415e2
E	=	print a floating-point value in exponential form using a capital E for the exponent e.g. 3.1415E2
f	=	print a floating-point value in standard form e.g. 314.15
g	=	print a floating-point value in general form (chooses between %f and %e appropriately)
G	=	print a floating-point value in general form (chooses between %F and %E appropriately)
i	=	print a signed integer value
k	=	callback (printed as a pointer).
n	=	return the number of code units, not characters, written so far to the output
o	=	print the unsigned integer argument in octal, alternate form uses a 0 prefix
p	=	print a pointer value, alternate form uses 0x prefix
s	=	print a string. Strings inputs may be variable-size signals.
S	=	print a wide string. String inputs may be variable-size signals.
u	=	print an unsigned integer value
x	=	print the unsigned integer argument in hexadecimal, alternate form uses a 0x prefix
X	=	print the unsigned integer argument in hexadecimal, alternate form uses a 0X prefix

code units:

Specify a positive integer to use a fixed maximum number of code units. Specify a '*' character to indicate a variable number of code units as the maximum. In this case, an extra input is required which allows the maximum number of code units to be specified dynamically via the input. The code units are interpreted differently according to the argument type:

%c	=	the maximum number of code units in a character after conversion (defaults to 1)
%s	=	the maximum number of code units in the string after conversion (defaults to the precision, if specified; otherwise unlimited)

dimension:

If specified, the argument is treated as an array with the specified dimension (length). Array elements are separated in the formatted output by commas for most argument types. For the 'c' and 'C' argument types, characters are not separated by commas but are printed as a string. Each array element is formatted according to the given field width, precision, modifier, etc. There is no capacity for specifying the total field width of the entire array - only the field width for each element printed.

Specify a positive integer to use a fixed array dimension. Specify a '*' character to indicate a variable array dimension. In this case, the size of the array is determined by the size of the corresponding input port for Simulink blocks, and by an extra input argument for C code. Unlike the field width, precision and maximum number of code units, specifying a '*' for the dimension does not cause another input port to be created for Simulink blocks. When a variable array dimension is specified, the corresponding input may be a variable-size signal. See Variable-Size Signals for more information on variable-size signals.

For example, the format specifier "%lg" prints the value of a double-precision float-point input using the default six significant digits, while the format specifier "%lg(3)" prints a 3-vector with each element formatted using the default six significant digits, and each element separated by a comma. To put more space between elements, use a field width. For example, the format specifier "%-10lg(3) prints a 3-vector with each element occupying 10 characters and the value of each element left-justified within its 10 character field.

To print a double-precision number as an integer, use the format specifier "%.0lf", which prints the number with no decimal places. Note that "lf" should be used rather than "%f" because "%f" indicates a single-precision floating-point number, not a double-precision floating-point number. Note that Simulink uses double-precision floating-point by default, so format specifiers will generally require the 'l' modifier. For scalars, it is also possible to use one of the integer format specifiers, such as "%d", with Simulink blocks because it will be cast to the correct type before printing. For array inputs, the correct data type must be indicated in the format specifier because it would be inefficient to replicate the array simply to cast each element of the array to the correct type.

Use the modifiers to adjust the size of the input data types to the desired data type. The format specifiers supports a broad range of modifiers and thus a wide variety of potential input and output data types.

Special Characters

For Simulink blocks, the special characters '\n', '\r', '\t', '\b', '\f' and '\v' are recognized in format strings to be the newline, carriage return, tab, backspace, form-feed and vertical tab respectively. For example, the format string "Hello world\n" results in the text "Hello world" followed by a newline character. For C code, all the standard escape sequences are recognized.

For streaming formatted text to Windows Hyperterminal, use the '\r' character to terminate lines of text rather than the '\n' charter.