FormatString

format data into a character stream. (V38)

This function performs C-language-like formatting of a data stream, outputting the result a character at a time. Where % formatting commands are found in the formatting template, they are replaced with the corresponding elements in 'dataStream'. %% must be used in the string if a % is desired in the output.

An extension to the standard C-language printf() conventions used by FormatString() is argument position specification. Specifying the argument position lets the order of the % commands change while the arguments provided remain the same. Using the C printf() call as an example:

These two statements would produce the following output:

The argument positioning feature lets you change the format string being processed while keeping the data stream the same. This is an invaluable tool when translating strings to different languages.

locale

the locale to use for the formatting

fmtTemplate

a C-language-like NULL-terminated format string, with the following supported % options:

%[arg_pos$][flags][width][.limit][length]type

arg_pos - ordinal position of the argument for this command within

the array of arguments pointed to by 'dataStream'
$ - must follow the arg_pos value, if specified

flags - only one allowed. '-' specifies left justification.
width - field width. If the first character is a '0', the

field is padded with leading 0s.
. - must precede the field limit value, if specified

limit - maximum number of characters to output from a string.

(only valid for %s or %b).

length - size of input data defaults to word (16-bit) for types c,

d, u and x, 'l' changes this to long (32-bit).

type - supported types are:

b - BSTR, data is 32-bit BPTR to byte count followed

by a byte string. A NULL BPTR is treated as an
empty string.

d - signed decimal
D - signed decimal using the locale's formatting

conventions

u - unsigned decimal
U - unsigned decimal using the locale's formatting

conventions

x - hexadecimal with hex digits in uppercase
X - hexadecimal with hex digits in lowercase
s - string, a 32-bit pointer to a NULL-terminated

byte string. A NULL pointer is treated
as an empty string.

c - character

If the formatting template parameter is NULL, the
function returns without outputting anything. Note the
meaning of %x and %X are swapped with respect to
standard C conventions. This is for compatibility with
exec.library/RawDoFmt().

next

A pointer to beyond the last data element used in 'dataStream' (the next argument that would have been processed). This allows multiple formatting passes to be made using the same data.

This function formats word values in the data stream. If your compiler defaults to longs, you must add an "l" to your specifications. This can get strange for characters, which might look like "%lc".

If you specify argument positions, please be aware that the number of arguments is limited to 128 whose positions are tracked. If you exceed this limitation, FormatString() will start producing the contents of the remaining format string instead of converting the arguments to text. So, for example, if the 129th conversion specification were "%s" then it would come out as "%s" rather than an empty string. This limitation has existed in all locale.library versions.

All locale.library versions up to and including V46.8 (AmigaOS 3.1.4) default to prepare for positional arguments such as "%2$s", regardless of whether the format string specification calls for it. The preparation may consume up to 1000 bytes of stack space, and your application, library or device should have more than this amount of stack space available if you call the FormatString() function, or the exec.library/RawDoFmt function, which is patched by locale.library to make use of its FormatString() function. locale.library V47.26 (AmigaOS 3.2) will prepare for positional arguments only if the format specification string calls for it. As a precaution, you should always assume that preparations for positional arguments are being made.

Result pointer was unreliable in all versions including 47.14 if any number conversion with grouping characters was being used.

Positional arguments as in "%2$s" could lead to undefined behaviour if the position was given as 0, or if the position was missing altogether ("%$s") in all versions including 47.14.

Only up to 65535 characters of strings used by the %s conversion specification will be copied in all versions including 47.14.

Mixing arguments with specific positions (e.g. "%2$s") and arguments without specific positions (e.g. "%ld") could lead to undefined behaviour in all version including 47.21, with more data read from the argument list than was available and in a different order than what might have been expected. In order to produce reliable results, either use arguments with specific positions in all conversion specifications, or only use conversion specifications without specific argument positions.

In 3.2 (47.26) %d and %D were printed as if unsigned. This is fixed in 3.2.1 (47.27)

exec.library/RawDoFmt()