SYNTAX
string sprintf (string format, mixed args...)
[int sprintf (string out, string format, mixed args...)]
DESCRIPTION
sprintf takes a format string and a number of arguments. Using the
format string the arguments are formatted into a string which is
returned. The format string consists of ordinary characters which are
copied into the returned string, and conversion specifications which
cause the next argument of sprintf to be converted into the returned string.
sprintf will simulate C's behaviour, except in non-relevant cases since
LPC has less types than C. It will also simulate all options of
C's strftime. Beside that, there are several (mostly LPC specific)
extensions in both the available flags and conversion characters.
Unlike C, sprintf returns the output string, in stead of writing the
output string in the first argument and returning the number of
bytes written. However, defining __CLOSE_TO_C__ in the config file,
will write the output string into the first argument and return the
number of bytes written.
A conversion specification starts with a '%' or a '@' and ends with a
conversion character. Between the '%' or '@' and conversion character
there may be, in order:
Flags (in any order), which modify the specification:
'-': (string) specifies left in stead of the default right alignment
of argument.
'_': (string) specifies left in stead of the default right truncation of
converted arguments. (C-sprintf does not have this option)
'|': (string) center the converted argument in its field, if the size
of the converted argument is less than the specified width.
'+': (numerical) forces printing of a sign. Default is only to print a
sign when the number is negative.
' ': (numerical) If no sign is printed, a leading space will be added.
'0': (numerical,float) use '0' in stead of ' ' as a padding char when
aligning. Default is a space.
'#': (numerical) Specifies alternative output. Octal numbers will have
a leading "0", hexadecimal numbers a leading "0x" (if
conversion character is 'x') or "0X" (conversion
character is 'X').
(float) Force printing of decimal dot, even if precision is 0.
'`': (string) reverse the string before further processing it. The
reversal will be done before calling lower_case/upper_case/
capitalize, or padding/truncating the string.
'&': (string) do a rot-13 on the string. A rot-13 rotates all letters
in a string 13 places.
'~': (string) flip the case of the letters of a string.
'<': (string) force output to be lower_case.
'=': (string) force output to be capitalized.
'>': (string) force output to be upper_case.
The order of evaluation of '<', and '>' will not be garanteed, so
be careful when using more than one. '=' will be evaluated after
'<' or '>'.
The '~', '<', '=' and '>' flags use the ISO-LATIN-1 character set.
A number specifying the minimum field width. The converted argument will
be printed in a field at least this wide, wider if necessary. If the
converted argument has fewer characters than the field width, it will be
padded to the left (or right if left adjustment has been requested) to make
up the field width. The padding character is normally a space, or a
character set by the %p conversion, but is '0' if the zero padding flag
is present.
A period which seperates the field width from the precision. The period is
required when the precision is defined.
A number, the precision, which for strings specifies the maximum number of
characters to be printed from a converted argument. If a converted argument
has to be truncated, the end of the converted argument is truncated,
unless the '_' flag is present, then the first part will be truncted.
For numerical conversions, the precision determines the minimum number of
digits to be printed. Leading '0's will be used for padding.
For f, e and E conversions the precision indicates how many digits after
the decimal period have to be printed; for g and G conversions, the
precision gives the number of significant digits.
Both the field width and the precision can be '*' meaning the field width
and/or the precision should be taken by the next available argument.
Lenght modifiers are not supported (they are meaningless in LPC).
Conversion characters: Unless stated otherwise, they convert
the next unconverted argument. The type(s) mentioned in
brackets is the type the matching argument should have.
A '[N]' denotes a numerical conversion. A '[F]' denotes float conversion.
% Conversion characters:
a: (mixed *, all int/float/string)
handle all elements of argument as with %s (in order). This is
useful to print several strings with the same flags, field width
and/or precision.
A: (string *)
as %a, but strings only.
b: (int) [N]
signed binair notation.
c: (char)
single character.
d, i: (int) [N]
signed decimal notation.
e: (int, float) [F]
E: (int, float) [F]
Decimal notation of the form [-]m.ddd(e|E)(+|-)xx[x], where
the number of d's is specified by the precision. The default
precision is FLT_PRECISION (6); a precision of 0 surpresses
the decimal point, except when the '#' flag is given.
f: (int, float) [F]
Decimal notation of the form [-]mmm.ddd, where the number of
d's is specified by the precision. The default precision is
FLT_PRECISION (6); a precision of 0 surpresses the decimal
point, except when the '#' flag is given.
g: (int, float) [F]
G: (int, float) [F]
%e or %E is used if the exponent is less than -4, or greater
than or equal the precision; otherwise %f is used. Trailing
zeros and a trailing decimal point are not printed.
h: (string)
H: (string)
Print a string by giving the character values (in hex notation).
If the h form is used, nothing is printed between bytes,
otherwise the bytes are separated by the padding char (defaults
to a space).
n: (int *)
the number of bytes written into the output string sofar
will be written into the argument. Nothing will be printed
into the output string.
o: (int) [N]
signed octal notation.
O: (object)
file_name of object.
p: (char)
change padding char to argument. This padding char will be
active until it is changed again. When no padding char is set,
a space will be used. No character will be written into the
output string.
The zero flag will still overrule the padding char.
q: (string)
In object previously set by %Q, the current argument is called
(treated as function). The result is printed as %y.
The function is called without arguments.
Q: (object)
Store argument to be queried later. See %q. No character will
be written into the output string.
r: (string)
Encrypt a string. The string is chopped in 8 byte parts and
encrypted.
R: (string)
Encrypt a string. The string is chopped in 10 byte parts,
using the first 2 as encryption seed, and the latter 8 as
message. If the last part is 1 byte long, it is discarded;
if it is 2 bytes long, the empty string will be encrypted
using the 2 bytes as seed.
s: (string, int, float)
string.
S: (string)
as %s, but string only.
x: (int) [N]
signed hexadecimal notation. Use abcdef.
X: (int) [N]
signed hexadecimal notation. Use ABCDEF.
y: (mixed)
print any type represented as a string. Integers and floats
are printed 'as they are'. Strings will be enclosed by "'s.
Objects will be in the form OBJ <file_name> (WITH the '<'
and '>'). Arrays are preceded by '({', its elements (separated
by commas) printed recursively and ended by '})'. Mappings start
with '([', the index/values pairs (with ' : ' between the index
and the value and commas separating the pairs) printed
recursively and end with '])'.
%: (none)
print a '%' symbol. No argument is converted.
@ Conversation characters: They all are time-related. The argument passed
should be the number of seconds after Jan 1, 1970, 0:00:00 GMT.
Passing time () gives the current time.
a: (int) abbreviated weekday.
A: (int) full weekday name.
b: (int) abbreviated month name.
B: (int) full month name.
c: (int) local date and time representation.
d: (int) [N] day of the month. (00 - 31)
H: (int) [N] hour (24 hour clock). (00 - 23)
I: (int) [N] hour (12 hour clock). (01 - 12)
j: (int) [N] day of the year. (001 - 366)
m: (int) [N] month. (01 - 12)
M: (int) [N] minute. (00 - 59)
p: (int) local equivalent of AM or PM.
S: (int) [N] second. (00 - 61)
U: (int) [N] week number of year (Sunday as first day of the week).
(00 - 53)
w: (int) [N] weekday (0-6, Sunday is 0).
W: (int) [N] week number of year (Monday as first day of the week).
(00 - 53)
x: (int) local date representation.
X: (int) local time representation.
y: (int) [N] year without century. (00 - 99)
Y: (int) [N] year with century.
Z: (int) time zone, if any.
@: (none) print a '@' symbol. No argument is converted.
@ conversion characters are not recognized when __TIME_CONVERSION__
is not defined in the config file.
Flags, field width and precission on the %n, %p, %Q, %%, and @@ conversion
characters are recognized but ignored.
The conversation arguments follow the format string, and are converted
in order.
ERRORS
Passing 0 as format string results in an error.
Conversion specifications not terminated by a conversion character result
in an error.
The programmer should take care of the correct number of arguments of
sprintf (). The number of args should match the number of conversion
specifications (except for the % and @ conversion characters.) Passing
too few arguments will result in an error. If too many arguments are
passed, the non-used arguments will be ignored.
Use of wrong typed arguments (see above list for the proper type) results
in undefined behaviour.
Use of conversion characters not mentioned in above list results in
undefined behaviour.
Using the same flag twice or a flag for numerical conversions on
non-numerical conversions will result in undefined behaviour.
CONFIGURATION
The file config.h gives a few configuration possibilities.
__CLOSE_TO_C__ If defined, sprintf puts the output string in the first
argument, and returns the number of bytes written.
Otherwise, the output string is returned. Undefined
by default;
__UPPER_CASE__ Define if upper_case () is an available efun ().
__TIME_CONVERSION__ Define if @ conversation sequences should be handled.
Defined by default.
BASE Define to the default base in which numbers are
represented. 10 is the default value.
The file time.h contains a few time related configurations.
DST_CONVERSION_YEAR Define this to the first year the current DST scheme
was in affect. Dates before this year are assumed to
not have DST. Defaults to 1970.
TZ Name of the timezone. Default "MET".
DSTZ Name of the timezone with DST. Default "METDST".
AM Name how 'am' should be represented. Default is "am".
PM Name how 'pm' should be represented. Default is "pm".
FILES
In the same directory as the file 'sprintf.c', the following files should
be found:
config.h A few configurations.
macros.h Macros used by the program.
time.h Time related macros and configurations.
sym_names.h Defines characters.
extra.c Functions modifying strings.
time.c Time related functions.
DRIVER
This package was designed for the DGD driver, and the most recent
version needs DGD 1.0.7.7 or higher to work.
HISTORY
Version 1.0 was developed early April 1994.
Version 1.1 (with floats) was released August 9, 1994.
AUTHOR
The author is Haijo Schipper (Abigail). The author can be reached on the
following addresses:
abigail@xs4all.nl (soon, if it bounces, try abigail@hacktic.nl)
abigail@The Pattern (epsilon.me.chalmers.se 6047)
abigail@TMI-2 (tmi.ccs.neu.edu 5555)
BUGS
The code is not well commented.