NSPR Reference: Chapter 20 Formatted Printing
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

NSPR Reference Previous Contents Next

## Chapter 20 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
Output Functions
Scanning Function

## Formatting Specification

The output functions translate internal values 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 of which causes conversion and printing of the next successive argument of the calling function. Each conversion specification begins with a percent character (`%`) and ends with a conversion character. Between the percent and the conversion character there can 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, a `l` if 32 bits, or `ll` if 64 bits.

The conversion characters are shown 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 `'\0'` or the number of characters given by the precision
`f, g` | `PRFloat64` | Double floating point number
`p` | `void*` | Pointer (implementation-dependent representation)

## Output Functions

Output functions are:

`PR_snprintf``
` `PR_smprintf``
` `PR_sprintf_append``
` `PR_smprintf_free``
` `PR_sxprintf``
` `PR_fprintf```

Each of these functions has a corresponding version implemented with a variable length argument list:

va_list Versions of Output Functions

#### PR_snprintf

Formats output into a fixed-size buffer.

##### Syntax

    PRUint32 PR_snprintf (
       char *out,
       PRUint32 outlen,
       const char *fmt,
       ...);

##### Parameters

The function has these parameters:

`out` | The character buffer that will hold the result of the translation.
`outlen` | The length in bytes of the 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.

##### Returns

Returns the length of the written output not including the `NULL` terminator, or
-1 if an error occurs.

##### Description

This function formats the specified parameters according to the specified format string, and stores the output in the specified buffer of the specified size. It guarantees that a `NULL` is at the end of the buffer.

#### PR_smprintf

Formats output into a buffer allocated at run time.

##### Syntax

    char* PR_smprintf (
       const char *fmt,
       ...);

##### Parameter

The function has these parameters:

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

##### Returns

If the translation is successful, returns a non-`NULL` character pointer. A `NULL` return value indicates an error in processing. Retrieve the reason for the error using `PR_GetError`.

##### Description

This function formats the specified parameters according to the specified format string, and returns the output in a character buffer. It guarantees that a `NULL` is at the end of the buffer.

This function is identical to `PR_snprintf` except that the output buffer is allocated by the runtime rather than passed into the function. If the function is successful, the returned buffer belongs to the caller. When it is no longer used, free it using `PR_smprintf_free`.

#### PR_sprintf_append

Appends a formatted string to an existing string.

##### Syntax

    char* PR_sprintf_append (
       char *last,
       const char *fmt,
       ...);

##### Parameters

The function has these parameters:

`last` | A string that was previously returned from this function, or `NULL` for 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.

##### Returns

If the transformation is successful, returns a non-`NULL` character pointer. The result should be treated as a new string. In case of error, returns `NULL`.

##### Description

This function formats the specified parameters according to the specified format string, and appends the translation to the specified existing string. The function returns a new character buffer containing the contents of the string passed in as the parameter `last`, plus the result of the current transformation.

If no string is specified, the function allocates a new character buffer. The function extends the buffer as needed, using standard heap allocators. If the value of `last` is not `NULL`, the function reallocates a new buffer sufficient to hold the existing string plus the result of the new translation, and deletes the passed string.

The buffer returned by the function belongs to the caller. When it is no longer used, free it using `PR_smprintf_free`.

#### PR_smprintf_free

Releases the string buffer returned by `PR_smprintf`.

##### Syntax

    void PR_smprintf_free (char *str);

##### Parameters

The function has this parameter:

`str` | A string buffer returned by a previous call to `PR_smprintf`.

##### Returns

Nothing

##### Description

This function frees the memory associated with the specified string buffer, which was allocated by a previous call to `PR_smprintf` or `PR_sprintf_append`. If the specified buffer was not allocated by one of these functions, the result is undefined.

#### PR_sxprintf

Formats output to a location determined by a callback function.

##### Syntax

    PRUint32 PR_sxprintf (
       PRStuffFunc f,
       void *arg,
       const char *fmt,
       ...);

##### Parameters

The function has these 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 possesses 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.

##### Returns

The total number of bytes in the transformed area, or `0xffffffff` if the transformation fails.

##### Description

This function formats the specified parameters according to the specified format string, then calls the specified "stuff function," passing the transformed string and a pointer to an object that contains the state needed to handle that string.

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.

The stuff function must be supplied by the client, and must conform to the following signature:

    typedef PRIntn (*PRStuffFunc)
       (void *arg, const char *s, PRUint32 slen);

The stuff function has these parameters:

`arg` | A pointer to an object referenced by the caller of `PR_sxprintf``` that contains sufficient state for the stuff function to know where to put the new transformed fragment.
`s` | A character buffer containing a transformed fragment that is to be added to the state of the object referenced by `arg`.
`slen` | The length of the buffer `s`.

#### PR_fprintf

Formats output into a file.

##### Syntax

    PRUint32 PR_fprintf (
       struct PRFileDesc* fd,
       const char *fmt,
       ...);

##### Parameters

The function has these parameters:

`fd` | A valid, open file descriptor.
`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.

##### Returns

Returns the total number of bytes written to the file descriptor, or `0xffffffff` if the transformation fails. It is possible for some transformed bytes to be written to the file before the function fails.

##### Description

This function formats the specified parameters according to the specified format string, then directs the result of the transformation to the specified file descriptor using `PR_Write`. The output function may be called multiple times.

### va_list Versions of Output Functions

The following function prototypes define `va_list` forms of the output functions described above. The functions are:

`PR_vsnprintf``
` `PR_vsmprintf``
` `PR_vsprintf_append``
` `PR_vsxprintf``
` `PR_vfprintf```

#### PR_vsnprintf

##### Syntax

    PRUint32 PR_vsnprintf (
       char *out,
       PRUint32 outlen,
       const char *fmt,
       va_list ap);

#### PR_vsmprintf

##### Syntax

    char* PR_vsmprintf (
       const char *fmt,
       va_list ap);

#### PR_vsprintf_append

##### Syntax

    char* PR_vsprintf_append (
       char *last,
       const char *fmt,
       va_list ap);

#### PR_vsxprintf

##### Syntax

    PRUint32 PR_vsxprintf (
       PRStuffFunc f,
       void *arg,
       const char *fmt,
       va_list ap);

#### PR_vfprintf

##### Syntax

    PRUint32 PR_vfprintf (
       struct PRFileDesc* fd,
       const char *fmt,
       va_list ap);

## Scanning Function

One scanning function is provided, `PR_sscanf`.

#### PR_sscanf

Scans a character string and performs data conversions.

##### Syntax

    PRInt32 PR_sscanf (
       const char *buf,
       const char *fmt,
       ...);

##### Parameters

The function has these 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, each of which is a pre-allocated location in which to return the results. The number and type of the parameters are governed by the `fmt` string.

##### Returns

The number of items scanned and stored, or -1 if the conversion failed.

##### Description

This function scans the specified character string, performs data conversions according to the specified format control string, and stores the converted values in the data objects pointed to by its arguments.

This function 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.

Previous Contents Next

Last Updated May 18, 2001