Understand LabVIEW format specifier syntax for format strings that format output or scan input.

Format Specifier Syntax for Formatting Functions

Formatting functions use full format specifier syntax:

%[$][-][+][#][^][0][Width][.Precision∥_Significant Digits][{Unit}][<Embedded Time Format>]Conversion Code

where

  • Width must be a number greater than zero
  • Precision or Significant Digits must be a number greater than or equal to zero
Note
  • Double brackets [] indicate optional elements. You do not need to include literal [] characters in the format specifier unless a specific syntax element requires them.
  • ∥ indicates that, if you decide to use .Precision or _Significant Digits, you must choose one or the other.
  • Replace text in the syntax with an appropriate syntax element.

Format Specifier Syntax for Scanning Functions

Scanning functions use a simplified format specifier syntax:

%[Width]Conversion Code

where Width must be a number greater than zero

Note
  • Double brackets [] indicate optional elements. You do not need to include literal [] characters in the format specifier.
  • Replace text in the syntax with an appropriate syntax element.

Format Specifier Syntax Elements

Format specifiers support specific syntax elements that define how LabVIEW functions interpret input strings and produce an output string. Understand the format specifier syntax to use to create the output strings you need.

% Delimiter

Required element that begins a format specifier.

The Format Into String, Format Into File, Scan From String, and Scan From File functions are expandable. These functions can use multiple format specifiers in the format string, one for each input or output of the function.

  • The number of format specifiers in the format string must match the number of arguments to the function.
  • To specify multiple format specifiers in the format string input, indicate each format specifier with %.

Modifiers

Use optional modifier elements to refine the output that a format string creates.

Syntax Element Formatting Function or Scanning Function Description
$ Formatting Specifies the order in which to display variables. Include the digit that represents the order of the variable immediately before this modifier.
- Formatting Left justifies the parameter within its width rather than right justifies it.
+ Formatting Includes sign even when the number is positive.
^ Formatting
  • When used with the e or g conversion codes, formats the number in engineering notation. In engineering notation, the exponent is always a multiple of three.
  • When used with T, formats the time in Universal Time.
# Formatting Removes trailing zeros. If the number has no fractional part, this modifier also removes the description part.
0 Formatting When used without the - modifier, pads any excess space to the left of a numeric parameter with zeros rather than with spaces to reach minimum width.
Width
  • Formatting
  • Scanning
  • Formatting function: Width specifies the minimum character field width of the output. This width is not a maximum width. LabVIEW uses as many characters as necessary to format the parameter without truncating it. LabVIEW pads the field ro the left or right of the parameter with spaces, depending on justification. If Width is missing or is 0, the output is only as long as is necessary to contain the converted input parameter.
  • Scanning function: Width specifies the maximum character field width to use. LabVIEW scans the maximum number of characters when processing the parameter.
.Precision or _Significant Digits Formatting Controls the number of digits displayed, where either Precision or Significant Digits is a number.
Note You cannot use precision and significant digits together in a single format specifier.
  • .Precision: The number is a precision specifier for digits to the right of the decimal point. .Precision affects only the digits to the right of the decimal point. .Precision has the following special interactions or values:
    • Floating-point notation: this element specifies the number of digits to the right of the decimal point.
    • . not present: LabVIEW uses a precision of six digits.
    • . is 0: LabVIEW does not insert a precision.
    • Used with string parameters: specifies the maximum width of the scanned field. LabVIEW truncates strings longer than this length.
  • _Significant Digits: The number is the number of significant digits to use in the display format. Displays the data by rounding to the number of digits you specify. LabVIEW rounds the data only for display purposes, which does not affect the original data. Includes all non-spacing digits. For example:
    • 3.457 has 4 significant digits
    • 0.0012 has 2 significant digits
    • 123000 has 3 significant digits

    NI recommends setting Significant Digits to the following values, depending on the type of number:

    • Single-precision, floating-point numbers: [1, 6]
    • Double-precision and extended-precision, floating-point numbers: [1, 13]
{Unit} Formatting Overrides the original unit of a VI when you use a function to convert a physical quantity (a value with an associated unit). You must use a compatible unit.
Note You can use this syntax element only with the Format Into String function.
<Embedded Time Format> Formatting Contains a time-specific format string for use with the T (absolute time) and t (relative time) conversion codes. For valid embedded time format strings, refer to Time-Specific Format Codes.

Conversion Codes

Characters that specify how to scan or format a parameter. Required elements for both scanning functions and formatting functions.

Conversion codes operate primarily with a specific type of data but can interpret multiple types of data.

Conversion Codes for Numbers

Conversion Code Supported Numerics Description
x
  • Integers
  • Fixed-point numbers
 Hexadecimal integer (for example, B8).
o
  • Integers
  • Fixed-point numbers
 Octal integer (for example, 701).
b
  • Integers
  • Fixed-point numbers
 Binary integer (for example, 1011).
d
  • Integers
  • Fixed-point numbers
 Signed decimal integer.
u
  • Integers
  • Fixed-point numbers
 Unsigned decimal integer.
f
  • Floating-point numbers
  • Fixed-point numbers
 Floating-point number with fractional format (for example, 12.345).
e
  • Floating-point numbers
  • Fixed-point numbers
 Floating-point number in scientific notation (for example, 1.234E1).
g
  • Floating-point numbers
  • Fixed-point numbers
 Automatic formatting. Depending on the exponent of the number, uses either f or e.
  • Exponent is greater than –4 or less than the precision specified: uses f
  • Exponent is less than –4 or greater than the precision specified: uses e
p
  • Floating-point numbers
  • Fixed-point numbers
 Floating-point number in SI notation.
Note Conversion codes for numbers can interpret other types of data as follows:
  • Booleans: 0 represents False, 1 represents True
  • Enums: Interprets the numeric index value of the enum item

Conversion Codes for Strings

Conversion Code Description
s String (for example, abc)
  • When scanning, s matches only up to the next white-space character.
  • A space matches one or more consecutive white-space characters. To scan a string that may contain white space, use the characters in set conversion code. Specify all the characters which the string may contain within the brackets, including space or other whitespace characters.
[ ] Characters in set: matches a string that contains only the characters specified between the brackets.
Note The [ ] conversion code is useful only when you are scanning strings, not formatting strings.

Character matches are case sensitive.

The following characters have special meanings within the [ ] conversion code:

  • Specify inclusive ranges of characters in the set: Use a hyphen (-) between the characters that bound the range.

    To match a literal hyphen, specify it as the first or last character in the set.

  • Scan until the first match for a specified character or characters in the set: Enter the caret symbol ^ as the first character after the opening bracket [.

    To match a literal caret symbol, place the caret in any other position within the set.

The following examples demonstrate the use of the characters in set conversion code:

  • %[aeiou]: Matches any string that contains only lowercase vowels.
  • %[0-9a-zA-Z ]: Matches a string that contains numbers, letters, or spaces.
  • %[^,;]: Scans a string only until the function finds the first comma or semicolon.
Note s can interpret other types of data as follows:
  • Booleans: Interprets False and True
  • Enums: Interprets the string label of the enum item
  • Named refnums, such as DAQmx channels or VISA resource names
  • Paths

Conversion Codes for Time

Conversion Code Description
T Absolute time. Use T in the Display Format property of numeric or time stamp controls, constants, and indicators, as well as the Format Into String, Format Into File, Scan From String, and Scan From File functions.
Note You cannot use T with the Array To Spreadsheet String, Spreadsheet String To Array, Format Value, and Scan Value functions.

Formatting a time stamp as anything other than time returns an error.
t Relative time. Use t in the Display Format property of numeric or time stamp controls, constants, and indicators, as well as the Format Into String,Format Into File, Scan From String, and Scan From File functions.
Note You cannot use t with the Array To Spreadsheet String, Spreadsheet String To Array, Format Value, and Scan Value functions.

Formatting a time stamp as anything other than time returns an error.
Note T can interpret time stamps and numerics. t can interpret numerics only.

Localization Codes

Optional sequence that determines whether LabVIEW uses a decimal or comma to separate the whole number from the decimal part of the number.

These codes control the decimal separator for numeric output. These codes do not cause any input or output to occur. They change the decimal separator for all further inputs and outputs until they find the next %;.

Table 5. Localization Codes for Format Specifiers
Localization Code Description
%,; Comma decimal separator.
%.; Period decimal separator.
%; System default separator. If you do not specify a separator, LabVIEW uses the system default separator.

Literal Characters

If you want to add characters to an input string, you can add literal characters to the format string. You can use escape sequences in format strings to insert certain characters.

Table 6. Escape Characters for Format Specifiers
Escape Sequence Output Description
%% % Avoid collision with the % delimiter that defines the beginning of a format specifier.
\> > Avoid collision with the > delimiter that ends the embedded time format modifier.
Backslash (\) codes Depends on backslash code Character sequence that specify hex values, spacing, backspaces, and other formatting options.

For more information about backslash codes, refer to Backslash ('\') Codes Display.

Format Specifier Syntax Examples

Understand how LabVIEW format specifiers convert input arguments to output strings with practical examples.

Automatic Formatting (%g) Example

Argument Format String Resulting String
12.00 %#g 12
12000000 %#g 1.2E+7

If you specify #, LabVIEW removes trailing zeros.

If you specify g, LabVIEW chooses scientific notation or floating-point notation based on the exponent of the number to format.

Decimal (%d) Example

Argument Format String Resulting String
12.67 score= %d%% score= 13%

When you specify %d, LabVIEW displays integers in base-10 decimal format.

  • For signed or unsigned integers of any bit size, LabVIEW displays the integer unmodified.
  • LabVIEW rounds floating-point values to signed 64-bit integers. NaN and values greater than the maximum value of a signed 64-bit integer are rounded to the maximum value of a signed 64-bit integer, which is 9223372036854775807. To record values greater than the maximum value of a signed 64-bit integer, you must explicitly cast the values to unsigned 64-bit integers using the To Unsigned Quad Integer function.

Floating-Point (%f) Example

Argument Format String Resulting String
12.67 Temp: %5.1f Temp: 12.7
12.67 N %5.3f 12.670 N
12.67 N %5.3{mN}f 12670.000 mN
12.67 N %5.3{kg}f 12.670 ?kg
  • 5 in the format string specifies a width of 5. The number after . specifies the number of digits to the right of the decimal, or precision.
  • Units are valid only if you use the Format Into String function. The examples with a unit show how format specifiers interact with physical quantities.
    • You can convert from one unit to another.
    • The question mark indicates when the unit in the format specifier is in conflict with the input unit.

Scientific Notation (%e) Example

Argument Format String Resulting String
12.67 %.3e 1.267E+1
12.67 %^.3e 1.2670E+0

You can add ^ to change to engineering notation, where the exponent is always a multiple of three.

SI Notation (%p) Example

Argument Format String Resulting String
12000000 %.2p 12.00M
12000000 %_2p 12M
  • A value of .2 specifies that you want a precision of two digits in the resulting string.
  • A value of _2 specifies that you want two significant digits in the resulting string.
  • The %p code adds the SI prefixes.

Hexadecimal (%x), Octal (%o), and Binary (%b) Example

Argument Format String Resulting String
12 %02x 0C
12 %06o 000014
12 %b 1100

b (binary) is base 2. o (octal) is base 8. x (hexadecimal) is base 16.

  • You can use the - modifier to left justify the resulting string.
  • The 0 modifier indicates to pad the resulting string with zeroes.
  • The digit in the format specifier specifies the width of the resulting string.

For example, a modifier -n pads the resulting string with spaces to the n width.

Relative Time (%t) Example

Argument Format String Resulting String
91.80 %.2t 01:31.80
91.8 %<Hours:%H Minutes:%M Seconds:%S>t Hours:00 Minutes:01 Seconds:31

LabVIEW formats elapsed time in terms of the following:

  • Complete weeks (%W)
  • Complete days (%D)
  • Complete hours (%H)
  • Complete minutes (%M)
  • Complete seconds (%S)
  • Fractions of seconds (%digitu)

For more information on the embedded time format codes, refer to Time-Specific Format Codes.

Absolute Time (%T) Example

Argument Format String Resulting String
00:00:00.000 AM 1/1/2001 (Universal Time) %<%.3X %x>T 12:00:00.000 AM 01/01/2001
00:00:00.000 AM 1/1/2001 (Universal Time) %<%Y.%m.%d>T 2001.01.01
00:00:00.000 AM 1/1/2001 (Universal Time) %^<%.3X %x>T 06:00:00.000 AM 12/31/2000

%T specifies absolute time.

  • Any information you include within the embedded time format (between < and >) indicates how you want to format the absolute time. For more information on the embedded time format codes, refer to Time-Specific Format Codes.
  • The format, including the punctuation, changes based on the regional settings of the computer. The time changes based on the configured time zone for the computer.
  • Add ^ to format the time in Universal Time.

String (%s) Example

Argument Format String Resulting String
Smith John Name: %s, %s. Name: Smith, John.
Hello, World String: %10.6s String: Hello,
  • %s is valid for both formatting and scanning. You can use %s for both strings and files.
  • In the first example, the format string uses multiple format specifiers. To accomplish this result, do the following:
    • Provide the family name (Smith) to input 1 of Format Into String.
    • Expand Format Into String to add a second input by clicking and dragging on the bottom of the function. Provide the given name (John) to the resulting input 2.
    • Enter the provided format string. Because the format string includes two % delimiters, the format string includes two format specifiers. The number of format specifiers in the format string must match the number of inputs to the function. LabVIEW interprets the characters that are not part of a format specifier as literal text to add to the resulting string.
  • In the second example, .6 controls the precision of the string. .6 specifies to use at most six characters from the string Hello, World. 10 is the width: LabVIEW pads the string with spaces so the total string length is equal to ten.

Variable Order (%$) Example

Argument Format String Resulting String
Smith John %2$s %1$s John Smith

In this example, Smith is the first variable and John is the second variable.

  • If you use $ in the format string for a particular variable, subsequent syntax elements that are not preceded by $ apply to the next variable.
  • To improve readability when you use $ for a variable, use $ for any other variables in the string.

Literal Percent Character Example (%%)

Argument Format String Resulting String
Empty argument %% %

%% does not add a terminal to the Format Into String or Scan From String functions.