In classes derived from streambuf , this function is called to let derived classes examine the state of the put, get, and reserve areas, and to synchronize these areas with any external representation. Normally sync() should consume any characters stored into the put area and, if possible, give back to the source any characters in the get area that have not been fetched. When sync() returns, no unconsumed characters should remain and the get area should be empty. If some kind of failure occurs, sync() should return EOF .

int unbuffered()

void unbuffered(int n)

virtual int underflow()

In classes derived from streambuf , it is called to supply characters for fetching; that is, to create a condition in which the get area is not empty. If this function is called when characters are in the get area, it should return the first character. If the get area is empty, it should create a nonempty get area and return the next character (which it should also leave in the get area). If no more characters are available, underflow() should return EOF and leave an empty get area.

Example

static const int bufsize = 1024; 
char buf[bufsize] ;   
int p, g ; 
do {                   
        in->sgetc() ; (1)
        g = in->in_avail() ;  (2)
        if (g > bufsize) g = bufsize ;  (3)
        g = in->sgetn(buf,g) ; 
        p = out->sput(buf,g) ; 
        out->sync() ;  (4)
        if (p!=g) error("output error"); 
        } while (g > 0) 
      

Provides a way to pass characters into the in and out arrays as soon as the characters become available (as when someone types them from a terminal) as follows:

1. Ensures at least one character is immediately available in the in array (unless the get pointer is at the end of the sequence).
2. Returns the number of characters immediately available.
3. Checks that chunks in which the characters become available are less than bufsize , and that they fit into the arrays.
4. Sends characters put into the out array to the ultimate consumer.

Specializes the iostream class for storing in and fetching from arrays of bytes.

Header File

#include <strstream.hxx>

Alternative Header

#include <strstream.h>

Declaration

class strstream: public iostream { public: strstream(); strstream(char *, int, int); strstreambuf *rdbuf(); char *str(); };

Description

This class specializes the iostream class for storing in and fetching from arrays of bytes. It handles all predefined data types, and provides an extensive set of options for performing input and output on these data types.

Constructors and Destructors

strstream()

Constructs an strstream object and dynamically allocates space to hold stored characters.

strstream(char *cp, int n, int mode)

Constructs an strstream object. It stores characters into the array starting at cp and continuing for n bytes. If ios::ate or ios::app is set in mode, cp is presumed to be a null-terminated string and storing begins at the null character; otherwise, storing begins at cp. Seeks are permitted anywhere in the array.

Member Functions

strstreambuf *rdbuf()

Returns a pointer to the strstreambuf object associated with a strstream object.

char *str()

Returns a pointer to an explicit array, to be used as the associated strstreambuf object, if the strstream object was constructed with such an array; otherwise, it returns a pointer to a dynamically allocated area. Until str() is called, deleting the dynamically allocated area is the responsibility of the strstream object. After str() returns, dynamic allocation becomes the responsibility of the user program. After str() has been called, the effect of storing more characters into the strstream object is undefined.

Specializes the streambuf class for input and output performed on arrays of bytes in memory.

Header File

#include <strstream.hxx>

Alternative Header

#include <strstream.h>

Declaration

class strstreambuf: public streambuf { public: strstreambuf(); strstreambuf(char *, int, char *); strstreambuf(int); strstreambuf(unsigned char *, int, unsigned char *); strstreambuf(void *(*a)(long), void (*f)(void *)); void freeze(int n = 1); virtual int overflow(int); virtual streambuf *setbuf(char *, int); char *str(); virtual int underflow(); };

Description

Objects of this class let you use an array of bytes (a string of characters) in memory as a streambuf object for stream input/output operations on various kinds of data. Mapping between abstract get and put pointers and char * pointers is direct in the sense that a char * is interpreted as logically pointing immediately ahead of the char it actually points to. Moving the pointers corresponds to incrementing and decrementing the char * values.

To accommodate the need for strings of arbitrary length, this class supports a dynamic mode. When a strstreambuf object is in dynamic mode, space for the character is allocated as needed. When the sequence is extended too far, it is copied to a new array.

If your program expects a buffer to be allocated when none was allocated, then the iostream package allocates a default buffer, with a length specified by BUFSIZ as defined in stdio.h . The package then issues the following warning:

Warning; a null pointer to streambuf was passed to ios::init()

Constructors and Destructors

strstreambuf()

Constructs an empty strstreambuf object in dynamic mode. This means that space is automatically allocated to accommodate characters put into the strstreambuf object (using the new and delete operators). Because this may require copying the original characters, programs that have many characters to insert should use setbuf() to inform the strstreambuf object about the needed allocation of space, or to use one of the constructors that follow.

strstreambuf(int n)

Constructs an empty strstreambuf object in dynamic mode. The initial allocation of space is at least n bytes.

strstreambuf(char *ptr, int n, char *pstart)

strstreambuf(unsigned char *ptr, int n, unsigned char *pstart)

Constructs a strstreambuf object to use the bytes starting at ptr. The strstreambuf object is in static mode; it does not grow dynamically. If n is positive, then the n bytes starting at ptr are used as the strstreambuf object. If n is 0, ptr is presumed to point to the beginning of a null-terminated string and the bytes of that string (not including the terminating null character) constitute the strstreambuf object. If n is negative, then the strstreambuf object is presumed to continue indefinitely.

The get pointer is initialized to ptr. The put pointer is initialized to pstart. If pstart is not null, then the initial sequence for fetching (the get area) consists of the bytes between ptr and pstart. If pstart is null, then storing operations are treated as errors and the initial get area consists of the entire array.

strstreambuf(void *(*a)(long n), void (*f)(void *ptr))

Constructs an empty strstreambuf object in dynamic mode. a is used as the allocator function in dynamic mode. The argument passed to a is a long denoting the number of bytes to be allocated. If the a argument is null, the new operator is used. f is used to free (or delete) get, put, or reserve areas returned by a. The argument to f becomes a pointer to the array allocated by a. If f is null, the delete operator is used.

Member Functions

void freeze(int n)

Inhibits (freezes) automatic deletion of the current array if n is nonzero, or permits (unfreezes) automatic deletion if n is 0. Deletion normally occurs when more space is needed, or when the strstreambuf object is being destroyed. Only space obtained through dynamic allocation is free. Storing characters into a strstreambuf that was dynamically allocated and is now frozen causes an error (the effect is undefined). If you want to resume storing characters in such a strstreambuf object you can thaw (unfreeze) it.

virtual int overflow(int c)

In classes derived from streambuf , it is called to consume characters. If c is not EOF , overflow(c) also must either save c or consume it. Although it can be called at other times, this function is usually called when the put area is full and an attempt is being made to store a new character. The normal action is to consume the characters between pbase() and pptr() , call setp() to establish a new put area, and (if c != EOF ) store c using sputc() . overflow(c) should return EOF to indicate an error; otherwise, it should return something else.

virtual streambuf *setbuf(char *ptr, int n)

Causes the strstreambuf object to remember n (if ptr is 0); this ensures that at least n bytes are allocated during the next dynamic mode allocation.

char *str()

Returns a pointer to the first character in the current array and freezes the strstreambuf object. If the strstreambuf object was constructed with an explicit array, the function returns a pointer to that array. If the strstreambuf object is in dynamic allocation mode but nothing has been restored yet, the returned pointer is null.

virtual int underflow()

In classes derived from streambuf , it is called to supply characters for fetching; that is, to create a condition in which the get area is not empty. If this function is called when characters are in the get area, it should return the first character. If the get area is empty, it should create a nonempty get area and return the next character (which it should also leave in the get area). If no more characters are available, underflow() should return EOF and leave an empty get area.

The Messages package provides a way to retrieve messages stored in a catalog or file that is separate from your program. It consists of a single class, Messages , that retrieves the text of a message.

A message set number is a number specified in the message catalog source file with a $set n line, ranging from 1 to NL_SETMAX, as defined in nl_types.h . To process the message catalog source file, use the gencat command. For more information see the gencat (1int) reference page.

Retrieves message text for a message number.

Header File

#include <messages.hxx>

Alternative Header

None.

Declaration

class Messages { public: Messages(const char *filename_arg, int set_arg = 0, const char *default_file_location_arg = (const char *)(NULL)); ~Messages(); const char *text(int msg_arg, const char *fallback_text_arg, int set_arg = 0); };

Exception Handling

If the message file cannot be opened or closed, the system prints one of the following error messages on cerr (as appropriate):

Cannot open message catalog " catalog name " -- check NLSPATH
Cannot close message catalog " catalog name "

Constructors and Destructors

Messages(const char *filename_arg, int set_arg, const char *default_file_location_arg)

Constructs a Messages object. The filename_arg argument specifies the file name of the message catalog. The set_arg argument specifies the message number to set; a value of 0 specifies that the default setting (NL_SETD as defined in nl_types.h ) be used. The default_file_location_arg argument specifies the default location of filename_arg.

~Messages()

Deletes a Messages object.

Member Function

const char *text(int msg_arg, const char *fallback_text_arg, int set_arg)

Returns the text of the message specified by the msg_arg argument. The fallback_text_arg argument indicates the text to return if the message cannot be found. The set_arg argument specifies the message set number; a value of 0 causes the system to use the set number provided to the constructor.

Example

The following is a sample message source file:

$ messages_example.msf   Messages example -- Digital UNIX message catalog 
 
$ set 1 EXAMPLE_SET 
 
1 This is an example error message 
 
$ End of messages_example.msf 
      

Entering the following gencat command compiles this file:

$ gencat messages_example.cat message_example.msf 
      

The following program retrieves the sample error message:

#include <iostream.hxx> 
#include <messages.hxx> 
 
const char *message_file_name = "messages_example"; 
const char *message_file_location = "%N.cat"; 
int message_set_example = 1; 
 
Messages m_example (message_file_name, message_set_example, 
    message_file_location); 
 
int main() 
{ 
    cout << 
        "text of example message 1: " << 
        m_example.text(1, "fallback message 1") << 
        "\n"; 
 
    cout << 
        "text of example message 2: " << 
        m_example.text(2, "fallback message 2") << 
        "\n"; 
 
    return EXIT_SUCCESS; 
} 
 
 
 
      

Executing the program without compiling the message source file displays the following fallback messages:

text of example message 1: fallback message 1 
text of example message 2: fallback message 2 
      

After compiling the message source file and setting the NLSPATH environment variable, executing the program retrieves the text of the error message and displays the second fallback message:

text of example message 1: This is an example error message 
text of example message 2: fallback message 2 
      

  

privacy and legal statement