a1200   NEWS   APPS   DOCS   ABOUT
a1200
----
a1200
----
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

NAME

	FormatString -- format data into a character stream. (V38)

SYNOPSIS

	next = FormatString(locale,fmtTemplate,dataStream,putCharFunc);
D0 A0 A1 A2 A3
APTR FormatString(struct Locale *,STRPTR,APTR,struct Hook *);

FUNCTION

	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.

INPUTS

	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.

RESULT

	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.

WARNING

	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".

SEE ALSO

exec.library/RawDoFmt()

Comments

Name:
E-mail: Use this if you want a message if you get a response, will not be shown.
Comment:
Select correct short for:

Spaceballs

FC
SNT
SPB
SCX

Comments:

$VER: d0.se 1.14 Copyright © 2011-2020 Tobias Geijersson support at d0 dot se