Formatting Functions
- Updated2023-02-21
- 13 minute(s) read
Formatting Functions
The formatting functions format and combine multiple source items into a single target item. The only difference in the workings of the three functions is the location of the target data. For Fmt, the target is a data item in memory that you pass to the function by reference. You must pass the target parameter for Fmt by reference. For FmtFile, the target is a file whose handle you pass as the first argument. For FmtOut, the target is the Standard Output, which is typically the display. FmtOut omits the target argument present in the other two functions. Except for these differences, the following descriptions apply to all the formatting functions.
Format Strings for Formatting Functions
The formatting functions have a formatString parameter that contains the information needed to transform the source arguments to the target argument. Format strings for all the formatting functions are of the following form:
"target_spec < source_specs_and_literals"
- target_spec is a format specifier that describes the nature of the target data item.
- source_specs_and_literals is a sequence of format specifiers and literal characters that indicates how to combine the source material into the target.
- The character '<' serves as a visual reminder of the direction of the data transformation from the sources to the target and separates the single target format specifier from the source format specifiers and literals.
You can omit the target format specifier, in which case the functions assume a %s string format. If you omit the target format specifier, you can omit the '<' character or retain this character for clarity.
Notice that the target format specifier is located to the left of the '<' symbol, just as the target parameter is located to the left of the format string. Likewise, the source format specifiers are located to the right of the '<' symbol, just as the source parameters are located to the right of the format string.
The following examples demonstrate format strings for the formatting functions.
"%s < RANGE %i"
"%s < %s; %i"
Format Specifiers
Format specifiers describe the inputs and outputs of data transformations. Each format specifier has the following form:
% [ rep ] formatcode [[ modifiers ]]
- The character '%' introduces all format specifiers.
- rep indicates how many times the format repeats with respect to the arguments. rep is not allowed when formatcode is s (string).
- formatcode is a code character that indicates the nature of the data items you want to format.
- modifiers is an optional, bracket-enclosed sequence of codes that further describes the data format.
The following example demonstrates a format specifier:
%s %100f %i[b2u]
Codes That Specify formatcode
Use the codes in the following table to specify formatcode:
formatcode | Meaning | Description | ||
---|---|---|---|---|
s | String | This source or target specifier indicates that the corresponding parameter is a character string. As a target specifier, this can mean that numeric source parameters are converted into an ASCII form for inclusion in the target string. Refer to the individual numeric formats, such as %i and %f, for details of these conversions. s is the default if no target specifier exists. The functions do not work on arrays of strings. For example, %10s is not a valid format string.
|
||
i | Integer | This source or target specifier indicates that the corresponding parameter is an integer or, if rep is present, an integer array. The function performs conversions to ASCII digits when converting to or from the string format %s. A modifier is available to specify the radix to use in such a conversion. The default is decimal. | ||
x | Integer (hexadecimal) |
This source or target specifier indicates that the corresponding parameter is an integer or, if rep is present, an integer array. The function performs conversions to ASCII hexadecimal digits (0123456789abcdef) when converting to or from the string format %s. | ||
o | Integer (octal) | This source or target specifier indicates that the corresponding parameter is an integer or, if rep is present, an integer array. The function performs conversions to ASCII octal digits (01234567) when converting to or from the string format %s. | ||
d | Integer (decimal) | This format specifier is identical to %i and is included for compatibility with the C printf family of functions. | ||
f | Real number | This source or target specifier indicates that the corresponding parameter is a real number or, if rep is present, a real array. The function performs conversions to ASCII when converting to or from the string format %s. | ||
c | Character | This source or target specifier indicates that the corresponding parameter is an integer with one significant byte or, if rep is present, an array of 1-byte integers. The function does not perform conversion to ASCII when converting to or from the string format %s. The function copies directly to or from the string. |
Formatting Modifiers
Modifiers are optional codes you use to describe the nature of the source or target data. If you use modifiers, you must enclose them in square brackets and place them immediately after the format code they modify. If one format specifier requires more than one modifier, enclose all modifiers in the same set of brackets.
A different set of modifiers exists for each possible format specifier as shown in the following tables. The first table lists the modifiers for integer specifiers, the second table lists modifiers for floating-point specifiers, and the last table lists modifiers for string specifiers.
Formatting Integer Modifiers
Use the following modifiers for the following format codes: %i, %d, %x, %o, and %c.
When using the Fmt function to transfer raw instrument data to or from a C integer or integer array, you must use the o modifier on the buffer that contains the raw instrument data. Do not use the o modifier on the buffer that contains the C integer or integer array. LabWindows/CVI determines the byte ordering of the buffer without the o modifier based on the architecture on which your program is running.
For example, if a GPIB instrument sends 2-byte binary data in Intel byte order, the code appears as follows:
short int instr_buf[100];
short int prog_buf[100];
status = ibrd (ud, instr_buf, 200);
Fmt (prog_buf, "%100d<%100d[b2o01]", instr_buf);
If, instead, the GPIB instrument sends two-byte binary data in Motorola byte order, Fmt appears as follows:
Fmt (prog_buf, "%100d<%100d[b2o10]", instr_buf);
In either case, use the o modifier only on the buffer that contains the raw data from the instrument (instr_buf). LabWindows/CVI ensures that the program buffer (prog_buf) is in the proper byte order for the host processor.
![]() |
Note When you use both the bn and on modifiers on an integer specifier, the bn modifier must be first. |
Formatting Floating-Point Modifiers
Use the following modifiers for the %f format code.
Modifier | Meaning | Description | ||
bn | Specify length | The b floating-point modifier specifies the length of the floating-point argument, or the length of an individual array element, in bytes. The default length is 8 bytes; therefore, double-precision values do not need this modifier. Single-precision, floating-point values are indicated by b4. The only valid values for n are 8 and 4. | ||
in | Specify array offset | The i floating-point modifier specifies an offset within a floating-point array argument. This modifier indicates the location within the array where processing begins. n is the zero-based index of the first element to process. Thus, %10f[i2] applied to a source floating-point array processes the 10 floating-point values from the third through the 12th element of the array. The i modifier is valid only if rep is present. If you use the i modifier with the z modifier, n is in terms of bytes. | ||
z | Treat string as floating-point array | The z floating-point modifier indicates that the data type of the corresponding argument is a string. Nevertheless, the functions treat the data in the string as a floating-point array. The z modifier is valid only if rep is present. | ||
wn | Specify string size | The w floating-point modifier specifies the exact number of bytes in which to store a string representation of the floating-point argument, in the event that the functions convert the value to a string format. You can enter any non-negative value here. If n is less than the number of digits required to represent the floating-point number, the functions insert an asterisk (*) into the string to signify an overflow. The default for n is zero, which indicates that the value can occupy whatever space is necessary. | ||
pn | Specify precision | The p floating-point modifier specifies the number of digits to the right of the decimal point in a string representation of the floating-point number. You can lose significant digits by attempting to conform to the precision specification. If you omit the pn modifier, the default value is p6. | ||
en | Specify as scientific notation | The e floating-point modifier instructs the functions to convert a value to string format in scientific notation. If you omit the en modifier, the functions use the floating-point notation. n is optional and specifies the number of digits in the exponent. For example, %f[e2] formats 10.0 as 1.0e+01. If you omit n, the functions use a default of three.
|
||
f | Specify as floating-point notation | The f floating-point modifier instructs the functions to convert a value to string format in floating-point notation. This is the default. | ||
t | Truncate | The t floating-point modifier indicates that in floating-point to integer transformations, the functions truncate instead of round the floating-point value. This is the default. | ||
r | Round | The r floating-point modifier indicates that in floating-point to integer transformations, the functions round instead of truncate the floating-point value. The default method is truncation. | ||
jn | Specify separator characters | The j modifier specifies the characters to insert between each element when you use the repeat code to format an array. n specifies the number of characters following the closing square bracket (]) that the function inserts between each element of the array. For example, the following Fmt call inserts a comma between each integer. Fmt (buf, "%s<%100d[j1],", dataArray); |
Formatting String Modifiers
Use the following modifiers for the %s format code.
Modifier | Meaning | Description |
---|---|---|
in | Specify array offset | The i string modifier specifies an offset within a string. This modifier indicates the location within the string where processing begins. n is the zero-based index of the first byte to process. Thus, %s[i2] applied to a target string begins placing data in the third byte of the string. |
a | Append | When applied to a target format specifier, the a string modifier specifies that all formatted data be appended to the target string, beginning at the first occurrence of an ASCII NUL in the target string. |
wn | Specify string size | When applied to a source format specifier, the w string modifier specifies the maximum number of bytes to consume from the string argument. You can enter any non-negative value here. The default is zero, which indicates to consume entire string. When modifying a target format specifier, the w string modifier specifies the exact number of bytes to store in the string, excluding the terminating ASCII NUL. If n is zero or omitted, the functions store as many bytes as the sources call for. When n is greater than the number of bytes available from the source, the functions fill the remaining bytes with ASCII NULs if you use the q modifier or blanks if you do not use the q modifier. When you use the w string modifier in conjunction with the a string modifier, n indicates the number of bytes to append to the string excluding the terminating ASCII NUL. |
q | Append NULs | When applied to a target string in conjunction with the w string modifier, the q string modifier specifies that unfilled bytes at the end of the target string be set to ASCII NULs instead of blanks. |
tn | Terminate on character | When applied to a source string, the t string modifier specifies that the source string terminates on the first occurrence of the character n, where n is the ASCII value of the character. Thus, %s[t44] stops the reading of the source string on an ASCII comma. For example, if you use %s[t44] with the source string Hello, World!, the functions place Hello into the target. More than one t modifier can occur in the same specifier, in which case the string terminates when any of the terminators occur. If no t modifier exists, the functions stop reading the source string on an ASCII NUL. This modifier has no effect when you apply it to the target specifier. |
t- | Terminate when full | This modifier is similar to tn except that t- specifies that there are no terminating characters. The functions stop reading the source string when the target is full or when the functions have read the number of bytes specified with the w modifier. |
t# | Terminate on number | This modifier is equivalent to repeating the t modifier with the ASCII values of the characters +, -, and 0-9. This modifier instructs the functions to stop reading the source string when a numeric expression occurs. If you use %s[t#] with the source string ab567, the functions place ab in the target. |
Using Asterisks (*) Instead of Constants in Format Specifiers
Often, a format specifier requires one or more integer values. The format specifier for an integer array, for example, requires the number of elements (rep). You can use constants for these integer values in format specifiers. You also can use an argument in the argument list to specify an integer value. When you use an argument to specify an integer value, substitute an asterisk (*) for the constant in the format specifier.
Use the asterisk in the following format specifier elements:
rep | For integer or floating-point arrays |
in | For integer or floating-point arrays, or strings |
wn | For any format specifier |
pn | For floating-point specifiers only |
en | For floating-point specifiers only |
rn | For integer specifiers only |
When you use one or more asterisks instead of constants in a target specifier, the arguments that correspond to the asterisks must appear after the format string in the same order as the corresponding asterisks appear in the format specifier.
When you use one or more asterisks instead of constants in a source specifier, the arguments that correspond to the asterisks must precede the source argument and must be in the same order as the corresponding asterisks in the format specifier.
Using Literals in Format Strings
Literal characters that appear in a formatting function format string indicate that the literal characters are to be combined with the source parameters in the appropriate positions. They do not correspond to any source parameters but are copied directly into the target item.
Because the left side of the < symbol must be a single format specifier, literal characters must be on the right side of the symbol. Literals on the left side or more than one format specifier on the left side result in a -1 error, indicating a faulty format string. You then can use GetFmtErrNdx to determine exactly where there is an error in the format string.
The characters %, [, ], <, and > have special meaning in the format strings. To specify that these characters be taken literally, precede them with %.