newObjects ActiveX Pack1 Format specification syntax
 

The general syntax of the format specification implies that there is a set of arguments (or elements if array or a collection variants of the methods are used) which are replaced in the format string in the order in which they appear. For example the first argument will be used for the first control escape, the second for the second control escape and so on.

The format string consists of text and embedded control escapes.  Each control escape begins with the % character and ends according to the syntax specified below. To output a % character you need to repeat the % twice - e.g. a "%%" in the format string will produce only one "%" in the output.

The general syntax for a control escape sequence is:

%[[name] | (index)] [flags] [width] [.precision] [{h | l}] [N] type

As it is shown above only the type part is required. The other parts are specified if more detailed control over the format is needed.

Here are the descriptions of each part:

[name] | (index)

Optionally you can use one of the both - name or index specified immediately after the % character to break the natural order of the parameters formatted into the output. 

name:  If specified it is enclosed in [] - for example "something %[name1]020d" means argument named "name1" to be formatted in 20 chars wide field padded with zeros. The name must be less then 255 characters long. This feature will have any effect only if the method in which the format string is specified uses a parameter source which supports names. For instance specifying name with Sprintf or SAprintf will have no effect while in SCprintf it will work ok - as long as the collection/dictionary object supplied as argument supports names. After the named argument is fetched and formatted one argument is skipped in the internal argument index. Thus if the first escape names an argument which is let say 5-th in the collection and the second escape sequence does not use [name] nor (index) it will fetch the second argument - not the first! See the notice below for useful recommendations.

Is it case sensitive? This depends on the source (e.g. in SCprintf the collection/dictionary object passed as argument). If it treats the names in case insensitive manner the name will be case insensitive if not the case will matter. Try to lookup this information in the collection object documentation. Most collections use case-insensitive names, but there are exceptions. 

index: (added in axpack1 version 2.4.5.0) If specified it is enclosed in () - for example "something %(2)020d" means argument 2  to be formatted in 20 chars wide field padded with zeros. The number should be positive and is 0 - based. This feature works with all the printf methods. Note that using index breaks the natural order of the parameters. Therefore the next parameter fetched will be the index + 1 argument! For example:

o.Sprintf("%d,%(2)d,%d,%(1)d",0,1,2,3) will return "0,2,3,1" - i.e. the 3-d escape will fetch the next argument after the argument number 2 which means the last argument, instead of fetching the 3-d argument as you may expect.

The index is 0 based even if in SCprintf you use as argument a collection that is 1-based. The SCprintf will automatically recognize the collection base index and transpose the indices internally.

Notice

It is recommended to use [name] and (index) specifications for all the format sequences in the format string or for none at all. If named/indexed and unnamed and non-indexed specifications are mixed the result can be misleading because of the changes to the natural order in which the arguments are fetched. Of course, you can calculate carefully what will happen after using [name] or (index), but still this can be a source for human made mistakes. 

negative (index) is accepted by the format parser, but is not currently used for anything. This is reserved for future versions.  

Flags

The flags are single characters found first in the escape command sequence. If the combination is meaningful more than one flag can be specified.

Flag Meaning Default behavior
- Left align the result in the given field width. Have no effect if width is not specified. Right align.
+ Prefix the output value with a sign (+ or -) if applicable. Only negative numbers will be displayed with a "-" sign.
0 Left-padding the result with 0-s to fill the field width. Has effect only if width is specified. No padding.
blank " "
(space)
Like previous but the value is padded with spaces.
# Force 0x, 0X or 0 prefixes for hexdecimal and octal values.
Or forces decimal point to be displayed for floating point values even if they have no digits following it.
No prefixes. No decimal point if only zeros follows it. Trailing zeros are truncated.
...

Width

Specifies the minimum width of the field in which the value will be placed. If the value requires more space the field width will be extended to fit. When the value is shorter it is padded left or right with blanks or 0-s (according to the flags and default behaviors specified in the Flags section).

Width is non-negative decimal integer or a * character. In case of * the function fetches the next argument/element and tries to convert it to integer that specifies the actual field width to be used.

Precision

Non-negative integer preceded with . that specifies the number of characters or decimal places for the value. The effect depends on the type as follows:

d,i,u,o,x,X - The minimal number of digits. The number is padded with zeros to fit the precision specified. Default is 1.

e,E - Number of digits after the decimal point.

f - The precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits.

g,G - The precision specifies the maximum number of significant digits printed

Currently has no effect over the other types. You should not use it if no effect is expected in order to avoid incompatibility with future versions.

Type modifiers

One of h or l (small L) can be specified to modify the size of the type to which the argument is converted. They have effect on the following types as follows:

base type prefixed with l (small L) prefixed with h
d, i No effect on Win32 platforms converted to VT_I2
u,x,X,o No effect on Win32 platforms converted to VT_UI2
t DateTimeFormat is used TimeFormat is used
T DateTimeFormat is used DateFormat is used

N - Allow nulls. If specified this allows the argument to be Null and the NullName is put instead of error.

The L (capital L) is not used in the current version, but it is reserved for future functionality extensions.

Types

Each type character instructs the function to fetch the next argument and try to convert it to a certain type. If this succeeds it is formatted according to the other parameters specified before it in the escape command sequence (the flags, width, precision etc.). If the argument cannot be converted an error occurs (it states the index of the argument at which it has been occurred). If the argument is Null (VT_NULL VARIANT type) error occurs unless N is specified before the type, which allows the Null-s to be displayed with the name specified by the NullName property.

Character Converted to type Output format
c VT_I4 (vbLong) which is then used as UNICODE character code that specifies which character to be displayed. one character.
d, i VT_I4 (vbLong) Signed decimal integer.
o VT_UI4 Unsigned octal integer
x VT_UI4 Unsigned hexdecimal integer (small a,b,c .. are used)
X VT_UI4 Unsigned hexdecimal integer (capital A,B,B .. are used)
u VT_UI4 Unsigned decimal integer.
e,E VT_R8 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 –. Small e is used for the exponent if e is specified and capital E is used if E is specified
f VT_R8 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.
g,G VT_R8 Signed value printed in 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. Depending on which character is specified g or G the exponent is displayed with small e or capital E if it appears.
M VT_R8 Double value formatted with maximum precision. Equivalent to G with very high precision setting. Intended for usage in SQL statement generation tasks where the precision must be preserved (See SQLiteCOM.Execute method).
s VT_BSTR String.
q VT_BSTR Quoted with ' and escaped string. The string is enclosed in ' ... ' quotes. If the ' character appears in the string it is escaped by duplicating it (good for SQL statements).
Q VT_BSTR Like q but " is used and escaped instead of '.
t VT_DATE Time in the format specified by the TimeFormat property.
T VT_DATE Date and time in the format specified by the DateTimeFormat property

 

 

newObjects Copyright 2001-2006 newObjects [ ]