Compaq C++
Compaq C++ Class Library Reference Manual
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()
Returns the current buffering state flag, which is independent of
the actual allocation of a reserve area. This function's primary purpose is to
find out if a reserve area is being allocated automatically by
allocate()
.
void unbuffered(int n)
Sets the value of the current buffering state flag. If
n equals 0, then the
streambuf
object is buffered;
otherwise it is unbuffered. This function's primary purpose is to control
whether a reserve area is allocated automatically by
allocate()
.
virtual int underflow()
In
streambuf
, this function should be
treated as if its behavior is undefined; classes derived from
streambuf
must define it.
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:
- Ensures at least one character is immediately
available in the
in
array (unless the get pointer is at the end of the sequence).
- Returns the number of characters immediately
available.
- Checks that chunks in which the characters
become available are less than
bufsize
, and that they fit into the arrays.
- Sends characters put into the
out
array to the ultimate consumer.
strstream class
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.
strstreambuf class
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.
Chapter 5 Messages Package
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.
Messages class
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
|
|