This topic describes format specifiers that you can use in the aqString.Format method. Format specifiers define how the method will convert its argument or a generated value to a string.
The general syntax of a format specifier is as follows:
The % marker and the type_identifier field are required, other parts of the format specifier are optional.
To treat the % symbol literally, duplicate it (%%).
Type Identifier Field
The type_identifier field determines whether an argument is interpreted as a character, string, or number.
| Type Identifier | Input Argument’s Type | Output Format |
|---|---|---|
| c | Integer |
Wide character |
| C | Integer |
Single-byte character |
| d, i | Integer |
Signed decimal integer |
| u | Integer |
Unsigned decimal integer |
| o | Integer |
Unsigned octal integer |
| x | Integer |
Unsigned hexadecimal integer, using "abcdef" |
| X | Integer |
Unsigned hexadecimal integer, using "ABCDEF" |
| f | Floating-point |
Number in standard notation. A signed value has the form [ – ]dddd.dddd where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision. |
| e | Floating-point |
Number in exponential notation, for instance, |
| E | Floating-point |
The same as e, but the exponent is denoted by the uppercase E. |
| g | Floating-point |
Signed value either in the f or e format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than –4 or greater than or equal to the precision argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it. |
| G | Floating-point |
The same as g, but the exponent is denoted by the uppercase E. |
| s, S | String |
Wide-character string. Characters are displayed up to the first null character or until the precision value is reached. |
The following example shows how to use the type identifier format specifier:
JavaScript, JScript
function DemoFormatSpecifiers_TypeIdentifier()
{
Log.Message(aqString.Format("This is a %s string.", "sample"));
// The "S" type identifier determines that the argument is treated as a string.
// Posts "This is a sample string."
Log.Message(aqString.Format("The character with the ANSII code 90: %c", 90));
// The "c" type identifier determines that the argument is treated as a character.
// Posts "The character with ANSII code 90: Z"
Log.Message(aqString.Format("The hexadecimal notation for 42: %X", 42));
// The "X" type identifier determines that the argument is treated as a hexadecimal value.
// Posts "The hexadecimal notation for 42: is 2A".
}
Python
def DemoFormatSpecifiers_TypeIdentifier():
Log.Message(aqString.Format("This is a %s string.", "sample"))
# The "S" type identifier determines that the argument is treated as a string.
# Posts "This is a sample string."
Log.Message(aqString.Format("The character with the ANSII code 90: %c", 90))
# The "c" type identifier determines that the argument is treated as a character.
# Posts "The character with ANSII code 90: Z"
Log.Message(aqString.Format("The hexadecimal notation for 42: %X", 42))
# The "X" type identifier determines that the argument is treated as a hexadecimal value.
# Posts "The hexadecimal notation for 42: is 2A".VBScript
Sub DemoFormatSpecifiers_TypeIdentifier
Log.Message(aqString.Format("This is a %s string.", "sample"))
' The "S" type identifier determines that the argument is treated as a string.
' Posts "This is a sample string."
Log.Message(aqString.Format("The character with the ANSII code 90: %c", 90))
' The "c" type identifier determines that the argument is treated as a character.
' Posts "The character with ANSII code 90: Z"
Log.Message(aqString.Format("The hexadecimal notation for 42: %X", 42))
' The "X" type identifier determines that the argument is treated as a hexadecimal value.
' Posts "The hexadecimal notation for 42: is 2A".
End Sub
DelphiScript
procedure DemoFormatSpecifiers_TypeIdentifier;
begin
Log.Message(aqString.Format('This is a %s string.', 'sample'));
// The "S" type identifier determines that the argument is treated as a string.
// Posts "This is a sample string."
Log.Message(aqString.Format('The character with the ANSII code 90: %c', 90));
// The "c" type identifier determines that the argument is treated as a character.
// Posts "The character with ANSII code 90: Z"
Log.Message(aqString.Format('The hexadecimal notation for 42: %X', 42));
// The "X" type identifier determines that the argument is treated as a hexadecimal value.
// Posts "The hexadecimal notation for 42: is 2A".
end;
C++Script, C#Script
function DemoFormatSpecifiers_TypeIdentifier()
{
Log["Message"](aqString["Format"]("This is a %s string.", "sample"));
// The "S" type identifier determines that the argument is treated as a string.
// Posts "This is a sample string."
Log["Message"](aqString["Format"]("The character with the ANSII code 90: %c", 90));
// The "c" type identifier determines that the argument is treated as a character.
// Posts "The character with ANSII code 90: Z"
Log["Message"](aqString["Format"]("The hexadecimal notation for 42: %X", 42));
// The "X" type identifier determines that the argument is treated as a hexadecimal value.
// Posts "The hexadecimal notation for 42: is 2A".
}
Flags Field
The flags field sets the alignment of numeric values and whether signs, blanks, decimal points, octal and hexadecimal prefixes should be used.
| Flag | Description |
|---|---|
| - | Force left adjustment, by padding (out to the field width) on the right. |
| + | Prefix positive numbers with a leading plus sign. |
| 0 | Prefix numbers with zeros until the minimum width is reached. |
| space (' ') | Prefix positive numbers with an extra space (to line up with negative numbers if printed in columns). |
| # |
When used with the o, x, or X type identifier, prefix any non-zero output value with 0, 0x, or 0X, respectively.
When used with the e, E, or f type identifier, show values (even integer ones) with a decimal point. When used with the g, or G type identifier, force the output to contain a decimal point and do not truncate trailing zeros. |
The following example shows how to use the flag specifier:
JavaScript, JScript
function DemoFormatSpecifiers_Flags()
{
Log.Message(aqString.Format("Value prefixed with spaces: % i", 16));
// The " "(space) flag specifies that the value should be prefixed with a space.
// Posts "Value prefixed with spaces: 16".
Log.Message(aqString.Format("Positive value prefixed with the plus sign: %+i", 100));
// The "+" flag specifies that positive values should be prefixed with the "+" sign.
// Posts "Positive value prefixed with the plus sign: +100".
Log.Message(aqString.Format("Hexadecimal value prefixed with 0x: %#x", 18));
// The "#” flag used with the "x" type identifier specifies that hexadecimal values are prefixed with "0x".
// Posts "Hexadecimal value prefixed with 0x: 0x12".
}
Python
def DemoFormatSpecifiers_Flags():
Log.Message(aqString.Format("Value prefixed with spaces: % i", 16))
# The " "(space) flag specifies that the value should be prefixed with a space.
# Posts "Value prefixed with spaces: 16".
Log.Message(aqString.Format("Positive value prefixed with the plus sign: %+i", 100))
# The "+" flag specifies that positive values should be prefixed with the "+" sign.
# Posts "Positive value prefixed with the plus sign: +100".
Log.Message(aqString.Format("Hexadecimal value prefixed with 0x: %#x", 18))
# The "#” flag used with the "x" type identifier specifies that hexadecimal values are prefixed with "0x".
# Posts "Hexadecimal value prefixed with 0x: 0x12".VBScript
Sub DemoFormatSpecifiers_Flags
Log.Message(aqString.Format("Value prefixed with spaces: % i", 16))
' The " "(space) flag specifies that the value should be prefixed with a space.
' Posts "Value prefixed with spaces: 16".
Log.Message(aqString.Format("Positive value prefixed with the plus sign: %+i", 100))
' The "+" flag specifies that positive values should be prefixed with the "+" sign.
' Posts "Positive value prefixed with the plus sign: +100".
Log.Message(aqString.Format("Hexadecimal value prefixed with 0x: %#x", 18))
' The "#” flag used with the "x" type identifier specifies that hexadecimal values are prefixed with "0x".
' Posts "Hexadecimal value prefixed with 0x: 0x12".
End Sub
DelphiScript
procedure DemoFormatSpecifiers_Flags;
begin
Log.Message(aqString.Format('Value prefixed with spaces: % i', 16));
// The " "(space) flag specifies that the value should be prefixed with a space.
// Posts "Value prefixed with spaces: 16".
Log.Message(aqString.Format('Positive value prefixed with the plus sign: %+i', 100));
// The "+" flag specifies that positive values should be prefixed with the "+" sign.
// Posts "Positive value prefixed with the plus sign: +100".
Log.Message(aqString.Format('Hexadecimal value prefixed with 0x: %#x', 18));
// The "#” flag used with the "x" type identifier specifies that hexadecimal values are prefixed with "0x".
// Posts "Hexadecimal value prefixed with 0x: 0x12".
end;
C++Script, C#Script
function DemoFormatSpecifiers_Flags()
{
Log["Message"](aqString["Format"]("Value prefixed with spaces: % i", 16));
// The " "(space) flag specifies that the value should be prefixed with a space.
// Posts "Value prefixed with spaces: 16".
Log["Message"](aqString["Format"]("Positive value prefixed with the plus sign: %+i", 100));
// The "+" flag specifies that positive values should be prefixed with the "+" sign.
// Posts "Positive value prefixed with the plus sign: +100".
Log["Message"](aqString["Format"]("Hexadecimal value prefixed with 0x: %#x", 18));
// The "#” flag used with the "x" type identifier specifies that hexadecimal values are prefixed with "0x".
// Posts "Hexadecimal value prefixed with 0x: 0x12".
}
Width Field
The width field sets the minimum number of characters for the output value. If the number of characters in the output value is less than the specified width, blanks are added until the minimum width is reached. If the number of characters in the output value is greater than the specified width, or if the width is not given, all the characters of the value are displayed.
The value of the field can be either a positive integer or an asterisk (*). An asterisk indicates that the next integer argument from the argument list should be used as the value of the width field.
The following example shows how to use the width specifier:
JavaScript, JScript
function DemoFormatSpecifiers_Width()
{
Log.Message(aqString.Format("String of the 12-character length: %12s", "Test"));
// The "12" value specifies the minimum width of the output value.
// Blanks are added to the "Test" string until the width is reached.
// Posts "String of the 12-character length: Test".
Log.Message(aqString.Format("Integer value of the 3-digit length: %0*i", 3, 5));
// The "*" indicates that the next integer argument in the argument list specifies the minimum width.
// The output value minimum width is 3.
// The "0" flag indicates that the value will be prefixed with zeros until the width is reached.
// Posts "Integer value of the 3-digit length: 005".
}
Python
def DemoFormatSpecifiers_Width():
Log.Message(aqString.Format("String of the 12-character length: %12s", "Test"))
# The "12" value specifies the minimum width of the output value.
# Blanks are added to the "Test" string until the width is reached.
# Posts "String of the 12-character length: Test".
Log.Message(aqString.Format("Integer value of 3-digit length: %0*i", 3, 5))
# The "*" indicates that the next integer argument in the argument list specifies the minimum width.
# The output value minimum width is 3.
# The "0" flag indicates that the value will be prefixed with zeros until the width is reached.
# Posts "Integer value of the 3-digit length: 005".VBScript
Sub DemoFormatSpecifiers_Width
Log.Message(aqString.Format("String of the 12-character length: %12s", "Test"))
' The "12" value specifies the minimum width of the output value.
' Blanks are added to the "Test" string until the width is reached.
' Posts "String of the 12-character length: Test".
Log.Message(aqString.Format("Integer value of 3-digit length: %0*i", 3, 5))
' The "*" indicates that the next integer argument in the argument list specifies the minimum width.
' The output value minimum width is 3.
' The "0" flag indicates that the value will be prefixed with zeros until the width is reached.
' Posts "Integer value of the 3-digit length: 005".
End Sub
DelphiScript
procedure DemoFormatSpecifiers_Width;
begin
Log.Message(aqString.Format('String of the 12-character length: %12s', 'Test'));
// The "12" value specifies the minimum width of the output value.
// Blanks are added to the "Test" string until the width is reached.
// Posts "String of the 12-character length: Test".
Log.Message(aqString.Format('Integer value of the 3-digit length: %0*i', 3, 5));
// The "*" indicates that the next integer argument in the argument list specifies the minimum width.
// The output value minimum width is 3.
// The "0" flag indicates that the value will be prefixed with zeros until the width is reached.
// Posts "Integer value of the 3-digit length: 005".
end;
C++Script, C#Script
function DemoFormatSpecifiers_Width()
{
Log["Message"](aqString["Format"]("String of the 12-character length: %12s", "Test"));
// The "12" value specifies the minimum width of the output value.
// Blanks are added to the "Test" string until the width is reached.
// Posts "String of the 12-character length: Test".
Log["Message"](aqString["Format"]("Integer value of the 3-digit length: %0*i", 3, 5));
// The "*" indicates that the next integer argument in the argument list specifies the minimum width.
// The output value minimum width is 3.
// The "0" flag indicates that the value will be prefixed with zeros until the width is reached.
// Posts "Integer value of the 3-digit length: 005".
}
Precision Field
The precision field depends on the value type and determines the number of characters to be displayed, the number of decimal places, or the number of significant digits. The description of each affected type is provided in the table below. Unlike width specification, precision specification can cause either truncation of the output value or rounding of a floating-point value.
The precision value can be either a positive integer or an asterisk (*). An asterisk means that the next integer argument from the argument list should be used as the value of the precision field.
| Type Identifier | The Meaning of the Precision Parameter |
|---|---|
| d, i, u, o, x, X | Specifies the minimum number of digits to display. If the number of digits in the argument is less than the number specified in the precision parameter, the output value is padded on the left with zeros. The value is not truncated if the number of digits exceeds the value specified in the precision parameter. |
| e, E, f | Specifies the number of digits after the decimal point. The last printed digit is rounded. |
| g, G | Specifies the maximum number of significant digits. |
| s, S | Specifies the maximum number of characters. If the string contains more characters than the precision parameter specifies, the trailing characters are not displayed. |
The following example shows how to use the precision specifier:
JavaScript, JScript
function DemoFormatSpecifiers_Precision()
{
Log.Message(aqString.Format("Hexadecimal value displaying 5 digits prefixed with 0x: %#.5x", 1439));
// The precision value "5" used with the "x" type identifier specifies that 5 digits are to be displayed.
// Posts "The hexadecimal value displaying 5 digits prefixed with 0x: 0x0059f".
Log.Message(aqString.Format("Value in the standard notation with 3 digits after the decimal point: %.3f", 1234.8765));
// The precision value "3" specifies that 3 digits after the decimal point are to be displayed.
// Posts "The value in the standard notation with 3 digits after the decimal point: 1234.877".
Log.Message(aqString.Format("Value in the exponential notation with 2 digits after the decimal point: %.*e", 2, 1234.56789));
// "*" indicates that the next integer argument in the argument list specifies the precision value.
// Posts "The value in the exponential notation with 2 digits after the decimal point: 1.23e+003".
Log.Message(aqString.Format("The trailing characters of the following '%s' string are not displayed: %.3s", "Test", "Test"))
// The precision value specifies the maximum number of characters in the string value.
// Posts ”The trailing characters of the following 'Test' string are not displayed: Tes".
}
Python
def DemoFormatSpecifiers_Precision():
Log.Message(aqString.Format("Hexadecimal value displaying 5 digits prefixed with 0x: %#.5x", 1439))
# The precision value "5" used with the "x" type identifier specifies that 5 digits are to be displayed.
# Posts "The hexadecimal value displaying 5 digits prefixed with 0x: 0x0059f".
Log.Message(aqString.Format("Value in the standard notation with 3 digits after the decimal point: %.3f", 1234.8765))
# The precision value "3" specifies that 3 digits after the decimal point are to be displayed.
# Posts "The value in the standard notation with 3 digits after the decimal point: 1234.877".
Log.Message(aqString.Format("Value in the exponential notation with 2 digits after the decimal point: %.*e", 2, 1234.56789))
# "*" indicates that the next integer argument in the argument list specifies the precision value.
# Posts "The value in the exponential notation with 2 digits after the decimal point: 1.23e+003".
Log.Message(aqString.Format("The trailing characters of the following '%s' string are not displayed: %.3s", "Test", "Test"))
# The precision value specifies the maximum number of characters in the string value.
# Posts ”The trailing characters of the following 'Test' string are not displayed: Tes".
#endfield
#region ModifierField
def DemoFormatSpecifier_Modifier():
Log.Message(aqString.Format("%hi", 32768))
# The "h" modifier determines that the argument is treated like a 2-byte integer.
# Posts "-32768".
Log.Message(aqString.Format("%li", 32768))
# The "l" modifier determines that the argument is treated like a 4-byte integer.
# Posts "32768".VBScript
Sub DemoFormatSpecifiers_Precision
Log.Message(aqString.Format("Hexadecimal value displaying 5 digits prefixed with 0x: %#.5x", 1439))
' The precision value "5" used with the "x" type identifier specifies that 5 digits are to be displayed.
' Posts "The hexadecimal value displaying 5 digits prefixed with 0x: 0x0059f".
Log.Message(aqString.Format("Value in the standard notation with 3 digits after the decimal point: %.3f", 1234.8765))
' The precision value "3" specifies that 3 digits after the decimal point are to be displayed.
' Posts "The value in the standard notation with 3 digits after the decimal point: 1234.877".
Log.Message(aqString.Format("Value in the exponential notation with 2 digits after the decimal point: %.*e", 2, 1234.56789))
' "*" indicates that the next integer argument in the argument list specifies the precision value.
' Posts "The value in the exponential notation with 2 digits after the decimal point: 1.23e+003".
Log.Message(aqString.Format("The trailing characters of the following '%s' string are not displayed: %.3s", "Test", "Test"))
' The precision value specifies the maximum number of characters in the string value.
' Posts ”The trailing characters of the following 'Test' string are not displayed: Tes".
End Sub
DelphiScript
procedure DemoFormatSpecifiers_Precision;
begin
Log.Message(aqString.Format('Hexadecimal value displaying 5 digits prefixed with 0x: %#.5x', 1439));
// The precision value "5" used with the "x" type identifier specifies that 5 digits are to be displayed.
// Posts "The hexadecimal value displaying 5 digits prefixed with 0x: 0x0059f".
Log.Message(aqString.Format('Value in the standard notation with 3 digits after the decimal point: %.3f', 1234.8765));
// The precision value "3" specifies that 3 digits after the decimal point are to be displayed.
// Posts "The value in the standard notation with 3 digits after the decimal point: 1234.877".
Log.Message(aqString.Format('Value in the exponential notation with 2 digits after the decimal point: %.*e', 2, 1234.56789));
// "*" indicates that the next integer argument in the argument list specifies the precision value.
// Posts "The value in the exponential notation with 2 digits after the decimal point: 1.23e+003".
Log.Message(aqString.Format('The trailing characters of the following "%s"; string are not displayed: %.3s', 'Test', 'Test'));
// The precision value specifies the maximum number of characters in the string value.
// Posts "The trailing characters of the following "Test" string are not displayed: Tes".
end;
C++Script, C#Script
function DemoFormatSpecifiers_Precision()
{
Log["Message"](aqString["Format"]("Hexadecimal value displaying 5 digits prefixed with 0x: %#.5x", 1439));
// The precision value "5" used with the "x" type identifier specifies that 5 digits are to be displayed.
// Posts "The hexadecimal value displaying 5 digits prefixed with 0x: 0x0059f".
Log["Message"](aqString["Format"]("Value in the standard notation with 3 digits after the decimal point: %.3f", 1234.8765));
// The precision value "3" specifies that 3 digits after the decimal point are to be displayed.
// Posts "The value in the standard notation with 3 digits after the decimal point: 1234.877".
Log["Message"](aqString["Format"]("Value in the exponential notation with 2 digits after the decimal point: %.*e", 2, 1234.56789));
// "*" indicates that the next integer argument in the argument list specifies the precision value.
// Posts "The value in the exponential notation with 2 digits after the decimal point: 1.23e+003".
Log["Message"](aqString["Format"]("The trailing characters of the following '%s' string are not displayed: %.3s", "Test", "Test"))
// The precision value specifies the maximum number of characters in the string value.
// Posts ”The trailing characters of the following 'Test' string are not displayed: Tes".
}
Modifier Field
The modifier field specifies the size of the given argument. The possible combinations are:
| Type Identifier | Modifier | Argument size |
|---|---|---|
| d, i, o, x, X | h | 2-byte integer |
| l (lowercase L) | 4-byte integer | |
| I32 | 32-bit integer | |
| I64 | 64-bit integer | |
| I | 32-bit integer on 32-bit platforms and 64-bit integer on 64-bit platforms | |
| o, u, x, X | h | unsigned 2-byte integer |
| l (lowercase L) | unsigned 4-byte integer | |
| I32 | unsigned 32-bit integer | |
| I64 | unsigned 64-bit integer | |
| I | unsigned 32-bit integer on 32-bit platforms and unsigned 64-bit integer on 64-bit platforms | |
| c, C | h | Single-byte character |
| l (lowercase L) | Wide character |
The following example shows how to use the modifier format specifier:
JavaScript, JScript
function DemoFormatSpecifier_Modifier()
{
Log.Message(aqString.Format("%hi", 32768));
// The "h" modifier determines that the argument is treated like a 2-byte integer.
// Posts "-32768".
Log.Message(aqString.Format("%li", 32768));
// The "l" modifier determines that the argument is treated like a 4-byte integer.
// Posts "32768".
}
Python
def DemoFormatSpecifier_Modifier():
Log.Message(aqString.Format("%hi", 32768))
# The "h" modifier determines that the argument is treated like a 2-byte integer.
# Posts "-32768".
Log.Message(aqString.Format("%li", 32768))
# The "l" modifier determines that the argument is treated like a 4-byte integer.
# Posts "32768".VBScript
Sub DemoFormatSpecifier_Modifier
Log.Message(aqString.Format("%hi", 32768))
' The "h" modifier determines that the argument is treated like a 2-byte integer.
' Posts "-32768".
Log.Message(aqString.Format("%li", 32768))
' The "l" modifier determines that the argument is treated like a 4-byte integer.
' Posts "32768".
End Sub
DelphiScript
procedure DemoFormatSpecifier_Modifier;
begin
Log.Message(aqString.Format('%hi', 32768));
// The "h" modifier determines that the argument is treated like a 2-byte integer.
// Posts "-32768".
Log.Message(aqString.Format('%li', 32768));
// The "l" modifier determines that the argument is treated like a 4-byte integer.
// Posts "32768".
end;
C++Script, C#Script
function DemoFormatSpecifier_Modifier()
{
Log["Message"](aqString["Format"]("%hi", 32768));
// The "h" modifier determines that the argument is treated like a 2-byte integer.
// Posts "-32768".
Log["Message"](aqString["Format"]("%li", 32768));
// The "l" modifier determines that the argument is treated like a 4-byte integer.
// Posts "32768".
}