RawDoFmt

format data into a character stream.

Perform "C"-language sprintf()-like formatting of a data stream, outputting the result a character at a time. Where '%' formatting commands are found in the FormatString, they will be replaced with the corresponding element in the DataStream. '%%' must be used in the string if a '%' is desired in the output.

Under V36, RawDoFmt() returns a pointer to the end of the DataStream (The next argument that would have been processed). This allows multiple formatting passes to be made using the same data.

FormatString

a "C"-language-like NULL terminated format string, as used by the sprintf() function, with the following supported '%' options:

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

flags

Only one allowed. '-' specifies left justification.

width

Field width. If the first character is a '0', the field will be padded with leading 0's.

. - Must follow the field width, if specified.

limit

Maximum number of characters to output from a string. (only valid for %s).

length

Size of input data defaults to WORD for types d, x, and c, '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, or NULL terminated byte string. A NULL BPTR is treated as an empty string. (Added in V36 exec)

c

character

d

decimal

s

string, a 32-bit pointer to a NULL terminated byte string. In V36, a NULL pointer is treated as an empty string

u

unsigned decimal (Added in V37 exec)

x

hexadecimal

Note:

No support for floating point numbers and no support for octal format integers!

DataStream

A stream of data that is interpreted according to the format string. Often this is a pointer into the Task's stack.

PutChProc

The procedure to call with each character to be output, called as:

PutChProc(Character, PutChData);

D0-0:8 A3

Note:

The PutChProc procedure must preserve the contents of registers D2-D7/A2/A4-A6. Registers D0-D1/A0-A1 are scratch registers and their contents need not be preserved.

The procedure is called with a NULL Character at the end of the format string.

Starting with V45.1, this pointer may be NULL. In that case, the default "stuffChar" procedure shown below in the EXAMPLE section will be used.

PutChData

A value that is passed through to the PutChProc procedure. This is untouched by RawDoFmt, and may be modified by the PutChProc procedure.

This Amiga ROM function expects integer parameter values in the data stream to be 16 bit words with sizeof(int) == 2. Hence, in terms of C99 (ISO/IEC 9899:1999) RawDoFmt() defaults to treat "%d" like "%hd", "%x" like "%hx", etc. and it treats "%c" like "%hc".

Your compiler likely provides 32 bit integers parameter values with sizeof(int) == 4. This means that you will have to add an 'l' (this is the lower case letter "L", indicating that the size of the integer is equivalent to sizeof(long)) modifier to the format specification. Hence, e.g. "%d" must be replaced by "%ld", "%x" must be replaced by "%lx" and "%c" must be replaced by "%lc". This looks peculiar for single character output, but it is what it is. Note that even if a 16 bit integer or an 8 bit character is used as a parameter, the compiler will still promote it to a 32 bit integer value.

RawDoFmt() cannot be used to build a drop-in replacement for the sprintf() function of your 'C' compiler runtime library function. Special care must be taken to verify that the %c, %d, %x and %u formatting is adapted to the peculiar behaviour of RawDoFmt() by adding 'l' (lower case letter "L") to the format specification.

The "locale.library" (introduced with Workbench 2.1) will install its own replacement sprintf()-like formatting code via SetFunction(). This replacement has significantly higher stack size requirements than the original exec.library version of RawDoFmt(). You are best advised to only call RawDoFmt(), even indirectly such as through the dos.library/VPrintf function, if there are more than 1000 bytes of stack space available. The stack size requirements apply to all locale.library versions up to and including V46.8 (AmigaOS 3.1.4), which all default to prepare for positional arguments such as "%2$s", regardless of whether these are used in the format specification string. Starting with locale.library V47.26 (AmigaOS 3.2) will prepare for positional arguments only if the format specification string calls for it. As a general precaution, you should always assume that preparations for positional arguments are being made.

The result of RawDoFmt() is *ONLY* valid in V36 and later releases of EXEC. Pre-V36 versions of EXEC have "random" return values.

NextData

A pointer to the end of the DataStream (The next argument that would have been processed). This allows multiple formatting passes to be made using the same data (V36).

The RawDoFmt() function provides only a limited set of format conversion operations, with the available choices covering what the 1978 first edition of "The 'C' Programming Language" would describe. Hence, the sprintf()-like conversion operations support only "%d", "%x", "%u", "%c" and "%s" conversions, as well as the "%ld", "%lx", "%lu" and "%lc" conversion variants. Floating point number conversion is not supported and neither is conversion of integer values into octal format.

The Kickstart 1.0-1.3 version (V30-V34) of RawDoFmt() was limited to the the "%c", "%d", "%s" and "%x" format specifiers.

Documentation on the 'C' language "sprintf()" function in any 'C' language reference book, locale.library/FormatString()