Autodocs
Libraries:
locale.library
--environment_vars--
--rexxhost--
--structures--
CloseCatalog
CloseLocale
ConvToLower
ConvToUpper
FormatDate
FormatString
GetCatalogStr
GetLocaleStr
IsXXXX
OpenCatalogA
OpenLocale
ParseDate
StrConvert
StrnCmp
Include
GuruMeditation
|
Docs » Autodocs » locale.library » FormatString
FormatString -- format data into a character stream. (V38)
next = FormatString(locale,fmtTemplate,dataStream,putCharFunc);
D0 A0 A1 A2 A3
APTR FormatString(struct Locale *,STRPTR,APTR,struct Hook *);
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:
printf("%d eyes, %d feet and %d ears",eyes,feet,ears);
printf("%3$d ears, %1$d eyes and %2$d feet",eyes,feet,ears);
These two statements would produce the following output:
"2 eyes, 3 feet and 4 ears" for the first
"4 ears, 2 eyes and 3 feet" for the second
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().
dataStream - a stream of data that is interpreted according to
the format string. Often this is a pointer into
the task's stack.
putCharFunc - a callback hook invoked for every character generated,
including for the terminating NULL character. The hook
is called with:
A0 - address of Hook structure
A1 - character for hook to process (not a pointer!)
A2 - locale pointer
the function is called with a NULL char at the end of
the format string.
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".
exec.library/RawDoFmt()
|
