Format Specifiers

Applies to TestComplete 14.81, last modified on May 04, 2021

This topic describes format specifiers that you can use in the Custom String data generator. Format specifiers define the format of generated values.

The general syntax of a format specifier is as follows:

% [flags] [width][.precision] [modifier] type_identifier macro_regexp_or_string

All of the fields except for the %, type_identifier and macro_regexp_or_string fields are optional.

The sections below describe each of the specifier parts:

Flags Field

The flags field determines 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 (in order to line up with negative numbers if printed in columns).
#

When used with the o, x, or X type identifier, prefix any non-zero generated value with 0, 0x, or 0X, respectively.

When used with the e, E, or f type identifier, even integer values are generated with a decimal point.

When used with the g or G type identifier, force the generated value to contain a decimal point and do not truncate trailing zeros.

The following examples demonstrate how to use the flag format specifier:

%+i%INT(1, 100, 3) <-- Generates a sequence of integer values prefixed with the plus sign
%0.3d[0-9]{2} <-- Generates a sequence of integer values from 0 to 99 with the minimal length of 3. If the generated value’s length is less than 3, TestComplete augments it with the needed number of zeros
%X255 <-- Generates FF (the hexadecimal equivalent of 255 integer)

Width Field

The width field contains the minimum number of characters for the generated value. If the number of characters in the generated value is less than the specified width, blanks are added until the minimum width is reached. If the number of characters in the generated 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 macro demonstrates how to use the width format specifier:

%3d%INT(3, 300, *RND) <-- Generates a sequence of random integer values from 3 to 300 with the minimal length of 3. If the generated value’s length is less than 3, TestComplete augments it with the needed number of spaces.

Precision Field

The precision field depends on the value type and determines the number of characters to be generated, 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 generated value or rounding of a floating-point value.

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 precision field.

Type Identifier The Meaning of the precision Parameter
d, i, u, o, x, X Specifies the minimum number of digits to be generated. If the number of digits the argument contains is less than the one specified in the precision parameter, the generated 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 generated 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 macro demonstrates how to use the precision format specifier:

%#.5x%INT(1,100,3) <-- Generates a sequence of hexadecimal values prefixed with 0x and with the minimal length of 5. If the generated value’s length is less than 5, TestComplete augments it with the needed number of zeros.

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
s, S h Single-byte – character string
l (lowercase L) Wide-character string

The following macro demonstrates how to use the modifier format specifier:

%hs%NAME(ANY,FULL) <-- Generates a sequence of characters that correspond to the first letters of names provided by the %NAME(ANY,FULL) macro

Type Identifier Field

The type_identifier field determines whether the associated argument is interpreted as a character, string, or number.

Type Identifier Input Argument’s Type Output Format
c Character Wide character
C Character 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: signed value having 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: signed value having the form [ – ]d.dddd e [sign]ddd where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is + or –.
E Floating-point Analog to the e format, with the only difference that the exponent is denoted by uppercased 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 Analog to the g format, with the only difference that the exponent is denoted by uppercased E.
S String Single-byte-character string. Characters are displayed up to the first null character or until the precision value is reached.
s String Wide-character string. Characters are displayed up to the first null character or until the precision value is reached.

The following macro demonstrates how to use the type identifier format specifier:

%X%INT(15,100,15) <-- Generates a sequence of hexadecimal integers.

Macro, Regular Expression or String Field

The macro_regexp_or_string field determines the macro, regular expression or string to which the specified format is applied. The specified format is applied until the macro name or another format is specified. For instance:

%X255%s is a hexadecimal value <-- Generates the "FF is a hexadecimal value" string

In the example above, the %s format specifier is used to cancel the %X format specifier.

For more information on general rules used for specifying macros, refer to the About Custom String Generator help topic. For more information on using regular expressions with the Custom String generator, see Custom-String Generator - Supported Regular Expressions.

See Also

About Custom String Generator
Generators
Using Data Generators

Highlight search results