Table of Contents
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
|
|||||||||||||||||||||
0 |
= |
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 |
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.
See Also
Copyright ©2024 Quanser Inc. This page was generated 2024-10-17. Submit feedback to Quanser about this page.
Link to this page.