String formatting

This is about 'String/Composite formatting' used in ProtoFlux/Component String functions.

For 'Rich Text Formatting', see: Text formatting

Types of string formatting

There are two main types of string formatting: "Format Strings" which specify how a single value, and "Composite Format Strings" which specify how to format multiple values, and can sometimes contain "Format Strings" within them.

Format String

Format strings are a concept present in C# and have been thoroughly documented by Microsoft on their documentation page. Some users find this documentation too complicated so a simplified explanation of how they work is also present here.

A format string describes how a value should be converted to a string, this is most commonly used by the ToString node. Different value types have different options on what is considered valid. For example you can format a float with the string "F2" to show 2 decimal places, and an int with "X" to show the number as hexadecimal, but you cannot use "X" with a float. The output is also determined by your locale/language, which means the output of the formatting could be different locally for each user, depending on their language setting. Consider providing an explicit IFormatProvider if you do not like that behavior. The most common issue that arises because of localization is that some countries use a comma, and others a period as the decimal separator.

Enum formatting

If a source is an enum field, it is formatted as its name (for example Active) rather than the numeric value.

Number formatting

Standard Numeric Format Strings

Specifier	Name	Description	Example Input	Example Output
"C" or "c"	Currency	Result: A currency value. Supported by: All numeric types. Precision specifier: Number of decimal digits.	Input Value: 20.501 Format String: {0:c}	$20.50
			Input Value: 20.501 Format String: {0:c3}	$20.501
"D" or "d"	Decimal	Result: Integer digits with optional negative sign. Supported by: Integral types only. Precision specifier: Minimum number of digits. Default precision specifier: Minimum number of digits required	Input Value: 1234 Format String: {0:d}	1234
			Input value: -1234 Format String: {0:d6}	-001234
"E" or "e"	Exponential (scientific)	Result: Exponential notation. Supported by: All numeric types. Precision specifier: Number of decimal digits. Default precision specifier: 6.	Input Value: 1052.0329112756 Format String: {0:e}	1.052033E+003
			Input value: -1052.0329112756 Format String: {0:e2}	-1.05e+003
"F" or "f"	Fixed-point	Result: Integral and decimal digits with optional negative sign. Supported by: All numeric types. Precision specifier: Number of decimal digits. Default precision specifier: Defined by NumberFormatInfo.NumberDecimalDigits. Usually 2.	Input Value: 1234.567 Format String: {0:f}	1234.57
			Input value: 1234 Format String: {0:f1}	1234.0
"G" or "g"	General	Result: The more compact of either fixed-point or scientific notation. Supported by: All numeric types. Precision specifier: Number of significant digits. Default precision specifier: Depends on numeric type.	Input Value: 0.01 Format String: {0:g}	0.01
			Input value: 200.2 Format String: {0:g2}	2e+02
"N" or "n"	number	The numeric ("N") format specifier converts a number to a string of the form "-d,ddd,ddd.ddd…", where "-" indicates a negative number symbol if required, "d" indicates a digit (0-9), "," indicates a group separator, and "." indicates a decimal point symbol. Supported by: All numeric types. Precision specifier: Desired number of decimal places. Default precision specifier: Defined by NumberFormatInfo.NumberDecimalDigits. Usually 2.	Input Value: 12345 Format String: {0:n}	12,345.00
			Input value: 4567.22 Format String: {0:n1}	4,567.2
"P" or "p"	Percent	Result: Number multiplied by 100 and displayed with a percent symbol. Supported by: All numeric types. Precision specifier: Desired number of decimal places.	Input Value: 0.451 Format String: {0:p}	45.10%
			Input value: 0.98221 Format String: {0:p0}	98%
			Input value: 0.22222 Format String: {0:p1}	22.2%
"R" or "r"	Round-trip	The round-trip ("R") format specifier attempts to ensure that a numeric value that is converted to a string is parsed back into the same numeric value. This format is supported only for the float and double types in Resonite. It is recommended to use the "G" specifier instead.	Input Value: 2345.001 Format String: {0:r}	2345.001
			Input value: 123456789.123 Format String: {0:r}	123456789.123
"X" or "x"	Hexadecimal	Result: A hexadecimal string. Supported by: Integral types only. Precision specifier: Number of digits in the result string. Capitalization of the 'x' affects the capitalization of non-digit hex characters.	Input Value: 123 Format String: {0:x}	7b
			Input value: 123 Format String: {0:X}	7B
			Input value: 31 Format String: {0:X4}	001F

Custom Numeric Format Strings

These format strings give you a way to customize how a value is formatted as a string, instead of the preset standard ones from the previous table.

Specifier	Name	Description	Example Input	Example Output
"0"	Zero placeholder	Replaces the zero with the corresponding digit if one is present; otherwise, zero appears in the result string.	Input value: 1234.1 Format string: {0:0000}	1234
			Input value: 1234.1 Format string: {0:00000.0}	01234.1
"#"	Digit placeholder	Replaces the "#" symbol with the corresponding digit if one is present; otherwise, no digit appears in the result string. Note that no digit appears in the result string if the corresponding digit in the input string is a non-significant 0. For example, 0003 with format {0:####} -> 3.	Input value: 1234.5678 Format string: {0:#####}	1235
			Input value: 0.3737 Format string: {0:#.##}	.37
"."	Decimal point	Determines the location of the decimal separator in the result string.	Shown in other examples

Composite Formatting

Composite Format Strings are a concept present in C# and have been thoroughly documented by Microsoft on their documentation page. Some users find this documentation too complicated so a simplified explanation of how they work is also present here.

A composite format string describes how one or many values should be displayed. It consists of regular text and placeholder specifiers which are surrounded by curly braces.

Placeholders

A placeholder specifier contains the index of the argument it wants to display within curly braces. For example "{0}" would display the first argument, "{1}" the 2nd, and so on.

Format String

A placeholder specifier can specify a format string, which is placed after the index separated by a colon. For example "{0:F2}" would print the first argument with 2 decimal places.

Padding

A placeholder specifier can specify padding, which is placed after the index, but before the format string.

In output examples below, · means a space character.

Syntax	Padding	Value	Output
{0,3}	Spaces on the left	42	·42
{0,3}	Spaces on the left	7	··7
{0,4}	Spaces on the left	42	··42
{0,4}	Spaces on the left	7	···7
{0,-3}	Spaces on the right	42	42·
{0,-3}	Spaces on the right	7	7··

The width number only applies to the value inside the placeholder, not the rest of the format string. For example, {0,3} FPS pads {0} to 3 characters — the FPS part is left alone.

If the value is already as long or longer than the width, nothing gets cut off. {0,3} with 7 becomes ··7, but with 1200 it stays 1200.

Examples

Simple values

Sources	Format	Output
[0] = 42 (int)	Score: {0}	Score: 42
[0] = Decoy (String)	User: {0}	User: Decoy

Multiple sources

Each field in Sources maps to a placeholder by its list position:

• Sources[0] → {0}
• Sources[1] → {1}

Sources[0]	Sources[1]	Format	Output
3 (int)	10 (int)	Page {0} of {1}	Page 3 of 10
Decoy (String)	72 (int)	{0}: {1} FPS	Decoy: 72 FPS

See Also

Components

• ValueTextFormatDriver
• MultiValueTextFormatDriver

Protoflux Nodes

• FormatString
• ToString