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:

Type Identifier Field

Macro, Regular Expression or String Field

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

Format Specifiers

Flags Field

Width Field

Precision Field

Modifier Field

Type Identifier Field

Macro, Regular Expression or String Field

See Also