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:
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:
The flags field determines the alignment of numeric values and whether signs, blanks, decimal points, octal and hexadecimal prefixes should be used.
|-||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:
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:
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:
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|
|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:
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|
|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:
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:
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.