# Formatting Functions

The following information briefly describes the three formatting functions.

- n = Fmt (target, formatstring, source1, ..., sourcen);

  The Fmt function formats the source1, ..., sourcen arguments according to descriptions in the formatstring argument. Fmt places the result of the formatting into the target argument.

- n = FmtFile (handle, formatstring, source1, ..., sourcen);

  The FmtFile function formats the source1, ..., sourcen arguments according to descriptions in the formatstring argument. FmtFile writes the result of the formatting into the file corresponding to the handle argument.

- n = FmtOut (formatstring, source1, ..., sourcen);

  The FmtOut function formats the source1, ..., sourcen arguments according to descriptions in the formatstring argument. FmtOut writes the result of the formatting to the Standard Output.

Each of these formatting functions returns the number of source format specifiers satisfied. If an error exists in the format string, the functions return -1.

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. Call OpenFile to obtain a file handle. For FmtOut, the target is the Standard Output, 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.

### Formatting Functions—Format String

Consider the following formatting function:

n = Fmt(target, formatstring, source1, ..., sourcen);

where formatstring 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"

where target_spec is a format specifier that describes the nature of the target data item, and 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 following examples demonstrate format strings for the formatting functions.

"%s < RANGE %i"

"%s < %s; %i"

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.

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. 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]

| Note rep is not allowed when formatcode is s (string).

The codes in the following table specify formatcode:

### Codes That 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.
| Note When the functions fill in a target string, they always place an ASCII NUL in the string after the last byte.
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 table, Table 1, and Table 2.

### Formatting Integer Modifiers (%i, %d, %x, %o, %c)

Modifier | Meaning | Description
bn | Specify length | The b integer modifier specifies the length of the integer argument or the length of an individual integer array element, in bytes. The default length is 4 bytes; therefore, simple 4-byte integers do not need this modifier. The modifier b2 represents short integers. The modifier b1 represents single-byte integers.
in | Specify array offset | The i integer modifier specifies an offset within an integer 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, %10d[i2] applied to a source integer array processes the 10 integer 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 integer array | The z integer modifier indicates that the data type of the corresponding argument is a string. Nevertheless, the functions treat the data in the string as an integer array. The z modifier is valid only if rep is present.
rn | Specify radix | The r integer modifier specifies the radix of the integer argument, which is important if the functions convert the integer into string format. Legal radixes are 8 (octal), 10 (decimal, the default), 16 (hexadecimal), and 256 (a special radix that represents single 8-bit ASCII characters).
wn | Specify string size | The w integer modifier specifies the exact number of bytes in which to store a string representation of the integer argument, in the event that the functions convert the integer 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 integer, the functions insert an asterisk (*) into the string to signify an overflow. The default for n is zero, which indicates that the integer can occupy whatever space is necessary.
pc | Specify padding | The p integer modifier specifies a padding character c, which fills the space to the left of an integer in the event the integer does not require the entire width you specify with the wn modifier. The default padding character is a blank.
s | Specify as two’s complement | The s integer modifier indicates that the functions consider the integer argument a signed two’s complement number. This is the default interpretation of integers, so the functions do not require the s modifier.
u | Specify as unsigned | The u integer modifier indicates that the functions consider the integer to be an unsigned integer.
onnnn | Specify byte ordering | You use the o integer modifier to describe the byte ordering of raw data so that LabWindows/CVI can map the data to the appropriate byte order. The number of n’s must be equal to the byte size of the integer argument as specified by the bn modifier, which must precede the o modifier. In the case of a four-byte integer, o0123 indicates that the bytes are in ascending order of precedence, and o3210 indicates that the bytes are in descending order of precedence.
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);

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, you 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.

### Table 1. Formatting Floating-Point Modifiers (%f)

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.
| Note The functions can represent the value in scientific notation even when the e modifier is absent. This occurs when the absolute value of the argument is greater than 1.0e40 or less than 1.0e-40, or when the absolute value of the argument is greater than 1.0e20 or less than 1.0e-4 and neither the p modifier nor the w modifier is present.
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);

### Table 2. Formatting String Modifiers (%s)

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.

### Fmt, FmtFile, FmtOut—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.

### Fmt, FmtFile, FmtOut—Using Literals in the Format String

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 %.