|
|
[Contents] [Previous] Next [Last]
Chapter 17
Formatted printing
NSPR contains formatted printing facilities modeled after Ansi-C's stdlib
offering. The routines offered are thread aware and do place extra burdens
on the clients to deal with resource allocation and deallocation.
Formatting specification
The output functions translate internal value to characters under the control
of a format string. The format string contains two types
of objects: ordinary characters, which are copied to the output stream,
and conversion specifications, each which causes conversion and printing
of the next successive argument of the calling function. Each conversion
specification begins with a % and ends with a conversion character.
Between the % and the conversion character there may be, in order:
A minus sign, which specifies left adjustment of the converted argument.
A number that specifies the minimum field width. The converted argument
will be printed in a field at least this wide. If necessary, it will be
padded on the left (or right, if left adjustment is called for) to make
up the field width.
A period, which separates the field width from the precision.
A number, the precision, that specifies the maximum number of characters
to be printed for a string, or the number of digits after the decimal point
of a floating point value, or the minimum number of digits for an integer.
An h if the integer is to be printed as a 16 bit value, an l
if as 32 bits, or ll if 64 bits.
The conversion characters are in the following table.
| Character |
Argument type; Printed as |
| d |
PRIntn; Signed decimal
number |
| o |
PRUintn; Unsigned octal
number |
| x, X |
PRUintn; Unsigned hexadecimal
number, lower and upper case, respectively |
| u |
PRUintn; Unsigned decimal
number |
| c |
PRInt8; Single character |
| s |
char*; Print characters from the string until a '\0'
or the number of characters given by the precision |
| f, g |
PRFloat64; |
| p |
void*; pointer (implementation dependent representation) |
Output functions
PR_snprintf
PR_nsprintf formats the output into a fixed size buffer.
It guarantees that a NULL is at the end of the buffer.
PRUint32 PR_snprintf(char
*out, PRUint32 outlen, const char *fmt,
...);
Parameters
| out |
The character buffer that will hold the result of the translation. |
| outlen |
The length (in bytes) of the previously specified buffer. |
| fmt |
The string that is used as the formatting specification. |
| ... |
An arbitrary number of parameters. The number and type of the parameters
are governed by the fmt string. |
Return
The function returns the length of the written output, NOT including the
NULL, or (PRUint32)-1
if an error occurs.
PR_smprintf
PR_smprintf() is identical to PR_nsprintf()
except that rather than having the caller present the output buffer, it
is allocated by the runtime. If the return is successful, the buffer must
be freed by the caller (see PR_smprintf_free()).
char* PR_smprintf(const char *fmt, ...);
Parameter
| fmt |
The string that is used as the formatting specification. |
| ... |
An arbitrary number of parameters. The number and type of the parameters
are governed by the fmt string. |
Result
If the translation is successful, a non-NULL character pointer is returned
that must ultimately be freed by the client. The string is guaranteed to
have a NULL termination. A NULL return value indicates
an error in processing. The reason for the error can be retrieve by calling
PR_GetError().
PR_sprintf_append
PR_sprintf_append()appends the translation to an
existing string. The runtime will extend the buffer as it is needed, using
standard heap allocators. If the value of last is not NULL,
the runtime will attempt to reallocate a new buffer sufficient to
hold the existing string plus the result off the new translation. The result
must ultimately be freed by the client.
char* PR_sprintf_append(char *last, const char *fmt, ...);
Parameters
| last |
This is a string that was previously returned from PR_sprintf_append()
or a NULL (implying the first call). |
| fmt |
The string that is used as the formatting specification. |
| ... |
An arbitrary number of parameters. The number and type of the parameters
are governed by the fmt string. |
Result
If the transformation is successful, a non-NULL value will be
returned. The string it points to will contain the contents of the string
passed in as the parameter last, plus the result of the current
transformation. The result should be treated as a new string. The string
defined by last will be deleted if it is not NULL.
PR_sxprintf
Format internal data according the the standard transformation rules. Call
the stuff function the transformed string and a pointer to an object
that contains the state needed to handle that string. The stuff function
has the following signature:
typedef PRIntn (*PRStuffFunc)(void
*arg, const char *s, PRUint32 slen);
The stuff function may be called more than once for each call to
PR_sxprintf(). Each call should return the number
of bytes actually accepted by the stuff function for that particular call,
or -1 if the function fails.
| arg |
A pointer to an object referenced by the caller of PR_sxprintf()
that contains sufficient state for the stuff function to know when
to put the new transformed fragment. |
| s |
A transformed fragment that is to be added to the state of the object
referenced by arg. |
| slen |
The length of the transformed fragment, s. |
PRUint32 PR_sxprintf(PRStuffFunc
f, void *arg, const char *fmt, ...);
Parameters
| f |
The stuff function that will be called for each transformation
indicated by the formatting string, fmt. |
| arg |
A pointer to a client managed object that possess enough state to deal
with the multiple calls to the stuff function. This argument is
passed directly through and not interpreted by the runtime. |
| fmt |
The string that is used as the formatting specification. |
| ... |
An arbitrary number of parameters. The number and type of the parameters
are governed by the fmt string. |
Results
The value returned from PR_sxprintf()will be the total
number of bytes in the transformed area or 0xffffffff if the transformation
fails.
PR_fprintf
PR_fprintf() is a function with similar characteristics
as the previous formatting function, except the output is directed through
a file descriptor using PR_Write().
PRUint32 PR_fprintf(struct
PRFileDesc* fd, const char *fmt, ...);
| fd |
A valid, open file descriptor. The result of the transformation will
be directed through the file descriptor using PR_Write(). The output function
may be called multiple times. |
| fmt |
The string that is used as the formatting specification. |
| ... |
An arbitrary number of parameters. The number and type of the parameters
are governed by the fmt string. |
The result of the function call is the total number of bytes written to
the file descriptor or 0xffffffff if the transformation fails.
Note: Some transformed bytes might be written to the file and
then the function fail.
va_list versions
The following function prototypes define va_list forms of the
functions previously described.
PRUint32 PR_vsnprintf(char
*out, PRUint32 outlen, const char *fmt,
va_list ap);
char* PR_vsmprintf(const char *fmt, va_list ap);
char* PR_vsprintf_append(char *last, const char *fmt, va_list ap);
PRUint32 PR_vsxprintf(PRStuffFunc
f, void *arg, const char *fmt, va_list ap);
PRUint32 PR_vfprintf(struct PRFileDesc*
fd, const char *fmt, va_list ap);
Scanning functionss
PR_sscanf
PR_sscanf() scans the input character string, performs
data conversions, and stores the converted values in the data objects
pointed to by its arguments according to the format control string.
PR_sscanf() behaves the same way as the sscanf() function
in the Standard C Library (stdio.h), with the following exceptions:
PR_sscanf() handles the NSPR integer and floating point
types, such as PRInt16, PRInt32,
PRInt64, and PRFloat64,
PR_sscanf() has no multibyte character support.
PRInt32 PR_sscanf(const char *buf,
const char *fmt, ...);
Parameters
| buf |
A character array holding the data to be scanned. |
| fmt |
The string that is used as the formatting specification. |
| ... |
An arbitrary number of parameters. The number and type of the parameters
are governed by the fmt string. |
Result
PR_sscanf() returns the number of items scanned
and stored or a -1 if the conversion failed.
Last Updated: Tue Jul 14 16:12:23 PDT 1998
[Contents] [Previous] Next [Last]
Copyright © 1998 Netscape
Communications Corporation
|
