Format Specifiers

Applies to TestComplete 15.62, last modified on March 19, 2024

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, 1.23e-11 which is 1.23×10-11 in scientific notation. A signed value has the form [ - ]d.dddd e [sign]xx where d is a single decimal digit, dddd is one or more decimal digits, xx is two or three decimal digits of the exponent of 10, and sign is + or -.

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".
}

See Also

aqString Object
Format Method

Highlight search results