Format into String (G Dataflow)

Download Manual | Offline Viewer Required

Version:

Last Modified: February 28, 2020

Inserts input data into specified locations in a string and formats that data according to your specifications.

format string

A string that includes a format specifier for each input along with any additional text that you want to appear in the output. A format specifier is a series of characters, initiated by a %, that indicates how to convert the associated input argument into text.

Each format specifier uses the following general syntax:

% modifiers specifier

This input accepts a maximum of 255 characters.

Specifiers

Specifier	Definition
x	hexadecimal integer
o	octal integer
b	binary integer
d	signed decimal integer
u	unsigned decimal integer
f	floating-point number with fractional format
e	floating-point number in scientific notation
g	floating-point number in either fractional format (f) or scientific notation (e) depending on the exponent of the number: f—The exponent is greater than -4 and less than the precision specified e—exponent is less than -4 or greater than the precision specified
^e or ^g	floating-point number in engineering notation
p	floating-point number in SI notation
T	absolute time, most commonly used to interpret timestamp data
t	relative time, most commonly used to interpret numeric data as elapsed seconds

Modifiers for Numeric Specifiers (x, o, b, d, u, f, e, g, p)

If you use multiple modifiers, they must appear in the following order:

%[-][+][#][0][width][.precision || _significantDigits]specifier

Modifier	Definition	Usage Example	Output for 12345
0	Pads any excess space to the left of a numeric parameter with zeros rather than with spaces to reach minimum width.	%06_2f	012000
+	Includes the sign of the number even when the number is positive.	%+6_2f	+12000
#	Removes zeros at the end of the number.
-	Left justifies the output within its width. If the node inserts spaces to create the specified width, the spaces appear to the right of the value.	%-6_2f	12000_
width	A number specifying the minimum number of characters that the node uses in the output. If the value requires fewer characters, the node pads the output with spaces to meet this width. This width is not a maximum width. The node uses as many characters as necessary to output the value without truncating it. Non-numeric characters, such as a decimal point or negative sign, count toward the total width of an output string. If width is missing or 0, the output uses only as many characters as necessary to contain the formatted value.	%6f	_12345
width.precision	A number specifying how many digits appear to the right of the decimal point in the output. If neither .precision nor _significantDigits is present, the node uses a precision of six digits. If precision is 0, the node rounds the value to the nearest whole number.	%6.2f	12345.00
width_significantDigits	A number specifying how many significant digits appear in the output. The node rounds the data only for display purposes, which does not affect the original data. You cannot use .precision and _significantDigits together in a single format specifier.	%6_2f	_12000

Modifiers for Time Specifiers (t, T)

Use the following syntax to specify which parts of a time you want to format:

%[-]width <time specifier codes>t

Time Format Code	Definition	Values
%a	Abbreviated weekday name. This node returns a numeric value for systems that do not support abbreviated names, such as Chinese and Korean.	Sun - Sat
%A	Full weekday name	Sunday - Saturday
%b	Abbreviated month name. This node returns a numeric value for systems that do not support abbreviated names, such as Chinese and Korean.	Jan - Dec
%B	Full month name	January - December
%c	Locale-specific default date and time
%d	Day of month	01-31
%H	Hour (24-hour clock)	00-23
%I	Hour (12-hour clock)	01-12
%j	Day number of the year	001-366
%m	Month number	01-12
%M	Minute	00-59
%p	AM or PM flag	AM or PM
%S	Second	00-59
%<digit>u	Fractional seconds with <digit> precision
%U	Week number of the year, with the first Sunday as the first day of the first week	00-53
%w	Weekday as a decimal number, with 0 representing Sunday	0-6
%W	Week number of the year, with the first Sunday as the first day of the first week	00-53
%x	Locale-specific date
%.1x	Long date format
%.2x	Abbreviated long date format. This node returns a numeric value for systems that do not support abbreviated names, such as Chinese and Korean.
%X	Locale-specific time
%y	Year within century	00-99
%Y	Year, including the century	1997, for example
%z	Difference between locale time and universal time	HH:MM:SS
%Z	Time zone name or abbreviation
Literal text	Literal text

Modifier	Definition
-	Left justifies the output within its width. If the node inserts spaces to create the specified width, the spaces appear to the right of the value.
width	A number specifying the minimum number of characters that the node uses in the output. If the value requires fewer characters, the node pads the output with spaces to meet this width. This width is not a maximum width. The node uses as many characters as necessary to output the value without truncating it. If width is missing or 0, the output uses only as many characters as necessary to contain the formatted value.

Modifier

Definition

Left justifies the output within its width. If the node inserts spaces to create the specified width, the spaces appear to the right of the value.

width

A number specifying the minimum number of characters that the node uses in the output. If the value requires fewer characters, the node pads the output with spaces to meet this width.

This width is not a maximum width. The node uses as many characters as necessary to output the value without truncating it.

If width is missing or 0, the output uses only as many characters as necessary to contain the formatted value.

Modifiers for the String Specifier (s)

Use the following syntax to format a string:

%[-]width s

Modifier	Definition
-	Left justifies the output within its width. If the node inserts spaces to create the specified width, the spaces appear to the right of the value.
width	A number specifying the minimum number of characters that the node uses in the output. If the value requires fewer characters, the node pads the output with spaces to meet this width. This width is not a maximum width. The node uses as many characters as necessary to output the value without truncating it. If width is missing or 0, the output uses only as many characters as necessary to contain the formatted value.

Modifier

Definition

Left justifies the output within its width. If the node inserts spaces to create the specified width, the spaces appear to the right of the value.

width

A number specifying the minimum number of characters that the node uses in the output. If the value requires fewer characters, the node pads the output with spaces to meet this width.

This width is not a maximum width. The node uses as many characters as necessary to output the value without truncating it.

If width is missing or 0, the output uses only as many characters as necessary to contain the formatted value.

Modifier for Reordering Inputs

Modifier	Definition
number$	Explicitly specifies which input to use for the containing format specifier. This modifier overrides the default input with the input specified by number. When you use this modifier, the subsequent format specifiers become associated with the inputs that follow the input specified by number. To avoid confusion, National Instruments recommends using this modifier in all format specifiers if you use it in one.

Modifier

Definition

number$

Explicitly specifies which input to use for the containing format specifier. This modifier overrides the default input with the input specified by number.

When you use this modifier, the subsequent format specifiers become associated with the inputs that follow the input specified by number. To avoid confusion, National Instruments recommends using this modifier in all format specifiers if you use it in one.

Modifiers for Overriding Units

Modifier	Definition
{unit}	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.

Syntax for Including Literal Characters in a Format String

Most characters outside of a format specifier appear literally in the output. However, you must use special syntax for the following special characters:

Syntax	Definition
\00 - \FF	Hex value of an 8-bit character; must be uppercase
\b	Backspace (ASCII BS, equivalent to \08)
\f	Form feed (ASCII FF, equivalent to \0C)
\n	Linefeed (ASCII LF, equivalent to \0A). Format into File automatically converts this code into the platform-dependent end-of-line character.
\r	Carriage return (ASCII CR, equivalent to \0D)
\t	Tab (ASCII HT, equivalent to \09)
\s	Space (equivalent to \20)
\\	Backslash (ASCII \, equivalent to \5C)
%%	Percent sign

Default: A string containing the default format specifier for the data type of each input, separated by spaces

initial string

A string to which this node appends format string in order to form the resulting string.

error in

Error conditions that occur before this node runs.

The node responds to this input according to standard error behavior.

Standard Error Behavior

Many nodes provide an error in input and an error out output so that the node can respond to and communicate errors that occur while code is running. The value of error in specifies whether an error occurred before the node runs. Most nodes respond to values of error in in a standard, predictable way.

error in does not contain an error	error in contains an error

If no error occurred before the node runs, the node begins execution normally. If no error occurs while the node runs, it returns no error. If an error does occur while the node runs, it returns that error information as error out.	If an error occurred before the node runs, the node does not execute. Instead, it returns the error in value as error out.

Default: No error

input

Input data to be converted to text, as determined by the corresponding format specifier in format string. This node assigns inputs to format specifiers sequentially, such that the first format specifier formats input 1, the second format specifier formats input 2, and so on.

Each input can be a string, path, Boolean, enumerated type, timestamp, or numeric value. You cannot use arrays and clusters with this node.

The number of input parameters must match the number of format specifiers in format string. Furthermore, the data type of each input must be compatible with the associated format specifier. Otherwise, the node returns an error.

Note

The value of an enumerated type formatted into the string must match the current value of that enumerated type.

resulting string

The concatenation of initial string and the formatted output.

error out

Error information.

The node produces this output according to standard error behavior.

Standard Error Behavior

error in does not contain an error	error in contains an error

If no error occurred before the node runs, the node begins execution normally. If no error occurs while the node runs, it returns no error. If an error does occur while the node runs, it returns that error information as error out.	If an error occurred before the node runs, the node does not execute. Instead, it returns the error in value as error out.

Troubleshooting "Too few/many format specifiers" Error

These errors occur when you wire a string to format string that contains a different number of format specifiers than there are input parameters. To fix this mismatch, either resize the node to display the same number of inputs as format specifiers, or modify the number of format specifiers in format string to match the number of inputs.

Troubleshooting "Format specifier type mismatch" Error

This error occurs when you wire a string to format string that contains at least one format specifier whose data type specifier is incompatible with the data type of the corresponding input parameter. The text of the error specifies which parameter caused the mismatch. To fix this mismatch, you must change either the data type specifier in the relevant format specifier or wire a compatible data type to the relevant input.

Syntax element(s)	input	format string	output	Comments
%g # modifier	12.00	%#g	12	The node interprets the g specifier as f because the exponent of the input in scientific notation (1) is less than the default precision of 6. The # modifier omits the six zeroes that would normally appear after the decimal based on the default precision of 6.
%g # modifier	12000000	%#g	1.2E+7	The node interprets the g specifier as e because the exponent of the input in scientific notation (7) is greater than the default precision of 6. The # modifier omits the six zeroes that would normally appear after the decimal based on the default precision of 6.
%d literal %	12.67	score= %d%%	score= 13%	Because the d specifier produces an integer output, the input is rounded to the nearest integer. %% produces a literal %.
width precision literal text	12.67	Temp: %5.1f	Temp: 12.7	The 5 in the format specifier specifies a width of 5, and the 1 specifies the precision, or number of digits to the right of the decimal.
overriding units	12.67 N	%5.3f	12.670 N	The format specifier does not include the unit override syntax ({ }), so the output contains the original unit.
	12.67 N	%5.3{mN}f	12670.000 mN	{mN} is compatible with N, so the node makes the appropriate conversion.
	12.67 N	%5.3{kg}f	12.670 ?kg	{kg} is not compatible with N, so no conversion occurs, and the output includes a ?.
converting to engineering notation	12.67	%.3e	1.267E+1	Without the ^ modifier, the e specifier places the decimal to the right of the most significant digit.
converting to engineering notation	12.67	%^.3e	12.670E+0	Adding ^ to the format specifier produces an output in which the exponent is a multiple of 3. This determines the placement of the decimal.
%p precision vs. significant digits	12000000	%.2p	120.00M	Using the decimal point as part of the format specifier impacts the precision, or number of digits after the decimal point in the output. mega (10^6) is the closest SI prefix to the input value, so the output represents the value as M.
%p precision vs. significant digits	12000000	%_2p	120M	Using the _ modifier specifies the number of significant digits in the output. mega (10^6) is the closest SI prefix to the input value, so the output represents the value as M.
non-decimal numbers (%x, %o, %b) padding with zeroes	12	%02x	0C	The 2 in the format specifier causes the output to contain at least 2 characters. The 0 in the format specifier causes 0's to appear as the extra characters required to meet the width.
	12	%06o	000014	The 6 in the format specifier causes the output to contain at least 6 characters. The 0 in the format specifier causes 0's to appear as the extra characters required to meet the width.
	12	%b	1100	This format specifier omits the width, so the output contains only enough characters to represent the input value as a binary number.
%s multiple format specifiers	Smith John	Name: %s, %s.	Name: Smith, John.	The format string must contain two format specifiers because the node accepts two inputs.
variable order	first second	%s %s	first second	format string does not use the $ specifier, so the function populates the percent codes in input order.
	first second	%2$s %1$s	second first	format string uses the $ specifier to display the inputs in a different order than their input order.
	first second	%1$s %1$s %1$s	first first first	format string uses the $ specifier to display the first input multiple times and ignore the second input.
	first second	%2$s %s	error	The first format specifier uses the second input, which causes the next format specifier to want to use a third input. Because there are only two inputs, the node returns an error.

Where This Node Can Run:

Desktop OS: Windows

FPGA: All devices (only within an optimized FPGA VI)

Web Server: Supported in VIs that run in a web application

Table Of Contents

format string

initial string

error in

input

resulting string

error out

Troubleshooting "Too few/many format specifiers" Error

Troubleshooting "Format specifier type mismatch" Error

Recently Viewed Topics

PRODUCT

SUPPORT

COMPANY

MISSION