Company Events Academic Community Support Solutions Products & Services Contact NI MyNI

Format Specifier Syntax

LabVIEW 2012 Help

Edition Date: June 2012

Part Number: 371361J-01

»View Product Info

You use format specifiers to format strings, convert a number into a string, and insert non-displayable characters in strings.

For functions that produce a string as an output, such as Format Into String and Array To Spreadsheet String, a format specifier uses the following syntax elements. Double brackets ( [] ) enclose optional elements.

%[$][-][+][#][^][0][Width][.Precision || _SignificantDigits][{Unit}][<Embedded information>]Conversion Code

where Width must be a number greater than zero and .Precision and _SignificantDigits must be a number greater than or equal to zero.

For functions that scan a string, such as Scan From String and Spreadsheet String To Array, a format specifier uses the following simplified syntax elements.

%[Width]Conversion Code

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

Format Specifiers Syntax Elements

The following table displays the syntax elements for format specifiers. Refer to the examples of format specifiers for more information.

Syntax Element Description
% Begins the format specifier.
$ (optional) When you use a formatting function, this modifier specifies the order in which to display variables. Include the digit that represents the order of the variable immediately before this modifier.
- (optional) When you use a formatting function, this modifier left justifies the parameter rather than right justifies it within its width.
+ (optional) When you use a formatting function, this modifier includes sign even when the number is positive.
^ (optional) When you use a formatting function and the e or g conversion codes, this element formats the number in engineering notation, where the exponent is always a multiple of three.
# (optional) When you use a formatting function, this modifier removes trailing zeros. If the number has no fractional part, this modifier also removes the description part.
0 (optional) When you use a formatting function, use this modifier without the - modifier to pad any excess space to the left of a numeric parameter with zeros rather than with spaces to reach minimum width.
Width (optional) When you use a scanning function, such as Scan From String, the Width element specifies an exact field width to use. LabVIEW scans only the specified number of characters when processing the parameter. When you use a formatting function, the Width element 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 to the left or right of the parameter with spaces, depending on justification. If Width is missing or 0, the output is only as long as necessary to contain the converted input parameter.
.Precision or _Significant Digits (optional) When you use a formatting function, . or _ controls the number of digits displayed. If you use ., LabVIEW uses the number that follows as a precision specifier for digits to the right of the decimal point. If you use _, LabVIEW uses the number that follows as the specified number of significant digits to use in the display format.

.Precision—When you use it with floating-point notation, this element specifies the number of digits to the right of the decimal point. If . is not present, LabVIEW uses a precision of six digits. If . is 0, LabVIEW does not insert a precision. When you use it with string parameters, .Precision specifies the maximum width of the scanned field. LabVIEW truncates strings longer than this length.

_Significant Digits—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. .Precision affects only the digits to the right of the decimal point, and _Significant Digits includes all non-spacing digits. For example,
  • 3.457 has 4 significant digits
  • 0.0012 has 2 significant digits
  • 123000 has 3 significant digits
Note  You cannot use precision and significant digits together in a single format specifier.

For single-precision, floating-point numbers, National Instruments recommends that you use values from 1 to 6 for _Significant Digits. For double-precision and extended-precision, floating-point numbers, National Instruments recommends that you use values from 1 through 13 for _Significant Digits.

{Unit} (optional) 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. You can use this syntax element only with the Format Into String function.
<Embedded Format Information> Contains a time-specific format string. Refer to the Format Codes for the Time Format String for valid format strings. Only %W, %D, %H, %M, %S and %u apply to relative time.
Conversion Codes Characters that specify how to scan or format a parameter.
Use the following conversion codes for integers and fixed-point numbers:
  • x—Hexadecimal integer (for example, B8).
  • o—Octal integer (for example, 701).
  • b—Binary integer (for example, 1011).
  • d—Signed decimal integer.
  • u—Unsigned decimal integer.
Use the following conversion codes for floating-point and fixed-point numbers:
  • f—Floating-point number with fractional format (for example, 12.345).
  • e—Floating-point number in scientific notation (for example, 1.234E1).
  • g—LabVIEW uses f or e depending on the exponent of the number. LabVIEW uses f if the exponent is greater than –4 or less than the precision specified. LabVIEW uses e if the exponent is less than –4 or greater than the precision specified.
  • p—Floating-point number in SI notation.
Use the following conversion codes for a string:
  • 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 white-space characters.
  • [ ]—Characters in set. [ ] matches a string that contains only the characters specified between the brackets. Character matches are case sensitive. The [ ] conversion code is useful only when you are scanning strings. To match the caret symbol (^) in a set, make sure it is not the first character after the bracket. 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. You can use a hyphen to specify ranges of characters in the set.
    • %[^,;]—Matches any string of characters up to but not including the first comma or semicolon.
    To match a hyphen, specify it as the first or last character in the set.
Use the following conversion codes for time:
Localization Codes Determines if 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 %;.
%,; Comma decimal separator.
%.; Period decimal separator.
%; System default separator.

Format Specifier Examples

The following table displays examples using the syntax elements for format specifiers.

Type Argument(s) Format String Resulting String Comments
Automatic Formatting (%g) 12.00 %#g 12 If you specify #, LabVIEW removes trailing zeros. If you specify g, LabVIEW chooses scientific notation or floating-point notation based on the number to format.
12000000 %#g 1.2E+6
Decimal (%d) 12.67 score= %d%% score= 13% When you specify %d, LabVIEW rounds the argument. Use %% to format a single %.
Floating-Point (%f) 12.67 Temp: %5.1f Temp: 12.7 The 5 in the Format String section specifies a width of 5, and the 1 specifies the number of digits to the right of the decimal, or precision.
12.67 N %5.3f 12.670 N Units are valid only if you use the Format Into String or Scan From String functions. These are examples of physical quantity input. The second example shows how 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.
12.67 N %5.3{mN}f 12670.000 mN
12.67 N %5.3{kg}f 12.670 ?kg
Scientific Notation (%e) 12.67 %.3e 1.267E+1 Add ^ to change to engineering notation where the exponent is always a multiple of three.
12.67 %^.3e 12.670E+0
SI Notation (%p) 12000000 %.2p 12.00M A value of .2 specifies that you want a precision of 2 digits in the resulting string. A value of _2 specifies that you want two significant digits in the resulting string. %p adds the SI prefixes.
12000000 %_2p 12M
Hexadecimal (%x) 12 %02x 0C A – indicates that you want the resulting string left justified. A 0 indicates that you want the resulting string padded with zeros. The number specifies the width of the resulting string. In other words, a value of –n pads the resulting string with spaces to the n width. b is base 2, o is base 8, and x is base 16.
Octal (%o) 12 %06o 000014
Binary (%b) 12 %b 1100
Relative Time (%t) 91.80 %.2t 01:31.80 LabVIEW formats elapsed time in terms of complete weeks (%W), days (%D), hours (%H), minutes (%M), seconds (%S), and fractions of seconds (%u). Refer to the Format Codes for the Time Format String for more time format codes.
91.8 %<Hours:%H Minutes:%M Seconds:%S>t Hours:00 Minutes:01 Seconds:31
Absolute Time (%T) 00:00:00.000 AM
1/1/2001
(Universal Time)
%<%.3X %x>T 12:00:00.000 AM 01/01/2001 %T specifies absolute time. Any information you include with the < and > brackets indicates how you want to format the absolute time. This 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. Refer to the Format Codes for the Time Format String for more time format codes.
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 Add ^ to format the time in Universal Time.
String (%s) Smith John Name: %s, %s. Name: Smith, John. Strings are valid only if you use the Format Into String function. In the second example, the format string specifies to use at most six characters from the string Hello, World then pad with spaces so the total string length is equal to 10.
Hello, World String: %10.6s String:   Hello,
Variable Order (%$) 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 the $ syntax element in the format string for a particular variable, subsequent syntax elements that are not preceded by a $ syntax element apply to the next variable. If you use the $ syntax element for a variable, use the $ syntax element for any other variables in the string to improve readability.

 

Your Feedback! poor Poor  |  Excellent excellent   Yes No
 Document Quality? 
 Answered Your Question? 
Add Comments 1 2 3 4 5 submit