The Mozilla
Organization
Our Mission
Who We Are
Getting Involved
Community
Editorials
What's New
Development
Roadmap
Module Owners
Blue Sky
Projects
Status
Tools
Products
Source Code
Binaries
Documentation
License Terms
Bug Reports
Search
Feedback


[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

    		Copyright © 1998 The Mozilla Organization.