1 - assert
<assert.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
2 - cassert
<cassert>
Include the standard header <cassert>
to effectively include the Standard C library header
<assert.h>.
#include <assert.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
3 - cctype
<cctype>
Include the standard header <cctype>
to effectively include the standard header
<ctype.h>.
#include <ctype.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
4 - cerrno
<cerrno>
Include the standard header <cerrno>
to effectively include the Standard C library header
<errno.h>.
#include <errno.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
5 - cfloat
<cfloat>
Include the standard header <cfloat>
to effectively include the Standard C library header
<float.h>.
#include <float.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
6 - charset
Characters
Character Sets
· Character Sets and Locales
· Escape Sequences
· Numeric Escape Sequences
· Trigraphs
· Multibyte Characters
· Wide-Character Encoding
Characters play a central role in Standard C. You represent
a C program as one or more
source files.
The translator reads a source file as a
text stream
consisting of characters that you can read when you
display the stream on a terminal screen or produce hard copy with a
printer. You often manipulate text when a C program executes. The
program might produce a text stream that people can read, or it might
read a text stream entered by someone typing at a keyboard
or from a file modified using a text editor.
This document describes the characters that you
use to write C source files and that you manipulate as streams
when executing C programs.
When you write a program, you express C source files as
text lines
containing characters from the
source character set.
When a program executes in the
target environment,
it uses characters from the
target character set.
These character sets are related, but need not have
the same encoding or all the same members.
Every character set contains a distinct code value for each
character in the
basic C character set.
A character set can also contain additional characters
with other code values. For example:
- The
character constant
'x' becomes the value of
the code for the character corresponding to x in the target
character set. - The
string literal
"xyz" becomes a sequence of
character constants stored in successive bytes of memory, followed
by a byte containing the value zero:
{'x', 'y', 'z', '\0'}
A string literal is one way to specify a
null-terminated string,
an array of zero or more bytes followed by a byte containing the
value zero.
Visible graphic characters
in the basic C character set:
Form Members
letter A B C D E F G H I J K L M
N O P Q R S T U V W X Y Z
a b c d e f g h i j k l m
n o p q r s t u v w x y z
digit 0 1 2 3 4 5 6 7 8 9
underscore _
punctuation ! " # % & ' ( ) * + , - . / :
; < = > ? [ \ ] ^ { | } ~Additional
graphic characters in the basic C character set:
Character Meaning
space leave blank space
BEL signal an alert (BELl)
BS go back one position (BackSpace)
FF go to top of page (Form Feed)
NL go to start of next line (NewLine)
CR go to start of this line (Carriage Return)
HT go to next Horizontal Tab stop
VT go to next Vertical Tab stop
The code value zero is reserved for the
null character
which is always in the target character set. Code values for the basic
C character set are positive when stored in an object of type char.
Code values for the digits are contiguous, with increasing value.
For example, '0' + 5 equals '5'.
Code values for any
two letters are not necessarily contiguous.
An implementation can support multiple
locales, each
with a different character set. A locale summarizes conventions particular
to a given culture, such as how to format dates or how to sort names.
To change locales and, therefore, target character sets while the
program is running, use the function
setlocale.
The translator encodes character constants and
string literals for the
"C" locale,
which is the locale in effect at program startup.
Within character constants and string literals, you can write
a variety of escape sequences. Each escape sequence determines
the code value for a single character. You use escape sequences
to represent character codes:
- you cannot otherwise write (such as
\n) - that can be difficult to read properly (such as
\t) - that might change value in different target character sets (such
as
\a) - that must not change in value among different target environments
(such as
\0)
An escape sequence takes the form shown in the diagram.
Mnemonic escape sequences
help you remember the characters they represent:
Character Escape Sequence
" \"
' \'
? \?
\ \\
BEL \a
BS \b
FF \f
NL \n
CR \r
HT \t
VT \v
You can also write numeric escape sequences using either
octal or hexadecimal digits. An
octal escape sequence
takes one of the forms:
\d or \dd or \ddd
The escape sequence yields a code value that is the numeric
value of the 1-, 2-, or 3-digit octal number following the backslash
(\). Each d can be
any digit in the range 0-7.
A
hexadecimal escape sequence takes one of the forms:
\xh or \xhh or ...
The escape sequence yields a code value that is the numeric
value of the arbitrary-length hexadecimal number following the backslash
(\). Each h can be any
decimal digit 0-9, or
any of the letters a-f or A-F.
The letters represent
the digit values 10-15, where either a or A has
the value 10.
A numeric escape sequence terminates with the first character
that does not fit the digit pattern. Here are some examples:
- You can write the
null character
as
'\0'. - You can write a newline character (
NL)
within a string literal by writing:
"hi\n" which becomes the array
{'h', 'i', '\n', 0} - You can write a string literal that begins with a specific numeric
value:
"\3abc" which becomes the array
{3, 'a', 'b', 'c', 0} - You can write a string literal that contains the hexadecimal
escape sequence
\xF followed by
the digit 3 by writing
two string literals:
"\xF" "3" which becomes the array
{0xF, '3', 0}
A trigraph is a sequence of three characters that begins
with two question marks (??). You use trigraphs to write C
source files with a character set that does not contain convenient
graphic representations for some punctuation characters. (The resultant
C source file is not necessarily more readable, but it is unambiguous.)
The list of all
defined trigraphs is:
Character Trigraph
[ ??(
\ ??/
] ??)
^ ??'
{ ??<
| ??!
} ??>
~ ??-
# ??=These are the only trigraphs. The translator does not alter any other
sequence that begins with two question marks.
For example, the expression statements:
printf("Case ??=3 is done??/n");
printf("You said what????/n");are equivalent to:
printf("Case #3 is done\n");
printf("You said what??\n");The translator replaces each trigraph with its equivalent single
character representation in an early
phase of translation.
You can always treat a trigraph as a single source character.
A source character set or target character set can also contain
multibyte characters (sequences of one or more bytes). Each
sequence represents a single character in the
extended character set.
You use multibyte characters to represent large sets of characters,
such as Kanji. A multibyte character can be a one-byte sequence that
is a character from the
basic C character set,
an additional one-byte sequence that is implementation defined,
or an additional sequence of two or more bytes that is
implementation defined.
Any multibyte encoding that contains sequences of two or more
bytes depends, for its interpretation between bytes, on a
conversion state determined
by bytes earlier in the sequence of characters. In the
initial conversion state
if the byte immediately following matches one of the characters
in the basic C character set, the byte must represent that character.
For example, the
EUC encoding is a superset of ASCII.
A byte value in the interval [0xA1, 0xFE] is the first of a two-byte
sequence (whose second byte value is in the interval [0x80, 0xFF]).
All other byte values are one-byte sequences. Since all members of the
basic C character set
have byte values in the range [0x00, 0x7F] in ASCII,
EUC meets the requirements
for a multibyte encoding in Standard C. Such a sequence is not
in the initial conversion state immediately after a byte value in
the interval [0xA1, 0xFe]. It is ill-formed if a second byte
value is not in the interval [0x80, 0xFF].
Multibyte characters can also have a
state-dependent encoding.
How you interpret a byte in such an encoding depends on a
conversion state that involves both a
parse state, as before, and a
shift state, determined
by bytes earlier in the sequence of characters. The
initial shift state,
at the beginning of a new multibyte character, is also the
initial conversion state. A subsequent
shift sequence can determine an
alternate shift state,
after which all byte sequences (including one-byte sequences) can have
a different interpretation. A byte containing the value zero,
however, always represents the
null character.
It cannot occur as any of the bytes of another multibyte character.
For example, the
JIS encoding is another superset of ASCII.
In the initial shift state, each byte represents a single character,
except for two three-byte shift sequences:
- The three-byte sequence
"\x1B$B" shifts to two-byte mode.
Subsequently, two successive bytes (both with values
in the range [0x21, 0x7E]) constitute a single multibyte character. - The three-byte sequence
"\x1B(B" shifts back
to the initial shift state.
JIS also meets the requirements for a multibyte encoding in Standard C.
Such a sequence is not in the initial conversion state
when partway through a three-byte shift sequence
or when in two-byte mode.
You can write multibyte characters in C source text as part
of a comment, a character constant, a string literal, or a filename in an
include directive.
How such characters print is implementation
defined. Each sequence of multibyte characters that you write must
begin and end in the initial shift state.
The program can also include multibyte characters in
null-terminated
C strings
used by several library functions, including the
format strings for
printf and
scanf.
Each such character string must begin and end
in the initial shift state.
Each character in the extended character set also has an integer
representation, called a wide-character encoding.
Each extended character has a unique wide-character value.
The value zero always corresponds to the
null wide character.
The type definition
wchar_t
specifies the integer type that represents wide characters.
You write a
wide-character constant
as L'mbc', where mbc represents
a single multibyte character.
You write a
wide-character string literal as L"mbs",
where mbs represents
a sequence of zero or more multibyte characters.
The wide-character string literal
L"xyz" becomes a sequence of
wide-character constants stored in successive bytes of memory, followed
by a null wide character:
{L'x', L'y', L'z', L'\0'}
The following library functions
help you convert between the multibyte
and wide-character representations of extended characters:
mblen,
mbstowcs,
mbtowc,
wcstombs,
wctomb.
The macro
MB_LEN_MAX
specifies the length of the longest possible multibyte sequence required
to represent a single character defined by the implementation across
supported locales. And the macro
MB_CUR_MAX
specifies the length of the longest possible multibyte sequence required
to represent a single character defined for the current
locale.
For example, the
string literal
"hello" becomes an array of six char:
{'h', 'e', 'l', 'l', 'o', 0}while the wide-character string literal
L"hello" becomes
an array of six integers of type
wchar_t:
{L'h', L'e', L'l', L'l', L'o', 0}
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
7 - climits
<climits>
Include the standard header <climits>
to effectively include the Standard C library header
<limits.h>.
#include <limits.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
8 - clocale
<clocale>
Include the standard header <clocale>
to effectively include the standard header
<locale.h>.
#include <locale.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
9 - cmath
<cmath>
Include the standard header <cmath>
to effectively include the standard header
<math.h>.
#include <math.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
10 - complex
<complex>
abs
· arg
· complex
· conj
· cos
· cosh
· double_complex
· exp
· float_complex
· imag
· log
· log10
· norm
· operator!=
· operator*
· operator+
· operator-
· operator/
· operator<<
· operator==
· operator>>
· polar
· pow
· real
· sin
· sinh
· sqrt
· tan
· tanh
· __STD_COMPLEX
Include the standard header <complex>
to define classes double_complex and float_complex and a host of
supporting functions.
Unless otherwise specified,
functions that can return multiple values return an imaginary
part in the half-open interval (-pi, pi].
// DECLARATIONS
#define __STD_COMPLEX
// CLASSES
class double_complex;
class float_complex;
// double_complex FUNCTIONS
double_complex operator+(const double_complex& left,
const double_complex& right);
double_complex operator+(const double_complex& left,
const double& right);
double_complex operator+(const double& left,
const double_complex& right);
double_complex operator-(const double_complex& left,
const double_complex& right);
double_complex operator-(const double_complex& left,
const double& right);
double_complex operator-(const double& left,
const double_complex& right);
double_complex operator*(const double_complex& left,
const double_complex& right);
double_complex operator*(const double_complex& left,
const double& right);
double_complex operator*(const double& left,
const double_complex& right);
double_complex operator/(const double_complex& left,
const double_complex& right);
double_complex operator/(const double_complex& left,
const double& right);
double_complex operator/(const double& left,
const double_complex& right);
double_complex operator+(const double_complex& left);
double_complex operator-(const double_complex& left);
bool operator==(const double_complex& left,
const double_complex& right);
bool operator==(const double_complex& left,
const double& right);
bool operator==(const double& left,
const double_complex& right);
bool operator!=(const double_complex& left,
const double_complex& right);
bool operator!=(const double_complex& left,
const double& right);
bool operator!=(const double& left,
const double_complex& right);
istream& operator>>(istream& istr, double_complex& right);
ostream& operator<<(ostream& ostr, const double_complex& right);
double real(const double_complex& left);
double imag(const double_complex& left);
double abs(const double_complex& left);
double arg(const double_complex& left);
double norm(const double_complex& left);
double_complex conj(const double_complex& left);
double_complex polar(const double& rho,
const double& theta = 0);
double_complex cos(const double_complex& left);
double_complex cosh(const double_complex& left);
double_complex exp(const double_complex& left);
double_complex log(const double_complex& left);
double_complex log10(const double_complex& left);
double_complex pow(const double_complex& left, int right);
double_complex pow(const double_complex& left,
const double& right);
double_complex pow(const double_complex& left,
const double_complex& right);
double_complex pow(const double& left,
const double_complex& right);
double_complex sin(const double_complex& left);
double_complex sinh(const double_complex& left);
double_complex sqrt(const double_complex& left);
// float_complex FUNCTIONS
bool operator==(const float& left,
const float_complex& right);
bool operator!=(const float_complex& left,
const float_complex& right);
bool operator!=(const float_complex& left,
const float& right);
bool operator!=(const float& left,
const float_complex& right);
istream& operator>>(istream& istr, float_complex& right);
ostream& operator<<(ostream& ostr, const float_complex& right);
float real(const float_complex& left);
float imag(const float_complex& left);
float abs(const float_complex& left);
float arg(const float_complex& left);
float norm(const float_complex& left);
float_complex conj(const float_complex& left);
float_complex polar(const float& rho,
const float& theta = 0);
float_complex cos(const float_complex& left);
float_complex cosh(const float_complex& left);
float_complex exp(const float_complex& left);
float_complex log(const float_complex& left);
float_complex log10(const float_complex& left);
float_complex pow(const float_complex& left, int right);
float_complex pow(const float_complex& left,
const float& right);
float_complex pow(const float_complex& left,
const float_complex& right);
float_complex pow(const float& left,
const float_complex& right);
float_complex sin(const float_complex& left);
float_complex sinh(const float_complex& left);
float_complex sqrt(const float_complex& left);
// END OF DECLARATIONSdouble abs(const double_complex& left);
float abs(const float_complex& left);
The function returns the magnitude of left.
double arg(const double_complex& left);
float arg(const float_complex& left);
The function returns the phase angle of left.
template<class Ty>
class complex {
public:
typedef Ty value_type;
Ty real() const;
Ty imag() const;
complex(const Ty& realval = 0, const Ty& imagval = 0);
complex(const complex& right);
complex& operator=(const complex& right);
complex& operator+=(const complex& right);
complex& operator-=(const complex& right);
complex& operator*=(const complex& right);
complex& operator/=(const complex& right);
complex& operator=(const Ty& right);
complex& operator=(const Ty& right);
complex& operator+=(const Ty& right);
complex& operator-=(const Ty& right);
complex& operator*=(const Ty& right);
complex& operator/=(const Ty& right);
};The template class doesn't really exist. It is a convenient fiction
for describing the behavior common to the two types:
The template class describes an object that stores two objects
of type Ty, one that represents the real part
of a complex number and one that represents the imaginary part.
complex(const Ty& realval = 0, const Ty& imagval = 0);
complex(const complex& right);
The first constructor initializes the stored real part to
realval and the stored imaginary part to imagval.
The second constructor initializes the stored real part to
right.real() and the stored imaginary part to
right.imag().
Ty imag() const;
The member function returns the stored imaginary part.
complex& operator*=(const complex& right);
complex& operator*=(const Ty& right);
The first member function replaces the stored real and imaginary parts
with those corresponding to the complex product of *this
and right. It then returns *this.
The second member function multiplies both the stored real part
and the stored imaginary part with right.
It then returns *this.
complex& operator+=(const complex& right);
complex& operator+=(const Ty& right);
The first member function replaces the stored real and imaginary parts
with those corresponding to the complex sum of *this
and right. It then returns *this.
The second member function adds right to the stored real part.
It then returns *this.
complex& operator-=(const complex& right);
complex& operator-=(const Ty& right);
The first member function replaces the stored real and imaginary parts
with those corresponding to the complex difference of *this
and right. It then returns *this.
The second member function subtracts right from
the stored real part. It then returns *this.
complex& operator/=(const complex& right);
complex& operator/=(const Ty& right);
The first member function replaces the stored real and imaginary parts
with those corresponding to the complex quotient of *this
and right. It then returns *this.
The second member function multiplies both the stored real part
and the stored imaginary part with right.
It then returns *this.
complex& operator=(const complex& right);
complex& operator=(const Ty& right);
The first member function replaces the stored real part with
right.real() and the stored imaginary part
with right.imag(). It then returns *this.
The second member function replaces the stored real part with
right and the stored imaginary part
with zero. It then returns *this.
Ty real() const;
The member function returns the stored real part.
typedef Ty value_type;
The type is a synonym for the template parameter Ty.
double_complex conj(const double_complex& left);
float_complex conj(const float_complex& left);
The function returns the conjugate of left.
double_complex cos(const double_complex& left);
float_complex cos(const float_complex& left);
The function returns the cosine of left.
double_complex cosh(const double_complex& left);
float_complex cosh(const float_complex& left);
The function returns the hyperbolic cosine of left.
class double_complex : public complex<double> {
public:
double_complex(double realval = 0, double imagval = 0);
double_complex(const float_complex& right);
double_complex& operator=(const double right);
};The class describes an object that stores two objects
of type double, one that represents the real part
of a complex number and one that represents the imaginary part.
The class differs from its fictitious base class
complex<double>
only in the constructors it defines.
The first constructor initializes the stored real part to
realval and the stored imaginary part to imagval.
The second constructor initializes the stored real part to
right.real() and the stored imaginary part to
right.imag().
The assignment operator stores right in the stored real part
and zero in the stored imaginary part.
double_complex exp(const double_complex& left);
float_complex exp(const float_complex& left);
The function returns the exponential of left.
class float_complex : public complex<float> {
public:
float_complex(float realval = 0, float imagval = 0);
explicit float_complex(const double_complex& right);
float_complex& operator=(const float right);
};The class describes an object that stores two objects
of type float, one that represents the real part
of a complex number and one that represents the imaginary part.
The class differs from its fictitious base class
complex<float>
only in the constructors it defines.
The first constructor initializes the stored real part to
realval and the stored imaginary part to imagval.
The second constructor initializes the stored real part to
right.real() and the stored imaginary part to
right.imag().
The assignment operator stores right in the stored real part
and zero in the stored imaginary part.
double imag(const double_complex& left);
float imag(const float_complex& left);
The function returns the imaginary part of left.
double_complex log(const double_complex& left);
float_complex log(const float_complex& left);
The function returns the logarithm of left.
The branch cuts are along the negative real axis.
double_complex log10(const double_complex& left);
float_complex log10(const float_complex& left);
The function returns the base 10
logarithm of left.
The branch cuts are along the negative real axis.
double norm(const double_complex& left);
float norm(const float_complex& left);
The function returns the squared magnitude of left.
bool operator!=(const double_complex& left,
const double_complex& right);
bool operator!=(const double_complex& left,
const double& right);
bool operator!=(const double& left,
const double_complex& right);
bool operator!=(const float_complex& left,
const float_complex& right);
bool operator!=(const float_complex& left,
const float& right);
bool operator!=(const float& left,
const float_complex& right);The operators each return true only if
real(left) != real(right) ||
imag(left) != imag(right).
double_complex operator*(const double_complex& left,
const double_complex;& right);
double_complex operator*(const double_complex& left,
const double& right);
double_complex operator*(const double& left,
const double_complex& right);
float_complex operator*(const float_complex& left,
const float_complex;& right);
float_complex operator*(const float_complex& left,
const float& right);
float_complex operator*(const float& left,
const float_complex& right);The operators each convert both operands to the return type,
then return the complex product
of the converted left and right.
double_complex operator+(const double_complex& left,
const double_complex;& right);
double_complex operator+(const double_complex& left,
const double& right);
double_complex operator+(const double& left,
const double_complex& right);
double_complex operator+(const double_complex& left);
float_complex operator+(const float_complex& left,
const float_complex;& right);
float_complex operator+(const float_complex& left,
const float& right);
float_complex operator+(const float& left,
const float_complex& right);
float_complex operator+(const float_complex& left);The binary operators each convert both operands to the return type,
then return the complex sum
of the converted left and right.
The unary operator returns left.
double_complex operator-(const double_complex& left,
const double_complex;& right);
double_complex operator-(const double_complex& left,
const double& right);
double_complex operator-(const double& left,
const double_complex& right);
double_complex operator-(const double_complex& left);
float_complex operator-(const float_complex& left,
const float_complex;& right);
float_complex operator-(const float_complex& left,
const float& right);
float_complex operator-(const float& left,
const float_complex& right);
float_complex operator-(const float_complex& left);The binary operators each convert both operands to the return type,
then return the complex difference
of the converted left and right.
The unary operator returns a value whose real part is
-real(left) and whose imaginary part is
-imag(left).
double_complex operator/(const double_complex& left,
const double_complex;& right);
double_complex operator/(const double_complex& left,
const double& right);
double_complex operator/(const double& left,
const double_complex& right);
float_complex operator/(const float_complex& left,
const float_complex;& right);
float_complex operator/(const float_complex& left,
const float& right);
float_complex operator/(const float& left,
const float_complex& right);The operators each convert both operands to the return type,
then return the complex quotient
of the converted left and right.
ostream& operator<<(ostream& ostr,
const double_complex& right);
ostream& operator<<(ostream& ostr,
const float_complex& right);The template function inserts the complex value right
in the output stream ostr, effectively by executing:
ostringstream osstr;
osstr.flags(ostr.flags());
osstr.precision(ostr.precision());
osstr << '(' << real(right) << ','
<< imag(right) << ')';
ostr << osstr.str().c_str();Thus, if
ostr.width() is
greater than zero, any padding occurs either before or after the
parenthesized pair of values, which itself contains no padding.
The function returns ostr.
bool operator==(const double_complex& left,
const double_complex& right);
bool operator==(const double_complex& left,
const double& right);
bool operator==(const double& left,
const double_complex& right);
bool operator==(const float_complex& left,
const float_complex& right);
bool operator==(const float_complex& left,
const float& right);
bool operator==(const float& left,
const float_complex& right);The operators each return true only if
real(left) == real(right) &&
imag(left) == imag(right).
istream& operator>>(istream& istr,
double_complex& right);
istream& operator>>(istream& istr,
float_complex& right);The template function attempts to extract a complex value
from the input stream istr, effectively by executing:
istr >> ch && ch == '('
&& istr >> re >> ch && ch == ','
&& istr >> im >> ch && ch == ')'Here, ch is an object of type char,
and re and im are objects of the same type
as right.real().
If the result of this expression is true, the function stores
re in the real part and im in the
imaginary part of right. In any event, the function
returns istr.
double_complex polar(const double& rho,
const double& theta = 0);
float_complex polar(const float& rho,
const float& theta);The function returns the complex value whose magnitude
is rho and whose phase angle is theta.
double_complex pow(const double_complex& left, int right);
double_complex pow(const double_complex& left, const Ty& right);
double_complex pow(const double_complex& left,
const double_complex& right);
double_complex pow(const Ty& left, const double_complex& right);
float_complex pow(const float_complex& left, int right);
float_complex pow(const float_complex& left, const Ty& right);
float_complex pow(const float_complex& left,
const float_complex& right);
float_complex pow(const Ty& left, const float_complex& right);The functions each effectively convert both operands to
the return type, then return the converted
left to the power right.
The branch cut for left is along the negative real axis.
double real(const double_complex& left);
float real(const float_complex& left);
The function returns the real part of left.
double_complex sin(const double_complex& left);
float_complex sin(const float_complex& left);
The function returns the sine of left.
double_complex sinh(const double_complex& left);
float_complex sinh(const float_complex& left);
The function returns the hyperbolic sine of left.
double_complex sqrt(const double_complex& left);
float_complex sqrt(const float_complex& left);
The function returns the square root of left,
with phase angle in the half-open interval (-pi/2, pi/2].
The branch cuts are along the negative real axis.
#define __STD_COMPLEX
The macro is defined, with an unspecified expansion, to indicate
compliance with the specifications of this header.
double_complex tan(const double_complex& left);
float_complex tan(const float_complex& left);
The function returns the tangent of left.
double_complex tanh(const double_complex& left);
float_complex tanh(const float_complex& left);
The function returns the hyperbolic tangent of left.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
11 - crit_pb
Dinkumware, Ltd. Copyright and License NoticeDinkumware, Ltd.
Genuine Software
Copyright and License Notice
Dinkumware, Ltd.
398 Main Street
Concord MA 01742
USA
+1-978-371-2773
Dinkum C Library developed by P.J. Plauger
Dinkum C Library Reference developed by P.J. Plauger and Jim Brodie
The Dinkum C Library in machine-readable or printed form
(“Dinkum Library”) and the Dinkum C Library Reference in
machine-readable or printed form (“Dinkum Reference”), hereafter
in whole or in part the “Product,” are all copyright © 1992-2002 by
P.J. Plauger. ALL RIGHTS RESERVED. The Product is derived in part
from books copyright © 1989-1996 by P.J. Plauger, or by P.J. Plauger
and Jim Brodie.
Dinkumware, Ltd. and P.J. Plauger (“Licensor”) retain exclusive
ownership of this Product. It is licensed to you (“Licensee”) in
accordance with the terms specifically stated in this Notice. If you have
obtained this Product from a third party or under a special license from
Dinkumware, Ltd., additional restrictions may also apply. You
must otherwise treat the Product the same as other copyrighted
material, such as a book or recording. You may also exercise
certain rights particular to computer software under copyright law.
In particular:
- You may use the Library portion of the Product (if present)
to compile and link with C/C++ code to produce executable files.
- You may freely distribute such executable files for no additional
license fee to Licensor.
- You may make one or more backup copies of the Product for
archival purposes.
- You may permanently transfer ownership of the Product to another
party only if the other party agrees to the terms stated in this
Notice and you transfer or destroy all copies of the Product that
are in your posession.
- You must preserve this Notice and all copyright notices with
any copy you make of the Product.
- You may not loan, rent, or sublicense the Product.
- You may not copy or distribute, in any form, any part of this
Product for any purpose not specifically permitted by this Notice.
This copy of the Product is licensed for use by a limited number of
developers, which is specified as part of the packaging for this
Product. A license for up to ten users, for example, limits to ten
the number of developers reasonably able to use the Product at any
instant of time. Thus, ten is the maximum number of possible
concurrent users, not the number of actual concurrent users. A
single-user license is for use by just one developer.
Anyone who accesses this software has a moral responsibility not to
aid or abet illegal copying by others. Licensor recognizes that the
machine-readable format of the Product makes it particularly
conducive to sharing within multi-user systems and across networks.
Such use is permitted only so long as Licensee does not exceed the
maximum number of possible concurrent users and takes reasonable
precautions to protect the Product against unauthorized copying and
against public access. In particular, please note that the ability
to access this copy does not imply permission to use
it or to copy it.
Please note also that Licensor has expended considerable
professional effort in the production of this Product, and continues
to do so to keep it current.
Licensor warrants that the Product as shipped performs substantially
in accordance with its documented purpose, and that the medium on
which the Product is provided is free from defects in material and
workmanship. To the extent permitted by law, any implied warranties
on the Product are limited to 90 days.
Licensor's entire liability under this warranty shall be, at
Licensor's option, either to refund the license fee paid by
Licensee or to replace the medium on which the Product is provided.
This is also Licensee's exclusive remedy. To qualify for this
remedy, Licensee must demonstrate satisfactory proof of purchase to
Licensor and return the Product in reasonably good condition to
Licensor.
LICENSOR OTHERWISE MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE
SUITABILITY OF THIS PRODUCT, EITHER EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. LICENSOR
SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A
RESULT OF USING THIS PRODUCT, EVEN IF LICENSOR HAS BEEN ADVISED OF
THE POSSIBILITY OF SUCH DAMAGES. TO THE EXTENT PERMITTED BY LAW,
LICENSOR SHALL NOT BE LIABLE FOR CONSEQUENTIAL OR INCIDENTAL
DAMAGES.
By using this Product, you agree to abide by the intellectual
property laws and all other applicable laws of the USA, and the
terms described above. You may be held legally responsible for any
infringement that is caused or encouraged by your failure to abide
by the terms of this Notice.
RESTRICTED RIGHTS: Use, duplication, or disclosure by the government
is subject to the restrictions as set forth in subparagraph
(c)(1)(ii) of the Rights in Technical Data and Computer Software
Clause as DFARS 52.227-7013 and FAR 52.227-19. Unpublished rights
are reserved under the Copyright Laws of the USA. Contractor/
Manufacturer is DINKUMWARE, LTD., 398 Main Street, Concord MA 01742.
The terms of this notice shall be governed by the laws of the
Commonwealth of Massachusetts. THE RIGHTS AND OBLIGATIONS OF THE
PARTIES SHALL NOT BE GOVERNED BY THE PROVISIONS OF THE U.N.
CONVENTION FOR THE INTERNATIONAL SALE OF GOODS, 1980.
This Copyright and License Notice is the entire agreement of the
parties with respect to the matters set forth herein, and supersedes
any other oral or written agreements or communications relating
thereto, and shall alone be binding. No provision appearing on any
purchase order, quotation form, or other form originated by either
party shall be applicable.
Dinkumware and Dinkum are registered trademarks of Dinkumware, Ltd.
End of Copyright and License Notice
- ANSI Standard X3.159-1989
(New York NY: American National Standards Institute, 1989).
The original C Standard, developed by
the ANSI-authorized committee X3J11. The Rationale that accompanies
the C Standard explains many of the decisions that went into it, if
you can get your hands on a copy.
- ISO/IEC Standard 9899:1990
(Geneva: International Standards Organization, 1990).
Until 1999, the official C Standard around the world. Aside
from formatting details and section numbering, the ISO C Standard
is identical to the ANSI C Standard.
- ISO/IEC Amendment 1 to Standard 9899:1990
(Geneva: International Standards Organization, 1995).
The first (and only) amendment to the C Standard.
It provides substantial support for manipulating large character sets.
- ISO/IEC Standard 9899:1999
(Geneva: International Standards Organization, 1999).
The official C Standard around the world, replacing ISO/IEC
Standard 9899:1990.
- P.J. Plauger, The Standard C Library (Englewood Cliffs
NJ: Prentice Hall, 1992). Contains a complete implementation of the
Standard C library, as of 1992 at least,
as well as text from the library portion of the
C Standard and guidance in using the Standard C library.
- P.J. Plauger and Jim Brodie, Standard C: A Programmer's
Reference (Redmond WA: Microsoft Press, 1989).
The first complete but succinct reference to the entire C Standard.
It covers both the language and the library.
- P.J. Plauger and Jim Brodie, ANSI and ISO Standard C:
Programmer's Reference (Redmond WA: Microsoft Press, 1992).
An update to the above book.
- P.J. Plauger and Jim Brodie, Standard C (Englewood Cliffs NJ:
PTR Prentice Hall, 1996). An update to the above two books and
a principal source book for this material. It includes a
complete description of Amendment 1.
The authors welcome reports of any errors or omissions.
Please report any bugs or difficulties to:
Dinkumware Support
Dinkumware, Ltd.
398 Main Street
Concord MA 01742-2321
USA
+1-978-371-2773 (UTC -4 hours, -5 November through March)
+1-978-371-9014 (FAX)
support@dinkumware.com
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
12 - crit_pjp
Dinkumware, Ltd. Copyright and License NoticeDinkumware, Ltd.
Genuine Software
Copyright and License Notice
Dinkumware, Ltd.
398 Main Street
Concord MA 01742
USA
+1-978-371-2773
Dinkum C++ Library developed by P.J. Plauger
Dinkum C++ Library Reference developed by P.J. Plauger
The Dinkum C++ Library in machine-readable or printed form
(“Dinkum Library”) and the Dinkum C++ Library Reference in
machine-readable or printed form (“Dinkum Reference”), hereafter
in whole or in part the “Product,” are all copyright © 1989-2002 by
P.J. Plauger. ALL RIGHTS RESERVED. The Product is derived in part
from books copyright © 1992-2002 by P.J. Plauger.
Dinkumware, Ltd. and P.J. Plauger (“Licensor”) retain exclusive
ownership of this Product. It is licensed to you (“Licensee”) in
accordance with the terms specifically stated in this Notice. If you have
obtained this Product from a third party or under a special license from
Dinkumware, Ltd., additional restrictions may also apply. You
must otherwise treat the Product the same as other copyrighted
material, such as a book or recording. You may also exercise
certain rights particular to computer software under copyright law.
In particular:
- You may use the Library portion of the Product (if present)
to compile and link with C/C++ code to produce executable files.
- You may freely distribute such executable files for no additional
license fee to Licensor.
- You may make one or more backup copies of the Product for
archival purposes.
- You may permanently transfer ownership of the Product to another
party only if the other party agrees to the terms stated in this
Notice and you transfer or destroy all copies of the Product that
are in your posession.
- You must preserve this Notice and all copyright notices with
any copy you make of the Product.
- You may not loan, rent, or sublicense the Product.
- You may not copy or distribute, in any form, any part of this
Product for any purpose not specifically permitted by this Notice.
This copy of the Product is licensed for use by a limited number of
developers, which is specified as part of the packaging for this
Product. A license for up to ten users, for example, limits to ten
the number of developers reasonably able to use the Product at any
instant of time. Thus, ten is the maximum number of possible
concurrent users, not the number of actual concurrent users. A
single-user license is for use by just one developer.
Anyone who accesses this software has a moral responsibility not to
aid or abet illegal copying by others. Licensor recognizes that the
machine-readable format of the Product makes it particularly
conducive to sharing within multi-user systems and across networks.
Such use is permitted only so long as Licensee does not exceed the
maximum number of possible concurrent users and takes reasonable
precautions to protect the Product against unauthorized copying and
against public access. In particular, please note that the ability
to access this copy does not imply permission to use
it or to copy it.
Please note also that Licensor has expended considerable
professional effort in the production of this Product, and continues
to do so to keep it current.
Licensor warrants that the Product as shipped performs substantially
in accordance with its documented purpose, and that the medium on
which the Product is provided is free from defects in material and
workmanship. To the extent permitted by law, any implied warranties
on the Product are limited to 90 days.
Licensor's entire liability under this warranty shall be, at
Licensor's option, either to refund the license fee paid by
Licensee or to replace the medium on which the Product is provided.
This is also Licensee's exclusive remedy. To qualify for this
remedy, Licensee must demonstrate satisfactory proof of purchase to
Licensor and return the Product in reasonably good condition to
Licensor.
LICENSOR OTHERWISE MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE
SUITABILITY OF THIS PRODUCT, EITHER EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. LICENSOR
SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A
RESULT OF USING THIS PRODUCT, EVEN IF LICENSOR HAS BEEN ADVISED OF
THE POSSIBILITY OF SUCH DAMAGES. TO THE EXTENT PERMITTED BY LAW,
LICENSOR SHALL NOT BE LIABLE FOR CONSEQUENTIAL OR INCIDENTAL
DAMAGES.
By using this Product, you agree to abide by the intellectual
property laws and all other applicable laws of the USA, and the
terms described above. You may be held legally responsible for any
infringement that is caused or encouraged by your failure to abide
by the terms of this Notice.
RESTRICTED RIGHTS: Use, duplication, or disclosure by the government
is subject to the restrictions as set forth in subparagraph
(c)(1)(ii) of the Rights in Technical Data and Computer Software
Clause as DFARS 52.227-7013 and FAR 52.227-19. Unpublished rights
are reserved under the Copyright Laws of the USA. Contractor/
Manufacturer is DINKUMWARE, LTD., 398 Main Street, Concord MA 01742.
The terms of this notice shall be governed by the laws of the
Commonwealth of Massachusetts. THE RIGHTS AND OBLIGATIONS OF THE
PARTIES SHALL NOT BE GOVERNED BY THE PROVISIONS OF THE U.N.
CONVENTION FOR THE INTERNATIONAL SALE OF GOODS, 1980.
This Copyright and License Notice is the entire agreement of the
parties with respect to the matters set forth herein, and supersedes
any other oral or written agreements or communications relating
thereto, and shall alone be binding. No provision appearing on any
purchase order, quotation form, or other form originated by either
party shall be applicable.
Dinkumware and Dinkum are registered trademarks of Dinkumware, Ltd.
End of Copyright and License Notice
- ANSI Standard X3.159-1989
(New York NY: American National Standards Institute, 1989).
The original C Standard, developed by
the ANSI-authorized committee X3J11. The Rationale that accompanies
the C Standard explains many of the decisions that went into it, if
you can get your hands on a copy.
- ISO/IEC Standard 9899:1990
(Geneva: International Standards Organization, 1990).
Until 1999, the official C Standard around the world. Aside
from formatting details and section numbering, the ISO C Standard
is identical to the ANSI C Standard.
- ISO/IEC Amendment 1 to Standard 9899:1990
(Geneva: International Standards Organization, 1995).
The first (and only) amendment to the C Standard.
It provides substantial support for manipulating large character sets.
- ISO/IEC Standard 9899:1999
(Geneva: International Standards Organization, 1999).
The official C Standard around the world, replacing ISO/IEC
Standard 9899:1990.
- ISO/IEC Standard 14882:1998
(Geneva: International Standards Organization, 1998). The official
C++ Standard around the world.
The ISO C++ Standard is identical to the ANSI C++ Standard.
- P.J. Plauger, The Standard C Library (Englewood Cliffs
NJ: Prentice Hall, 1992). Contains a complete implementation of the
Standard C library, as of 1992 at least,
as well as text from the library portion of the
C Standard and guidance in using the Standard C library.
- P.J. Plauger, The Draft Standard C++ Library
(Englewood Cliffs NJ: Prentice Hall, 1995).
Contains a complete implementation
of the draft Standard C++ library as of early 1994.
- P.J. Plauger, Alexander Stepanov, Meng Lee, and David R. Musser,
The Standard Template Library (Englewood Cliffs NJ: Prentice
Hall, 2001). Contains a complete implementation of the Standard
Template Library as incorporated into the C++ Standard.
The author welcomes reports of any errors or omissions.
Please report any bugs or difficulties to:
Dinkumware Support
Dinkumware, Ltd.
398 Main Street
Concord MA 01742-2321
USA
+1-978-371-2773 (UTC -4 hours, -5 November through March)
+1-978-371-9014 (FAX)
support@dinkumware.com
See also the
Table of Contents and the
Index.
Copyright © 1989-2002 by P.J. Plauger. All rights reserved.
13 - csetjmp
<csetjmp>
Include the standard header <csetjmp>
to effectively include the standard header
<setjmp.h>.
#include <setjmp.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
14 - csignal
<csignal>
Include the standard header <csignal>
to effectively include the standard header
<signal.h>.
#include <signal.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
15 - cstdarg
<cstdarg>
Include the standard header <cstdarg>
to effectively include the standard header
<stdarg.h>.
#include <stdarg.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
16 - cstddef
<cstddef>
Include the standard header <cstddef>
to effectively include the standard header
<stddef.h>.
#include <stddef.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
17 - cstdio
<cstdio>
Include the standard header <cstdio>
to effectively include the standard header
<stdio.h>.
#include <stdio.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
18 - cstdlib
<cstdlib>
Include the standard header <cstdlib>
to effectively include the standard header
<stdlib.h>.
#include <stdlib.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
19 - cstring
<cstring>
Include the standard header <cstring>
to effectively include the standard header
<string.h>.
#include <string.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
20 - ctime
<ctime>
Include the standard header <ctime>
to effectively include the standard header
<time.h>.
#include <time.h>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
21 - ctype
<ctype.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
22 - cwchar
<cwchar>
Include the standard header <cwchar>
to define the macros traditionally defined in the Standard C library header
<wchar.h>.
Including this header also ensures that the names declared
with external linkage in the Standard C library header
are declared in the
std namespace.
In this implementation,
the names may or may not also be declared in the global namespace,
depending on the specific translation environment.
#if <TRADITIONAL C HEADERS>
#include <wchar.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
23 - cwctype
<cwctype>
Include the standard header <cwctype>
to define the macros traditionally defined in the Standard C library header
<wctype.h>.
Including this header also ensures that the names declared
with external linkage in the Standard C library header
are declared in the
std namespace.
In this implementation,
the names may or may not also be declared in the global namespace,
depending on the specific translation environment.
#if <TRADITIONAL C HEADERS>
#include <wctype.h>
#endif
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
24 - errno
<errno.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
25 - exceptio
<exception>
Include the standard header <exception>
to define several types and functions related to the handling
of exceptions.
// DECLARATIONS
class exception;
class bad_exception;
// FUNCTIONS
typedef void (*terminate_handler)();
typedef void (*unexpected_handler)();
terminate_handler
set_terminate(terminate_handler pnew) throw();
unexpected_handler
set_unexpected(unexpected_handler pnew) throw();
void terminate();
void unexpected();
bool uncaught_exception();
// END OF DECLARATIONSclass bad_exception
: public exception {
};The class describes an exception that can be thrown from an
unexpected handler.
The value returned by
what()
is an implementation-defined
C string.
None of the member functions throw any exceptions.
class exception {
public:
exception() throw();
exception(const exception& right) throw();
exception& operator=(const exception& right) throw();
virtual ~exception() throw();
virtual const char *what() const throw();
};The class serves as the base class for all exceptions thrown
by certain expressions and by the Standard C++ library. The
C string value returned by
what()
is left unspecified by the default constructor,
but may be defined by the constructors for certain derived classes
as an implementation-defined
C string.
None of the member functions throw any exceptions.
terminate_handler
set_terminate(terminate_handler pnew) throw();The function establishes a new
terminate handler
as the function *pnew. Thus, pnew must
not be a null pointer. The function returns the address of the
previous terminate handler.
unexpected_handler
set_unexpected(unexpected_handler pnew) throw();The function establishes a new
unexpected handler
as the function *pnew. Thus, pnew must
not be a null pointer. The function returns the address of the
previous unexpected handler.
void terminate();
The function calls a
terminate handler,
a function of type void ().
If terminate is called directly by the program,
the terminate handler is the one most recently set by a call to
set_terminate.
If terminate is called for any of several other
reasons during evaluation of a throw expression,
the terminate handler is the one in effect immediately after
evaluating the throw expression.
A terminate handler may not return to its caller. At
program startup,
the terminate handler is a function that calls
abort().
typedef void (*terminate_handler)();
The type describes a pointer to a function suitable for use as a
terminate handler.
bool uncaught_exception();
The function returns true only if a thrown exception is being currently
processed. Specifically, it returns true after completing evaluation of a
throw expression and before completing initialization of the exception
declaration in the matching handler or calling
unexpected as a result of the
throw expression.
void unexpected();
The function calls an
unexpected handler,
a function of type void ().
If unexpected is called directly by the program,
the unexpected handler is the one most recently set by a call to
set_unexpected.
If unexpected is called when control
leaves a function by a thrown exception of a type not permitted by an
exception specification
for the function, as in:
void func() throw() // function may throw no exceptions
{throw "bad"; } // throw calls unexpected()the unexpected handler is the one in effect immediately after
evaluating the throw expression.
An unexpected handler may not return to its caller. It may
terminate execution by:
- throwing an object of a type listed in the exception specification
(or an object of any type if the unexpected handler is called directly
by the program)
- throwing an object of type
bad_exception - calling
terminate(),
abort(), or
exit(int)
At program startup,
the unexpected handler is a function that calls
terminate().
typedef void (*unexpected_handler)();
The type describes a pointer to a function suitable for use as an
unexpected handler.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
26 - express
Expressions
You write expressions to determine values, to alter values stored
in objects, and to call functions that perform input and output. In
fact, you express all computations in the program by writing expressions.
The translator must evaluate some of the expressions you write
to determine properties of the program. The translator or the target
environment must evaluate other expressions prior to program startup
to determine the initial values stored in objects with static duration.
The program evaluates the remaining expressions when it executes.
This document describes briefly just those aspect
of expressions most relevant to the use of the Standard C library:
An
address constant expression
specifies a value that has a pointer type
and that the translator or target environment can determine
prior to program startup.
A constant expression
specifies a value that the translator or target environment can determine
prior to program startup.
An
integer constant expression
specifies a value that has an integer type
and that the translator can determine at the point in
the program where you write the expression.
(You cannot write a function call, assigning operator,
or comma operator except as part of the operand of a
sizeof operator.)
In addition, you must write only subexpressions
that have integer type. You can, however,
write a floating-point constant expression as the operand of an integer
type cast operator.
A
floating-point constant expression
specifies a value that has a floating-point type
and that the translator can determine at the point in
the program where you write the expression.
(You cannot write a function call, assigning operator,
or comma operator except as part of the operand of a
sizeof operator.)
In addition, you must write only subexpressions
that have integer or floating-point type.
An lvalue expression
An lvalue expression designates an object that has
an object type other than an array type. Hence, you can access the
value stored in the object.
A modifiable lvalue expression designates an object that has
an object type other than an array type or a const type. Hence,
you can alter the value stored in the object.
You can also designate objects with an lvalue expression
that has an array type or an incomplete type,
but you can only take the address of such an expression.
Promoting occurs for an
expression whose integer type is not one of the ``computational'' types.
Except when it is the operand of the
sizeof operator,
an integer
rvalue expression
has one of four types:
int, unsigned int, long, or unsigned long.
When you write an expression in an rvalue context and the expression
has an integer type that is not one of these types, the translator
promotes its type to one of these.
If all of the values representable in the
original type are also representable as type int, then the
promoted type is int. Otherwise, the promoted type is
unsigned int. Thus, for signed char, short,
and any signed bitfield type, the promoted type is int.
For each of the remaining integer types (char, unsigned char,
unsigned short, any plain bitfield type,
or any unsigned bitfield type), the effect of these rules
is to favor promoting to int wherever possible, but to promote
to unsigned int if necessary to preserve the original value
in all possible cases.
An rvalue expression
is an expression whose value can be determined only when the program executes.
The term also applies to expressions which need not
be determined until program execution.
You use the sizeof operator,
as in the expression sizeof X
to determine the size in bytes of an object whose type
is the type of X. The translator uses the expression
you write for X only to determine a type;
it is not evaluated.
A void expression
has type void.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
27 - float
<float.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
28 - fstream
<fstream>
Include the iostreams
standard header <fstream>
to define several classes that support
iostreams operations on
sequences stored in external
files.
// DECLARATIONS
class filebuf;
class ifstream;
class ofstream;
// END OF DECLARATIONSclass filebuf : public streambuf {
public:
typedef typename streambuf<Elem, Tr>::char_type
char_type;
typedef typename streambuf<Elem, Tr>::traits_type
traits_type;
typedef typename streambuf<Elem, Tr>::int_type
int_type;
typedef typename streambuf<Elem, Tr>::pos_type
pos_type;
typedef typename streambuf<Elem, Tr>::off_type
off_type;
filebuf();
bool is_open() const;
filebuf *open(const char *filename,
ios_base::openmode mode);
filebuf *close();
protected:
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual pos_type seekpos(pos_type pos,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual int_type underflow();
virtual int_type pbackfail(int_type meta =
traits_type::eof());
virtual int_type overflow(int_type meta =
traits_type::eof());
virtual int sync();
virtual streambuf
*setbuf(Elem *buffer, streamsize count);
};The class
describes a stream buffer that controls
the transmission of elements to and from a sequence of elements
stored in an external
file.
An object of class
filebuf stores a
file pointer, which designates the
FILE object
that controls the stream
associated with an
open file.
filebuf();
The constructor stores a null pointer in all the pointers
controlling the
input buffer and the
output buffer. It
also stores a null pointer in the
file pointer.
typedef char char_type;
The type is a synonym for char.
filebuf *close();
The member function returns a null pointer if the
file pointer fp
is a null pointer. Otherwise, it calls
fclose(fp).
If that function returns a nonzero value, the function
returns a null pointer. Otherwise, it returns this
to indicate that the file was successfully
closed.
typedef traits_type::int_type int_type;
The type is a synonym for
traits_type::int_type.
bool is_open();
The member function returns true if the
file pointer is not a null pointer.
typedef traits_type::off_type off_type;
The type is a synonym for
traits_type::off_type.
filebuf *open(const char *filename,
ios_base::openmode mode);The member function endeavors to open the file with
filename filename, by calling
fopen(filename, strmode). Here
strmode is determined from mode &
~(ate & |
binary):
ios_base::in
becomes "r" (open existing file for reading).ios_base::out or
ios_base::out |
ios_base::trunc
becomes "w" (truncate existing file or create for writing).ios_base::out |
ios_base::app
becomes "a" (open existing file for appending all writes).ios_base::in | ios_base::out
becomes "r+" (open existing file for reading and writing).ios_base::in | ios_base::out |
ios_base::trunc becomes "w+"
(truncate existing file or create for reading and writing).ios_base::in | ios_base::out |
ios_base::app becomes "a+"
(open existing file for reading and for appending all writes).
If mode & ios_base::binary is nonzero,
the function appends b to strmode
to open a binary stream
instead of a text stream.
It then stores the value returned by fopen in the
file pointer fp. If
mode & ios_base::ate is nonzero and the
file pointer is not a null pointer, the function calls
fseek(fp, 0,
SEEK_END) to
position the stream at end-of-file. If that positioning operation
fails, the function calls
close(fp) and
stores a null pointer in the file pointer.
If the file pointer is a null pointer, the function returns
a null pointer. Otherwise, it returns this.
virtual int_type overflow(int_type meta =
traits_type::eof());If meta !=
traits_type::eof(),
the protected virtual member function endeavors to insert the element
ch = traits_type::to_char_type(meta)
into the
output buffer.
It can do so in various ways:
- If a write position
is available, it can store the element into the write position
and increment the next pointer for the output buffer.
- It can make a write position available by allocating
new or additional storage for the output buffer.
- It can write any pending output in the output buffer, followed
by
ch, to the associated stream designated by the
file pointer fp
as if by successive calls of the form
fputc(ch, fp).
If any conversion or write fails, the function does not succeed.
If the function cannot succeed, it returns traits_type::eof().
Otherwise, it returns
traits_type::not_eof(meta).
virtual int_type pbackfail(int_type meta =
traits_type::eof());The protected virtual member function endeavors to put back an element
into the
input buffer,
then make it the current element (pointed to
by the next pointer). If meta ==
traits_type::eof(),
the element to push back is effectively the one already in the stream
before the current element. Otherwise, that element is replaced by
ch =
traits_type::to_char_type(meta).
The function can put back an element in various ways:
- If a putback position
is available, and the element stored there compares equal to
ch,
it can simply decrement the next pointer for the input buffer. - If the function can make a putback position available,
it can do so, set the next pointer to point at that position,
and store
ch in that position. - If the function can push back an element onto the input stream,
it can do so, such as by calling
ungetc for an element
of type char.
If the function cannot succeed, it returns
traits_type::eof(). Otherwise, it returns
traits_type::not_eof(meta).
typedef traits_type::pos_type pos_type;
The type is a synonym for
traits_type::pos_type.
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
filebuf, a stream position can be represented
by an object of type
fpos_t.
Offset zero designates the first element of the stream.
(An object of type
pos_type
stores at least an fpos_t object.)
For a file opened for both reading and writing,
both the input and output streams are positioned in tandem. To
switch
between inserting and extracting, you must call either
pubseekoff
or
pubseekpos.
Calls to pubseekoff (and hence to seekoff)
have various limitations for
text streams
and binary streams.
If the
file pointer fp
is a null pointer, the function fails. Otherwise, it endeavors
to alter the stream position by calling
fseek(fp, off, way).
If that function succeeds and the resultant position
fposn can be determined by calling
fgetpos(fp, &fposn),
the function succeeds. If the function succeeds, it returns
a value of type pos_type containing fposn.
Otherwise, it returns an invalid stream position.
virtual pos_type seekpos(pos_type pos,
ios_base::openmode which =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
filebuf, a stream position can be represented
by an object of type
fpos_t.
Offset zero designates the first element of the stream.
(An object of type
pos_type
stores at least an fpos_t object.)
For a file opened for both reading and writing,
both the input and output streams are positioned in tandem. To
switch
between inserting and extracting, you must call either
pubseekoff
or
pubseekpos.
Calls to pubseekoff (and hence to seekoff)
have various limitations for
both text streams
and binary streams.
If the
file pointer fp
is a null pointer, the function fails. Otherwise, it endeavors
to alter the stream position by calling
fsetpos(fp, &fposn),
where fposn is the fpos_t object stored
in pos. If that function succeeds, the function returns
pos. Otherwise, it returns an invalid stream position.
virtual streambuf
*setbuf(Elem *buffer, streamsize count);The protected member function returns zero if the
file pointer fp
is a null pointer. Otherwise, it calls
setvbuf(fp, (char *)buffer,
_IOFBF, count * sizeof (Elem))
to offer the array of count elements beginning at buffer
as a buffer for the stream. If that function returns a nonzero value,
the function returns a null pointer. Otherwise, it returns this
to signal success.
int sync();
The protected member function returns zero if the
file pointer fp
is a null pointer. Otherwise, it returns zero only if calls to both
overflow() and
fflush(fp)
succeed in flushing any pending output to the stream.
typedef char_traits traits_type;
The type is a synonym for
char_traits.
virtual int_type underflow();
The protected virtual member function endeavors to extract the current
element ch from the input stream, and return the element as
traits_type::to_int_type(ch).
It can do so in various ways:
- If a read position is available,
it takes
ch as the element stored in the read position
and advances the next pointer for the
input buffer. - It can read one or more elements of type char,
as if by successive calls of the form
fgetc(fp).
If any read or conversion fails,
the function does not succeed.
If the function cannot succeed, it returns
traits_type::eof(). Otherwise,
it returns ch, converted as described above.
class ifstream : public istream {
public:
filebuf *rdbuf() const;
ifstream();
explicit ifstream(const char *filename,
ios_base::openmode mode = ios_base::in);
bool is_open() const;
void open(const char *filename,
ios_base::openmode mode = ios_base::in);
void close();
};The class describes an object that controls
extraction of elements and encoded objects from a
stream buffer of class
filebuf.
The object stores an object of class
filebuf.
ifstream();
explicit ifstream(const char *filename,
ios_base::openmode mode = ios_base::in);The first constructor initializes the base class by calling
istream(sb),
where sb is the stored object of class
filebuf.
It also initializes sb by calling
filebuf().
The second constructor initializes the base class by calling
istream(sb).
It also initializes sb by calling
filebuf(),
then sb.open(filename, mode
| ios_base::in). If the latter function returns a null
pointer, the constructor calls
setstate(failbit).
void close();
The member function calls
rdbuf()->
close().
bool is_open();
The member function returns
rdbuf()->
is_open().
void open(const char *filename,
ios_base::openmode mode = ios_base::in);The member function calls
rdbuf()->
open(filename, mode | ios_base::in).
If that function returns a null pointer, the function calls
setstate(failbit).
filebuf *rdbuf() const
The member function returns the address of the stored stream buffer.
class ofstream : public ostream {
public:
filebuf *rdbuf() const;
ofstream();
explicit ofstream(const char *filename,
ios_base::openmode mode = ios_base::out);
bool is_open() const;
void open(const char *filename,
ios_base::openmode mode = ios_base::out);
void close();
};The class describes an object that controls
insertion of elements and encoded objects into a
stream buffer of class
filebuf.
The object stores an object of class
filebuf.
ofstream();
explicit ofstream(const char *filename,
ios_base::openmode which = ios_base::out);The first constructor initializes the base class by calling
ostream(sb),
where sb is the stored object of class
filebuf<Elem, Tr>.
It also initializes sb by calling
filebuf().
The second constructor initializes the base class by calling
ostream(sb).
It also initializes sb by calling
filebuf(),
then sb.open(filename, mode
| ios_base::out). If the latter function returns a null
pointer, the constructor calls
setstate(failbit).
void close();
The member function calls
rdbuf()->
close().
bool is_open();
The member function returns
rdbuf()->
is_open().
void open(const char *filename,
ios_base::openmode mode = ios_base::out);The member function calls
rdbuf()->
open(filename, mode | ios_base::out).
If that function returns a null pointer, the function calls
setstate(failbit).
filebuf *rdbuf() const
The member function returns the address of the stored
stream buffer.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
29 - fstream2
<fstream.h>
Include the traditional header <fstream.h>
to effectively include the standard header
<fstream>.
#include <fstream>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
30 - function
Functions
You write functions to specify all the actions that a program
performs when it executes. The type of a function tells you the type
of result it returns (if any). It can also tell you the types of any
arguments that the function expects when you call it from within an
expression.
This document describes briefly just those aspect
of functions most relevant to the use of the Standard C library:
Argument promotion
occurs when the type of the function fails to provide any information
about an argument. Promotion occurs if the function declaration
is not a function prototype or if the argument is one of
the unnamed arguments in a
varying number
of arguments. In this instance, the argument must be an
rvalue expression. Hence:
- An integer argument type is promoted.
- An lvalue of type array of
Ty becomes an rvalue of type
pointer to Ty. - A function designator of type function returning
Ty becomes
an rvalue of type pointer to function returning Ty. - An argument of type float is converted to double.
A do statement
executes a statement one or more times, while its
test-context expression
has a nonzero value:
do
statement
while (test);An expression statement
evaluates an expression in a
side-effects context:
printf("hello\n"); call a function
y = m * x + b; store a value
++count; alter a stored valueA for statement
executes a statement zero or more times, while the optional
test-context expression
test has a nonzero value.
You can also write two expressions, se-1
and se-2, in a for statement that are each in a
side-effects context:
for (se-1; test; se-2)
statementAn if statement
executes a statement only if the
test-context expression
has a nonzero value:
if (test)
statementAn if-else statement
executes one of two statements, depending on whether the
test-context expression
has a nonzero value:
if (test)
statement-1
else
statement-2A return statement
terminates execution of the function and transfers control
to the expression that called the function. If you write the optional
rvalue expression
within the return statement,
the result must be assignment-compatible with the type returned
by the function. The program converts the value of the expression
to the type returned and returns it as the value of the function call:
return expression;
An expression that occurs in a
side-effects context
specifies no value and designates no object or function.
Hence, it can have type void.
You typically evaluate such an expression for its
side effects
-- any change in the state of the program that occurs when evaluating
an expression. Side effects occur when the program
stores a value in an object, accesses a value from an object
of volatile qualified type, or alters the state of a file.
A switch statement
jumps to a place within a controlled statement, depending
on the value of an integer expression:
switch (expr)
{
case val-1:
stat-1;
break;
case val-2:
stat-2; falls through to next
default:
stat-n
}In a
test-context expression
the value of an expression causes control
to flow one way within the statement if the computed value is nonzero
or another way if the computed value is zero. You can write only an
expression that has a scalar rvalue result, because only scalars can
be compared with zero.
A while statement
executes a statement zero or more times, while the test-context
expression has a nonzero value:
while (test)
statement
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
31 - iomanip
<iomanip>
Include the iostreams
standard header <iomanip>
to define several manipulators
that each take a single argument. Each of these manipulators returns
an unspecified type, called T1 through T6
here, that overloads both
istream::operator>>
and
ostream::operator<<.
Thus, you can write extractors and inserters such as:
cin >> setbase(8);
cout << setbase(8);
// DECLARATIONS
T1 resetiosflags(ios_base::fmtflags mask);
T2 setiosflags(ios_base::fmtflags mask);
T3 setbase(int base);
T4 setfill(char ch);
T5 setprecision(streamsize prec);
T6 setw(streamsize wide);
// END OF DECLARATIONST1 resetiosflags(ios_base::fmtflags mask);
The manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.setf(ios_base::
fmtflags(), mask),
then returns str.
T3 setbase(int base);
The manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.setf(mask,
ios_base::basefield),
then returns str. Here, mask is determined
as follows:
- If
base is 8, then mask is
ios_base::oct - If
base is 10, then mask is
ios_base::dec - If
base is 16, then mask is
ios_base::hex - If
base is any other value, then mask is
ios_base::fmtflags(0)
T4 setfill(char ch);
The manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.fill(ch),
then returns str.
T2 setiosflags(ios_base::fmtflags mask);
The manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.setf(mask),
then returns str.
T5 setprecision(streamsize prec);
The manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.precision(prec),
then returns str.
T6 setw(streamsize wide);
The manipulator returns an object that, when extracted from or
inserted into the stream str, calls
str.width(wide),
then returns str.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
32 - iomanip2
<iomanip.h>
Include the traditional header <iomanip.h>
to effectively include the standard header
<iomanip>.
#include <iomanip>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
33 - ios
<ios>
ios
· fpos
· ios_base
· locale
· mbstate_t
· streamoff
· streampos
· streamsize
boolalpha
· dec
· fixed
· hex
· internal
· left
· noboolalpha
· noshowbase
· noshowpoint
· noshowpos
· noskipws
· nounitbuf
· nouppercase
· oct
· right
· scientific
· showbase
· showpoint
· showpos
· skipws
· unitbuf
· uppercase
Include the iostreams
standard header <ios> to
define several types and functions basic to the operation of
iostreams. (This header is
typically included for you by another of the iostreams headers. You
seldom have occasion to include it directly.)
A large group of functions are
manipulators. A manipulator
declared in <ios> alters the values stored in its
argument object of class
ios_base. Other manipulators
perform actions on streams controlled by objects of a type derived from
this class,
such as one of the classes
istream or
ostream.
For example, noskipws(str)
clears the format flag
ios_base::skipws in the object
str, which might be of one of these types.
You can also call a manipulator by inserting it into an output
stream or extracting it from an input stream, thanks to some special
machinery supplied in the classes derived from
ios_base. For example:
istr >> noskipws;
calls noskipws(istr).
// DECLARATIONS
typedef T1 streamoff;
typedef T2 streamsize;
class ios_base;
class ios;
class fpos;
class locale;
typedef T3 mbstate_t;
typedef fpos streampos;
// MANIPULATORS
ios_base& boolalpha(ios_base& iosbase);
ios_base& noboolalpha(ios_base& iosbase);
ios_base& showbase(ios_base& iosbase);
ios_base& noshowbase(ios_base& iosbase);
ios_base& showpoint(ios_base& iosbase);
ios_base& noshowpoint(ios_base& iosbase);
ios_base& showpos(ios_base& iosbase);
ios_base& noshowpos(ios_base& iosbase);
ios_base& skipws(ios_base& iosbase);
ios_base& noskipws(ios_base& iosbase);
ios_base& unitbuf(ios_base& iosbase);
ios_base& nounitbuf(ios_base& iosbase);
ios_base& uppercase(ios_base& iosbase);
ios_base& nouppercase(ios_base& iosbase);
ios_base& internal(ios_base& iosbase);
ios_base& left(ios_base& iosbase);
ios_base& right(ios_base& iosbase);
ios_base& dec(ios_base& iosbase);
ios_base& hex(ios_base& iosbase);
ios_base& oct(ios_base& iosbase);
ios_base& fixed(ios_base& iosbase);
ios_base& scientific(ios_base& iosbase);
// END OF DECLARATIONS
bad
· ios
· char_type
· clear
· copyfmt
· eof
· exceptions
· init
· fail
· good
· imbue
· init
· int_type
· narrow
· off_type
· operator!
· operator void *
· pos_type
· rdbuf
· rdstate
· setstate
· tie
· traits_type
· widen
class ios : public ios_base {
public:
typedef char char_type;
typedef char_traits traits_type;
typedef char_traits::int_type int_type;
typedef char_traits::pos_type pos_type;
typedef char_traits::off_type off_type;
explicit ios(streambuf *strbuf);
virtual ~ios();
operator void *() const;
bool operator!() const;
iostate rdstate() const;
void clear(iostate state = goodbit);
void setstate(iostate state);
bool good() const;
bool eof() const;
bool fail() const;
bool bad() const;
iostate exceptions() const;
iostate exceptions(iostate newexcept);
ios& copyfmt(const ios& right);
locale imbue(const locale& loc);
char_type widen(char ch);
char narrow(char_type ch, char dflt);
char_type fill() const;
char_type fill(char_type ch);
ostream *tie() const;
ostream *tie(ostream *newtie);
streambuf *rdbuf() const;
streambuf *rdbuf(streambuf *strbuf);
protected:
void init(streambuf *strbuf);
ios();
ios(const facet&); // not defined
void operator=(const facet&) // not defined
};The class describes the storage and member functions common
to both input streams (of class
istream)
and output streams (of class
ostream).
An object of class
ios helps control a stream with elements
of type char, also known as char_type, whose
character traits are determined by the
class char_traits.
An object of class ios stores:
bool bad() const;
The member function returns true if
rdstate() & badbit
is nonzero.
explicit ios(streambuf *strbuf);
ios();
The first constructor initializes its member objects by calling
init(strbuf). The second
(protected) constructor leaves its member objects uninitialized. A later
call to init must initialize the object before it
can be safely destroyed.
typedef char char_type;
The type is a synonym for char.
void clear(iostate state = goodbit);
The member function replaces the stored
stream state information with
state |
(rdbuf() != 0 ? goodbit : badbit).
If state &
exceptions() is nonzero, it
then throws an object of class
failure.
ios& copyfmt(const ios& right);
The member function reports the
callback event
erase_event.
It then copies from right into *this
the fill character,
the tie pointer, and the
formatting information.
Before altering the
exception mask, it reports the
callback event
copyfmt_event.
If, after the copy is complete, state &
exceptions() is nonzero,
the function effectively calls
clear with the argument
rdstate().
It returns *this.
bool eof() const;
The member function returns true if
rdstate() & eofbit
is nonzero.
iostate exceptions() const;
iostate exceptions(iostate newexcept);
The first member function returns the stored
exception mask. The second member
function stores except in the exception mask and returns
its previous stored value.
bool fail() const;
The member function returns true if
rdstate() & (badbit | failbit)
is nonzero.
char_type fill() const;
char_type fill(char_type ch);
The first member function returns the stored
fill character. The second member
function stores ch in the fill character and returns its
previous stored value.
bool good() const;
The member function returns true if
rdstate() == goodbit
(no state flags are set).
locale imbue(const locale& loc);
The member function calls
ios_base::imbue(loc).
If rdbuf is not a
null pointer, it also calls
rdbuf()->pubimbue(loc).
In any case, it returns the value returned by the call to
ios_base::imbue.
void init(streambuf *strbuf);
The member function stores values in all member objects, so that:
typedef int int_type;
The type is a synonym for int.
char narrow(char_type ch, char dflt);
The member function returns
ch.
typedef streamoff off_type;
The type is a synonym for
streamoff.
operator void *() const;
The operator returns a null pointer only if
fail().
bool operator!() const;
The operator returns
fail().
typedef streampos pos_type;
The type is a synonym for
streampos.
streambuf *rdbuf() const;
streambuf *rdbuf(streambuf *strbuf);
The first member function returns the stored
stream buffer pointer.
The second member function stores strbuf in the stored
stream buffer pointer
and returns the previously stored value.
iostate rdstate() const;
The member function returns the stored
stream state information.
void setstate(iostate state);
The member function effectively calls
clear(state |
rdstate()).
ostream *tie() const;
ostream *tie(ostream *newtie);
The first member function returns the stored
tie pointer. The second member function
stores newtie in the tie pointer and returns its previous
stored value.
typedef char_traits traits_type;
The type is a synonym for
char_traits.
char_type widen(char ch);
The member function returns
ch.
ios_base& boolalpha(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
boolalpha), then returns
iosbase.
ios_base& dec(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
dec, ios_base::
basefield), then returns
iosbase.
ios_base& fixed(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
fixed, ios_base::
floatfield), then returns
iosbase.
class fpos {
public:
typedef mbstate_t St;
fpos(streamoff off);
fpos(St state, fpos_t filepos);
St state() const;
void state(St state);
operator streamoff() const;
streamoff operator-(const fpos& right) const;
fpos& operator+=(streamoff off);
fpos& operator-=(streamoff off);
fpos operator+(streamoff off) const;
fpos operator-(streamoff off) const;
bool operator==(const fpos& right) const;
bool operator!=(const fpos& right) const;
};The class describes an object
that can store all the information needed to restore an arbitrary
file-position indicator
within any stream. An object of class fpos effectively
stores at least two member objects:
- a byte offset, of type
streamoff - a conversion state, for use by an object of class
filebuf,
of type St, which is an unofficial synonym for
mbstate_t
It can also store an arbitrary file position, for use by an object of class
filebuf,
of type fpos_t.
For an environment with limited file size, however,
streamoff and fpos_t may sometimes
be used interchangeably. So the number of
member objects stored may vary.
fpos(streamoff off);
fpos(St state, fpos_t filepos);
The first constructor stores the offset
off,
relative to the beginning of file.
If off is -1,
the resulting object represents an invalid stream position.
The second constructor stores the object state
and a file position determined by filepos.
bool operator!=(const fpos& right) const;
The member function returns !(*this == right).
fpos operator+(streamoff off) const;
The member function returns fpos(*this) += off.
fpos& operator+=(streamoff off);
The member function adds off to the stored offset member object,
then returns *this. For positioning within a file, the
result is generally valid only for
binary streams.
streamoff operator-(const fpos& right) const;
fpos operator-(streamoff off) const;
The first member function returns (streamoff)*this - (streamoff)right.
The second member function returns fpos(*this) -= off.
fpos& operator-=(streamoff off);
The member function returns fpos(*this) -= off.
For positioning within a file, the result is generally valid only for
binary streams.
bool operator==(const fpos& right) const;
The member function returns (streamoff)*this == (streamoff)right.
operator streamoff() const;
The member function returns the stored offset member object,
plus any additional offset stored as part of the fpos_t member object.
St state() const;
void state(St state);
The first member function returns the value stored in the
St member object. The second member function
stores state in the St member object.
ios_base& hex(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
hex, ios_base::
basefield), then returns
iosbase.
ios_base& internal(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
internal, ios_base::
adjustfield), then returns
iosbase.
event
· event_callback
· failure
· flags
· fmtflags
· getloc
· imbue
· Init
· ios_base
· iostate
· iword
· openmode
· operator=
· precision
· pword
· register_callback
· seekdir
· setf
· streamoff
· streampos
· sync_with_stdio
· unsetf
· width
· xalloc
class ios_base {
public:
class failure;
typedef T1 fmtflags;
static const fmtflags boolalpha, dec, fixed, hex,
internal, left, oct, right, scientific,
showbase, showpoint, showpos, skipws, unitbuf,
uppercase, adjustfield, basefield, floatfield;
typedef T2 iostate;
static const iostate badbit, eofbit, failbit,
goodbit;
typedef T3 openmode;
static const openmode app, ate, binary, in, out,
trunc;
typedef T4 seekdir;
typedef ::streamoff streamoff;
typedef ::streampos streampos;
static const seekdir beg, cur, end;
enum event {
copyfmt_event, erase_event,
imbue_event};
static const event copyfmt_event, erase_event,
copyfmt_event;
class Init;
ios_base& operator=(const ios_base& right);
fmtflags flags() const;
fmtflags flags(fmtflags newfmtflags);
fmtflags setf(fmtflags newfmtflags);
fmtflags setf(fmtflags newfmtflags, fmtflags mask);
void unsetf(fmtflags mask);
streamsize precision() const;
streamsize precision(streamsize newprecision);
streamsize width() const;
stramsize width(streamsize newwidth);
locale imbue(const locale& loc);
locale getloc() const;
static int xalloc();
long& iword(int idx);
void *& pword(int idx);
typedef void *(event_callback(event ev,
ios_base& iosbase, int idx);
void register_callback(event_callback pfn, int idx);
static bool sync_with_stdio(bool newsync = true);
protected:
ios_base();
};The class describes the storage and member functions common to both
input and output streams. The class
ios describes additional
common features.
An object of class ios_base stores
formatting information,
which consists of:
An object of class ios_base also stores
stream state information,
in an object of type
iostate, and a
callback stack.
enum event {
copyfmt_event, erase_event,
imbue_event};The type is an enumeration that describes an
object that can store the
callback event used as an argument to
a function registered with
register_callback.
The distinct event values are:
copyfmt_event,
to identify a callback that occurs near the end of a call to
copyfmt, just before the
exception mask is copied.erase_event,
to identify a callback that occurs at the beginning of a call to
copyfmt, or at
the beginning of a call to the destructor for *this.imbue_event,
to identify a callback that occurs at the end of a call to
imbue, just before the
function returns.
typedef void *(event_callback(event ev,
ios_base& iosbase, int idx);The type describes a pointer to a function that can
be registered with
register_callback.
Such a function must not throw an exception.
class failure : public exception {
public:
explicit failure(const string& what_arg) {
};The member class serves as the base class
for all exceptions thrown by the member function
clear in template class
ios. The value returned by
what() is
what_arg.data().
fmtflags flags() const;
fmtflags flags(fmtflags newfmtflags);
The first member function returns the stored
format flags. The second member function
stores newfmtflags in the format flags and returns its previous
stored value.
typedef T1 fmtflags;
static const fmtflags boolalpha, dec, fixed, hex,
internal, left, oct, right, scientific,
showbase, showpoint, showpos, skipws, unitbuf,
uppercase, adjustfield, basefield, floatfield;The type is a bitmask type
T1 that describes an object that can store
format flags. The distinct flag values (elements) are:
boolalpha, to insert or
extract objects of type bool as names (such as true
and false) rather than as numeric valuesdec, to insert or extract
integer values in decimal formatfixed, to insert
floating-point values in fixed-point format (with no exponent field)hex, to insert or extract
integer values in hexadecimal formatinternal,
to pad to a field width
as needed by inserting fill
characters at a point internal to a generated numeric fieldleft,
to pad to a field width as needed
by inserting fill characters
at the end of a generated field (left justification)oct, to insert or extract
integer values in octal formatright,
to pad to a field width
as needed by inserting fill characters
at the beginning of a generated field (right justification)scientific, to insert
floating-point values in scientific format (with an exponent field)showbase, to insert a
prefix that reveals the base of a generated integer fieldshowpoint, to insert a
decimal point unconditionally in a generated floating-point fieldshowpos, to insert a plus
sign in a non-negative generated numeric fieldskipws, to skip leading
white space before certain
extractionsunitbuf, to flush output
after each insertionuppercase, to insert
uppercase equivalents of lowercase letters in certain insertions
In addition, several useful values are:
locale getloc() const;
The member function returns the stored
locale object.
locale imbue(const locale& loc);
The member function stores loc in the
locale object, then reports the
callback event
imbue_event.
It returns the previous stored value.
class Init {
};The nested class describes an object whose construction ensures that
the standard iostreams objects are properly
constructed, even
before the execution of a constructor for an arbitrary static object.
ios_base();
The (protected) constructor does nothing. A later call to
ios::init
must initialize the object before it can be safely destroyed.
Thus, the only safe use for class ios_base is as a base
class for template class
ios.
typedef T2 iostate;
static const iostate badbit, eofbit, failbit, goodbit;
The type is a bitmask type
T2 that describes an object that can store
stream state information. The
distinct flag values (elements) are:
badbit, to record a loss of
integrity of the stream buffereofbit, to record
end-of-file while extracting from a streamfailbit, to record a
failure to extract a valid field from a stream
In addition, a useful value is:
long& iword(int idx);
The member function returns a reference to element
idx of the
extensible array with elements of type
long. All elements are effectively present and initially store
the value zero. The returned reference is invalid after the next call to
iword for the object, after the object is altered by a call to
ios::copyfmt, or
after the object is destroyed.
If idx is negative, or if unique storage is unavailable
for the element, the function calls
setstate(badbit)
and returns a reference that might not be unique.
To obtain a unique index, for use across all objects of type
ios_base, call
xalloc.
typedef T3 openmode;
static const openmode app, ate, binary, in, out, trunc;
The type is a bitmask type
T3 that describes an object that can store the
opening mode for several iostreams
objects. The distinct flag values (elements) are:
app, to seek to the end of a
stream before each insertionate, to seek to the end of a
stream when its controlling object is first createdbinary, to read a file as a
binary stream,
rather than as a
text streamin,
to permit extraction from a streamout,
to permit insertion to a streamtrunc, to truncate an
existing file when its controlling object is first created
ios_base& operator=(const ios_base& right);
The operator copies the stored
formatting information,
making a new copy of any
extensible arrays.
It then returns *this. Note that the
callback stack is not copied.
streamsize precision() const;
streamsize precision(streamsize newprecision);
The first member function returns the stored
display precision. The second member
function stores newprecision in the display precision and returns
its previous stored value.
void *& pword(int idx);
The member function returns a reference to element idx of the
extensible array with elements of type
void pointer. All elements are effectively present and initially
store the null pointer. The returned reference is invalid after the next
call to pword for the object,
after the object is altered by a call to
ios::copyfmt, or
after the object is destroyed.
If idx is negative, or if unique storage is unavailable
for the element, the function calls
setstate(badbit)
and returns a reference that might not be unique.
To obtain a unique index, for use across all objects of type
ios_base, call
xalloc.
void register_callback(event_callback pfn, int idx);
The member function pushes the pair {pfn, idx}
onto the stored
callback stack. When a
callback event ev is reported,
the functions are called, in reverse order of registry, by the
expression (*pfn)(ev, *this, idx).
typedef T4 seekdir;
static const seekdir beg, cur, end;
The type is an enumerated type T4 that describes an
object that can store the
seek mode used as an argument to the
member functions of several iostreams classes. The distinct flag values
are:
beg, to seek (alter the
current read or write position) relative to the beginning oc a sequence
(array, stream, or file)cur, to seek relative to the
current position within a sequenceend, to seek relative to the
end of a sequence
void setf(fmtflags newfmtflags);
fmtflags setf(fmtflags newfmtflags, fmtflags mask);
The first member function effectively calls
flags(newfmtflags | flags()) (set
selected bits), then returns the previous
format flags. The second member function
effectively calls
flags(mask & newfmtflags, flags() & ~mask) (replace selected
bits under a mask), then returns the previous format flags.
typedef ::streamoff streamoff;
The type is a synonym for
::streamoff.
typedef ::streampos streampos;
The type is a synonym for
::streampos.
static bool sync_with_stdio(bool newsync = true);
The static member function stores a
stdio sync flag, which is initially true.
When true, this flag ensures that operations on the same file are properly synchronized
between the iostreams functions and those defined
in the Standard C library.
Otherwise, synchronization may or may not be guaranteed, but performance may be
improved.
The function stores newsync in the stdio sync flag and returns its
previous stored value. You can call it reliably only before performing any operations
on the standard streams.
void unsetf(fmtflags mask);
The member function effectively calls
flags(~mask & flags())
(clear selected bits).
streamsize width() const;
streamsize width(streamsize newwidth);
The first member function returns the stored
field width. The second member function
stores newwidth in the field width and returns its previous
stored value.
static int xalloc();
The static member function returns a stored static value, which it
increments on each call. You can use the return value as a unique index
argument when calling the member functions
iword or
pword.
ios_base& left(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
left, ios_base::
adjustfield), then returns
iosbase.
class locale {
};The class serves as a placeholder for the much more elaborate locale
machinery mandated by Standard C++.
typedef T3 mbstate_t;
The type is an unspecified type T3 that serves as a placeholder
for the more elaborate conversion-state machinery, used to convert between
multibyte and wide-character encodings, mandated by Standard C.
ios_base& noboolalpha(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
boolalpha), then returns
iosbase.
ios_base& noshowbase(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
showbase),
then returns iosbase.
ios_base& noshowpoint(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
showpoint), then returns
iosbase.
ios_base& noshowpos(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
showpos"),
then returns iosbase.
ios_base& noskipws(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
skipws),
then returns iosbase.
ios_base& nounitbuf(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
unitbuf),
then returns iosbase.
ios_base& nouppercase(ios_base& iosbase);
The manipulator effectively calls
iosbase.unsetf(ios_base::
uppercase), then returns
iosbase.
ios_base& oct(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
oct, ios_base::
basefield), then returns
iosbase.
ios_base& right(ios_base& iosbase);
The maiipulator effectively calls
iosbase.setf(ios_base::
right, ios_base::
adjustfield), then returns
iosbase.
ios_base& scientific(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
scientific, ios_base::
floatfield), then returns
iosbase.
ios_base& showbase(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
showbase),
then returns iosbase.
ios_base& showpoint(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
showpoint), then returns
iosbase.
ios_base& showpos(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
showpos),
then returns iosbase.
ios_base& skipws(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
skipws),
then returns iosbase.
typedef T1 streamoff;
The type is a signed integer type T1 that describes an
object that can store a byte offset involved in various stream
positioning operations. Its representation has at least 32 value bits.
It is not necessarily large enough to represent an arbitrary
byte position within a stream. The value streamoff(-1)
generally indicates an erroneous offset.
typedef fpos streampos;
The type is a synonym for fpos.
typedef T2 streamsize;
The type is a signed integer type T3 that describes an
object that can store a count of the number of elements involved in
various stream operations. Its representation has at least 16 bits. It
is not necessarily large enough to represent an arbitrary byte
position within a stream.
ios_base& unitbuf(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
unitbuf),
then returns iosbase.
ios_base& uppercase(ios_base& iosbase);
The manipulator effectively calls
iosbase.setf(ios_base::
uppercase), then returns
iosbase.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
34 - iosfwd
<iosfwd>
Include the iostreams
standard header <iosfwd>
to declare forward references to several template classes used
throughout iostreams. All such template classes are defined in other
standard headers. You include this header explicitly only when
you need one of the above declarations, but not its definition.
// DECLARATIONS
typedef T1 streamoff;
typedef T2 streamsize;
typedef fpos streampos;
// CLASSES
class char_traits;
class ios;
class streambuf;
class istream;
class ostream;
class stringbuf;
class istringstream;
class ostringstream;
class filebuf;
class ifstream;
class ofstream;
// END OF DECLARATIONS
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
35 - iostrea2
<iostream.h>
Include the traditional header <iostream.h>
to effectively include the standard header
<iostream>.
#include <iostream>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
36 - iostream
<iostream>
Include the iostreams
standard header <iostream>
to declare objects that control reading from and writing to the
standard streams.
This is often the only header you
need include to perform input and output from a C++ program.
All the objects declared in this header share a peculiar
property -- you can assume they are
constructed before any
static objects you define, in a translation unit that includes
<iostreams>. Equally, you can assume that
these objects are not destroyed before the destructors for any
such static objects you define. (The output streams are, however,
flushed during program termination.)
Hence, you can safely read from
or write to the standard streams prior to program startup and
after program termination.
This guarantee is not universal, however. A static
constructor may call a function in another translation unit.
The called function cannot assume that the objects declared in
this header have been constructed, given the uncertain order
in which translation units participate in static construction.
To use these objects in such a context, you must first construct
an object of class
ios_base::Init,
as in:
#include <iostream>
void marker()
{ // called by some constructor
ios_base::Init unused_name;
cout << "called fun" << endl;
} // DECLARATIONS
extern istream cin;
extern ostream cout;
// END OF DECLARATIONSextern istream cin;
The object controls extractions from the
standard input
as a byte stream.
Once the object is constructed, the call
cin.tie() returns
&cout.
extern ostream cout;
The object controls insertions to the
standard output
as a byte stream.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
37 - istream
<istream>
Include the iostreams
standard header <istream>
to define class
istream,
which mediates extractions for the iostreams.
The header also defines a related
manipulator.
(This header is typically included for you by another
of the iostreams headers. You seldom have occasion to include it
directly.)
// DECLARATIONS
class istream;
// EXTRACTORS
istream&
operator>>(istream& istr, char *str);
istream&
operator>>(istream& istr, char& ch);
istream&
operator>>(istream& istr, signed char *str);
istream&
operator>>(istream& istr, signed char& ch);
istream&
operator>>(istream& istr, unsigned char *str);
istream&
operator>>(istream& istr, unsigned char& ch);
// MANIPULATORS
istream& ws(istream& istr);
// END OF DECLARATIONS
istream
· gcount
· get
· getline
· ignore
· operator>>
· peek
· putback
· read
· readsome
· seekg
· sentry
· sync
· tellg
· unget
class istream : public ios {
public:
explicit istream(streambuf *strbuf);
class sentry;
virtual ~istream();
istream& operator>>(
istream& (*pfn)(istream&));
istream& operator>>(
ios_base& (*pfn)(ios_base&));
istream& operator>>(
ios& (*pfn)(ios&));
istream& operator>>(
streambuf *strbuf);
istream& operator>>(bool& val);
istream& operator>>(short& val);
istream& operator>>(unsigned short& val);
istream& operator>>(int& val);
istream& operator>>(unsigned int& val);
istream& operator>>(long& val);
istream& operator>>(unsigned long& val);
istream& operator>>(void *& val);
istream& operator>>(float& val);
istream& operator>>(double& val);
istream& operator>>(long double& val);
streamsize gcount() const;
int_type get();
istream& get(char_type& ch);
istream& get(char_type *str, streamsize count);
istream&
get(char_type *str, streamsize count, char_type delim);
istream& get(streambuf& strbuf);
istream& get(streambuf& strbuf, char_type delim);
istream& getline(char_type *str, streamsize count);
istream& getline(char_type *str, streamsize count,
char_type delim);
istream& ignore(streamsize count = 1,
int_type delim = traits_type::eof());
int_type peek();
istream& read(char_type *str, streamsize count);
streamsize readsome(char_type *str, streamsize count);
istream& putback(char_type ch);
istream& unget();
pos_type tellg();
istream& seekg(pos_type pos);
istream& seekg(off_type off,
ios_base::seek_dir way);
int sync();
};The class describes an object that controls
extraction of elements and encoded objects from a
stream buffer
with elements of type char, also known as
char_type, whose
character traits are determined by the
class char_traits,
also known as
traits_type.
Most of the member functions that overload
operator>>
are formatted input functions.
They follow the pattern:
iostate state = goodbit;
const sentry ok(*this);
if (ok)
{try
{<extract elements and convert
accumulate flags in state
store a successful conversion> }
catch (...)
{try
{setstate(badbit); }
catch (...)
{}
if ((exceptions() & badbit) != 0)
throw; }}
setstate(state);
return (*this);Many other member functions are
unformatted input functions.
They follow the pattern:
iostate state = goodbit;
count = 0; // the value returned by gcount
const sentry ok(*this, true);
if (ok)
{try
{<extract elements and deliver
count extracted elements in count
accumulate flags in state> }
catch (...)
{try
{setstate(badbit); }
catch (...)
{}
if ((exceptions() & badbit) != 0)
throw; }}
setstate(state);Both groups of functions call
setstate(eofbit)
if they encounter end-of-file while extracting elements.
An object of class istream stores:
- a public base object of class
ios - an extraction count
for the last unformatted input operation (called
count
in the code above)
explicit istream(streambuf *strbuf);
The constructor initializes the base class by calling
init(strbuf).
It also stores zero in the
extraction count.
streamsize gcount() const;
The member function returns the
extraction count.
int_type get();
istream& get(char_type& ch);
istream& get(char_type *str, streamsize count);
istream& get(char_type *str, streamsize count,
char_type delim);
istream& get(streambuf& strbuf);
istream& get(streambuf& strbuf, char_type delim);The first of these
unformatted input functions
extracts an element, if possible, as if by returning
rdbuf()->sbumpc().
Otherwise, it returns
traits_type::eof().
If the function extracts no element, it calls
setstate(failbit).
The second function extracts the
int_type element
meta the same way. If meta compares equal to
traits_type::eof(),
the function calls
setstate(failbit).
Otherwise, it stores
traits_type::to_char_type(meta)
in ch. The function returns *this.
The third function returns get(str, count, widen('\n')).
The fourth function extracts up to count - 1 elements
and stores them in the array beginning at str. It always stores
char_type() after
any extracted elements it stores. In order of testing, extraction stops:
- at end of file
- after the function extracts an element that compares equal to
delim, in which case the element is put back
to the controlled sequence - after the function extracts
count - 1 elements
If the function extracts no elements, it calls
setstate(failbit).
In any case, it returns *this.
The fifth function returns get(strbuf, widen('\n')).
The sixth function extracts elements and inserts them in
strbuf. Extraction stops on end-of-file or on an element
that compares equal to delim (which is not extracted).
It also stops, without extracting the element in question,
if an insertion fails or throws an exception (which is caught
but not rethrown). If the function extracts no elements, it calls
setstate(failbit).
In any case, the function returns *this.
istream& getline(char_type *str, streamsize count);
istream& getline(char_type *str, streamsize count,
char_type delim);The first of these
unformatted input functions
returns getline(str, count, widen('\n')).
The second function extracts up to count - 1 elements
and stores them in the array beginning at str. It always stores
char_type() after
any extracted elements it stores. In order of testing, extraction stops:
- at end of file
- after the function extracts an element that compares equal to
delim, in which case the element is neither put back nor
appended to the controlled sequence - after the function extracts
count - 1 elements
If the function extracts no elements or count - 1 elements, it calls
setstate(failbit).
In any case, it returns *this.
istream& ignore(streamsize count = 1,
int_type delim = traits_type::eof());The unformatted input function
extracts up to count elements and discards them.
If count equals
INT_MAX,
however, it is taken as arbitrarily large.
Extraction stops early on end-of-file or
on an element ch such that
traits_type::to_int_type(ch)
compares equal to delim (which is also extracted).
The function returns *this.
istream& operator>>(
istream& (*pfn)(istream&));
istream& operator>>(
ios_base& (*pfn)(ios_base&));
istream& operator>>(
ios& (*pfn)(ios&));
istream& operator>>(
streambuf *strbuf);
istream& operator>>(bool& val);
istream& operator>>(short& val);
istream& operator>>(unsigned short& val);
istream& operator>>(int& val);
istream& operator>>(unsigned int& val);
istream& operator>>(long& val);
istream& operator>>(unsigned long& val);
istream& operator>>(void *& val);
istream& operator>>(float& val);
istream& operator>>(double& val);
istream& operator>>(long double& val);The first member function ensures that an expression of the
form istr >> ws calls
ws(istr), then returns *this.
The second and third functions ensure that other
manipulators,
such as hex behave
similarly. The remaining functions constitute the
formatted input functions.
The function:
istream& operator>>(
streambuf *strbuf);extracts elements, if strbuf is not a null pointer,
and inserts them in strbuf. Extraction stops on end-of-file.
It also stops, without extracting the element in question,
if an insertion fails or throws an exception (which is caught
but not rethrown).
If the function extracts no elements, it calls
setstate(failbit).
In any case, the function returns *this.
The function:
istream& operator>>(bool& val);
extracts a field and converts it to a boolean value.
The function endeavors to match a complete, nonempty
boolean input field.
If successful it converts
the boolean input field to a value of type bool
and stores that value in val.
A boolean input field takes one of two forms.
If flags() &
ios_base::boolalpha
is false, it is the same as an
integer input field, except that the
converted value must be either 0 (for false) or 1 (for true).
Otherwise, the sequence must match either
false (for false), or
true (for true).
The function returns *this.
The functions:
istream& operator>>(short& val);
istream& operator>>(unsigned short& val);
istream& operator>>(int& val);
istream& operator>>(unsigned int& val);
istream& operator>>(long& val);
istream& operator>>(unsigned long& val);
istream& operator>>(void *& val);
each extract a field and convert it to a numeric value.
Each function endeavors to match a complete, nonempty
integer input field.
If successful, it stores the result in val.
Otherwise, the function stores nothing in val and calls
setstate(ios_base::failbit).
If the function encounters end of file, it calls
setstate(ios_base::eofbit).
The integer input field is converted by the same rules used by the
scan functions
for matching and converting a series of char elements from a file.
The equivalent
scan conversion
specification is determined as follows:
- If
flags() &
ios_base::basefield ==
ios_base::oct, the
conversion specification is lo. - If
flags() & ios_base::basefield ==
ios_base::hex, the
conversion specification is lx. - If
flags() & ios_base::basefield == 0, the
conversion specification is li. - Otherwise, the conversion specification is
ld
if val has a signed type, lu if val
has an unsigned type, or p if val has type
void *.
If the converted value cannot
be represented as the type of val, the function calls
setstate(failbit).
In any case, the function returns *this.
The functions:
istream& operator>>(float& val);
istream& operator>>(double& val);
istream& operator>>(long double& val);
each extract a field and convert it to a numeric value.
Each function endeavors to match a complete, nonempty
A period (.) separates the integer digits from the
fraction digits.
The equivalent scan conversion specifier is f
if val has type float, lf if val
has type double, or Lf if val has type
long double.
If the converted value cannot
be represented as the type of val, the function calls
setstate(failbit).
In any case, it returns *this.
int_type peek();
The unformatted input function
extracts an element, if possible, as if by returning
rdbuf()->sgetc().
Otherwise, it returns
traits_type::eof().
istream& putback(char_type ch);
The unformatted input function
puts back ch, if possible, as if by calling
rdbuf()->sputbackc().
If rdbuf()
is a null pointer, or if the call to sputbackc returns
traits_type::eof(),
the function calls
setstate(badbit).
In any case, it returns *this.
istream& read(char_type *str, streamsize count);
The unformatted input function
extracts up to count elements
and stores them in the array beginning at str.
Extraction stops early on end-of-file, in which case the function calls
setstate(failbit).
In any case, it returns *this.
streamsize readsome(char_type *str, streamsize count);
The unformatted input function
extracts up to count elements
and stores them in the array beginning at str.
If good() is
false, the function calls
setstate(failbit).
Otherwise, it assigns the value of
rdbuf()->in_avail()
to N. If N < 0, the function calls
setstate(eofbit).
Otherwise, it replaces the value stored in N with
the smaller of count and N, then calls
read(str, N).
In any case, the function returns
gcount().
istream& seekg(pos_type pos);
istream& seekg(off_type off,
ios_base::seek_dir way);If fail() is false,
the first member function calls
newpos = rdbuf()->
pubseekpos(pos,
in),
for some pos_type temporary object newpos.
If fail() is false, the second function calls
newpos = rdbuf()->
pubseekoff(off, way,
in).
In either case, if (off_type)newpos == (off_type)(-1)
(the positioning operation fails) the function calls
istr.setstate(failbit).
Both functions return *this.
class sentry {
public:
explicit sentry(istream<Elem, Tr>& istr,
bool noskip = false);
operator bool() const;
};The nested class describes an object whose declaration structures the
formatted input functions and the
unformatted input functions.
If istr.good()
is true, the constructor:
- calls
istr.tie->
flush()
if istr.tie() is not a null pointer - effectively calls
ws(istr) if
istr.flags() &
skipws is nonzero
If, after any such preparation,
istr.good() is false, the constructor calls
istr.setstate(failbit).
In any case, the constructor stores the value returned by istr.good()
in status.
A later call to operator bool() delivers this stored value.
int sync();
If rdbuf() is
a null pointer, the function returns -1. Otherwise, it calls
rdbuf()->pubsync().
If that returns -1, the function calls
setstate(badbit)
and returns -1. Otherwise, the function returns zero.
pos_type tellg();
If fail() is false,
the member function returns
rdbuf()->
pubseekoff(0,
cur,
in).
Otherwise, it returns pos_type(-1).
istream& unget();
The unformatted input function
puts back the previous element in the stream, if possible, as if by calling
rdbuf()->sungetc().
If rdbuf()
is a null pointer, or if the call to sungetc returns
traits_type::eof(),
the function calls
setstate(badbit).
In any case, it returns *this.
istream&
operator>>(istream& istr, char *str);
istream&
operator>>(istream& istr, char& ch);
istream&
operator>>(istream& istr, signed char *str);
istream&
operator>>(istream& istr, signed char& ch);
istream&
operator>>(istream& istr, unsigned char *str);
istream&
operator>>(istream istr, unsigned char& ch);All of these functions are
formatted input functions.
The function:
istream&
operator>>(istream& istr, char *str);extracts up to N - 1 elements
and stores them in the array beginning at str.
If istr.width() is greater
than zero, N is istr.width(); otherwise it is
the size of
the largest array of char that can be declared.
The function always stores
char(0) after
any extracted elements it stores. Extraction stops early on end-of-file,
on a character with value char(0) (which is not extracted),
or on any element (which is not extracted) that would be discarded by
ws.
If the function extracts no elements, it calls
istr.setstate(failbit).
In any case, it calls istr.width(0) and
returns istr.
The function:
istream&
operator>>(istream& istr, char& ch);extracts an element, if possible, and stores it in ch.
Otherwise, it calls
is.setstate(failbit).
In any case, it returns istr.
The function:
istream&
operator>>(istream& istr, signed char *str);returns istr >> (char *)str.
The function:
istream&
operator>>(istream& istr, signed char& ch);returns istr >> (char&)ch.
The function:
istream&
operator>>(istream& istr, unsigned char *str);returns istr >> (char *)str.
The function:
istream&
operator>>(istream& istr, unsigned char& ch);returns istr >> (char&)ch.
istream& ws(istream& istr);
The manipulator extracts and discards any elements
ch for which
isspace(ch)
is true.
The function calls
setstate(eofbit)
if it encounters end-of-file while extracting elements.
It returns istr.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
38 - lib_cpp
C++ Library Overview
Using C++ Library Headers
· C++ Library Conventions
· Iostreams Conventions
· Program
Startup and Termination
· Exceptions
All C++ library entities are declared or defined in one or more
standard headers.
To make use of a library entity in a program, write an
include directive
that names the relevant standard header.
The full set of 28
C++ library headers
(along with the additional 15
Standard C headers)
constitutes a
hosted implementation
of Embedded C++:
<cassert>,
<cctype>,
<cerrno>,
<cfloat>,
<climits>,
<clocale>,
<cmath>,
<complex>,
<csetjmp>,
<csignal>,
<cstdarg>,
<cstddef>,
<cstdio>,
<cstdlib>,
<cstring>,
<ctime>,
<fstream>,
<iomanip>,
<ios>,
<iosfwd>,
<iostream>,
<istream>,
<new>,
<ostream>,
<sstream>,
<streambuf>,
<string>, and
<strstream>
A freestanding implementation
of the C++ library provides only a subset of these headers:
<cstddef>,
<cstdlib>
(declaring at least the functions
abort,
atexit, and
exit),
<new>, and
<cstdarg>.
The C++ library headers also have a broader subdivision --
iostreams headers.
You include the contents of a standard header by naming it in an
include directive,
as in:
#include <iostream> /* include I/O facilities */
You can include the standard headers in any order, a standard
header more than once, or two or more standard headers that define
the same macro or the same type.
Do not include a standard header within a declaration. Do not
define macros that have the same names as keywords before you include
a standard header.
A C++ library header includes any other C++ library headers
it needs to define needed types. (Always include explicitly any
C++ library headers needed in a translation unit, however, lest
you guess wrong about its actual dependencies.) A Standard C header
never includes another standard header. A standard header declares
or defines only the entities described for it in this document.
Every function in the library is declared in a standard header.
Unlike in Standard C, the standard header never provides a
masking macro,
with the same name as the function, that masks the function
declaration and achieves the same effect.
The C++ Standard requires that nearly all names
in the C++ library headers be defined in the
std namespace,
or in a namespace
nested within the std namespace.
Otherwise, all names are defined in the global namespace.
In this implementation,
however, you can ignore namespaces.
The C++ library obeys much the same
conventions
as the Standard C library, plus a few more outlined here.
An implementation has certain latitude in how it declares types
and functions in the C++ library:
- Names of functions in the Standard C library may have either
extern "C++" or
extern "C" linkage.
Include the appropriate
Standard C header
rather than declare a library entity inline. - A member function name in a library class may have additional
function signatures over those listed in this document. You can
be sure that a function call described here behaves as expected,
but you cannot reliably take the address of a library member function.
(The type may not be what you expect.)
- A library class may have undocumented (non-virtual) base classes.
A class documented as derived from another class may, in fact,
be derived from that class through other undocumented classes.
- A type defined as a synonym for some integer type may be the
same as one of several different integer types.
- A bitmask type can
be implemented as either an integer type or an enumeration.
In either case, you can perform bitwise operations (such as AND
and OR) on values of the same bitmask type. The elements
A and B of a bitmask type are nonzero
values such that A & B is zero. - A library function that has no exception specification can
throw an arbitrary exception, unless its definition clearly
restricts such a possibility.
On the other hand, there are some restrictions you can count on:
- The Standard C library uses no
masking macros. Only specific function
signatures are reserved, not the names of the functions themselves.
- A library function name outside a class will not have
additional, undocumented, function signatures. You can reliably
take its address.
- Base classes and member functions described as virtual are
assuredly virtual, while those described as non-virtual are
assuredly non-virtual.
- Two types defined by the C++ library
are always different unless this document explicitly suggests
otherwise.
- Functions supplied by the library, including the default versions of
replaceable functions,
can throw at most those exceptions listed in any exception
specification.
No destructors supplied by the library throw exceptions.
Functions in the
Standard C library
may propagate an exception, as when
qsort calls a comparison
function that throws an exception, but they do not otherwise throw
exceptions.
The iostreams headers support conversions
between text and encoded forms, and input and output to external
files:
<fstream>,
<iomanip>,
<ios>,
<iosfwd>,
<iostream>,
<istream>,
<ostream>,
<sstream>,
<streambuf>, and
<strstream>.
The simplest use of iostreams requires only that you include
the header <iostream>. You can then extract values from
cin, to read the
standard input.
The rules for doing so are outlined in the description of the class
istream.
You can also insert values to
cout, to write the
standard output.
The rules for doing so are outlined in the description of the class
ostream.
Format control common to both extractors and insertors is managed
by the class ios.
Manipulating this format information in the guise of extracting and
inserting objects is the province of several
manipulators.
You can perform the same iostreams operations on files that you
open by name, using the classes declared in
<fstream>.
To convert between iostreams and objects of class
string,
use the classes declared in <sstream>.
And to do the same with C strings,
use the classes declared in <strstream>.
The remaining headers provide support services, typically of direct
interest to only the most advanced users of the iostreams classes.
A C++ program performs the same operations as does a C program
program startup and at
program termination,
plus a few more outlined here.
Before the target environment calls the function
main, and after it stores
any constant initial values you specify in all objects that have
static duration, the program executes any remaining constructors
for such static objects. The order of execution is not specified
between translation units, but you can nevertheless assume that some
iostreams objects are properly initialized
for use by these static constructors. These control
text streams:
You can also use these objects within the destructors called for
static objects, during
program termination.
As with C, returning
from main or calling
exit
calls all functions registered with
atexit
in reverse order of registry.
In this implementation,
exception handling can be either enabled or disabled.
This document describes all behavior as if exception handling is enabled.
If exception handling is disabled, however:
- Throw specifications in library function declarations
are not actually present.
- Catch clauses in library function definitions likewise are not
actually present. It is not possible for the program to catch an
exception, except in the limited sense outlined below. Hence, the
library has no occasion to rethrow an exception.
- Rather than throw an exception, as in
throw ex, the library
actually calls ex._Raise().
Here, void _Raise()
is a member function of class exception,
the base class for all exceptions thrown by the library. It performs the following
operations, in order:
- If a raise handler
has been registered by an earlier call to the static member function
exception::
_Set_raise_handler(void
(*)(const exception&), then _Raise calls the
raise handler. _Raise then calls the protected virtual member function
void _Doraise(), which typically calls
_Throw(*this) in any class derived
from exception. (This ensures that the most derived version
of the virtual public member function what gets called
by _Throw, as outlined below.)_Raise then calls _Throw(*this).
The replaceable global function
void _Throw(const exception& ex)
never returns to its caller.
If the pointer returned by ex.what() is not a null pointer,
the function writes to the
standard error output stream
a diagnostic message that includes the
null-terminated string
designated by the pointer. In any event, the function then calls
abort.
The net effect of all this machinery is to supply several levels of control,
in lieu of the normal exception-handling machinery:
- You can dynamically specify a raise handler that is called whenever the
library would normally throw any exception
derived from class
exception. - You can override
_Doraise, in a class you derive
from exception, to get control whenever an object of that
class would normally be thrown by the library (assuming that any raise handler
you register returns to its caller). - You can define your own version of
_Throw, to statically handle
termination on all thrown exceptions as you see fit.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
39 - lib_file
Files and Streams
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of the C library:
the Green Hills Software C Library.
For documentation pertaining to it,
please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
40 - lib_over
C Library Overview
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of the C library:
the Green Hills Software C Library.
For documentation pertaining to it,
please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
41 - lib_prin
Formatted Output
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of the C library:
the Green Hills Software C Library.
For documentation pertaining to it,
please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
42 - lib_scan
Formatted Input
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of the C library:
the Green Hills Software C Library.
For documentation pertaining to it,
please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
43 - limits
<limits.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
44 - locale
<locale.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
45 - math
<math.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
46 - new
<new>
Include the standard header <new>
to define several types and functions that control allocation and
freeing of storage under program control.
Some of the functions declared in this header are
replaceable.
The implementation supplies a default version, whose behavior is
described in this document. A program can, however, define a
function with the same signature to replace the default version
at link time. The replacement version must satisfy the requirements
described in this document.
// DECLARATIONS
typedef void (*new_handler)();
class bad_alloc;
class nothrow_t;
extern const nothrow_t nothrow;
// FUNCTIONS
new_handler set_new_handler(new_handler pnew) throw();
// OPERATORS
void operator delete(void *ptr) throw(); // REPLACEABLE
void operator delete(void *, void *) throw();
void operator delete(void *ptr, // REPLACEABLE
const nothrow_t&) throw();
void operator delete[](void *ptr) throw(); // REPLACEABLE
void operator delete[](void *, void *) throw();
void operator delete[](void *ptr, // REPLACEABLE
const nothrow_t&) throw();
void *operator new(size_t count) // REPLACEABLE
throw(bad_alloc);
void *operator new(size_t count, // REPLACEABLE
const nothrow_t&) throw();
void *operator new(size_t count, void *ptr) throw();
void *operator new[](size_t count) // REPLACEABLE
throw(bad_alloc);
void *operator new[](size_t count, // REPLACEABLE
const nothrow_t&) throw();
void *operator new[](size_t count,
void *ptr) throw();
// END OF DECLARATIONSclass bad_alloc : public exception {
};The class describes an exception thrown to indicate that
an allocation request did not succeed. The value returned by
what()
is an implementation-defined
C string.
None of the member functions throw any exceptions.
typedef void (*new_handler)();
The type describes a pointer object that
designates a function suitable for use as a
new handler.
extern const nothrow_t nothrow;
The object is used as a function argument to
match the parameter type
nothrow_t.
class nothrow_t {};The class is used as a function parameter to
operator new to indicate that the function should
return a null pointer to report an allocation failure,
rather than throw an exception.
void operator delete(void *ptr) throw(); // REPLACEABLE
void operator delete(void *, void *) throw();
void operator delete(void *ptr, // REPLACEABLE
const nothrow_t&) throw();The first function is called by a
delete expression
to render the value of ptr invalid.
The program can define a function with this function signature that
replaces
the default version defined by the
Standard C++ library. The required behavior is to accept a value of
ptr that is null or that was returned by an earlier call to
operator new(size_t).
The default behavior for a null value of ptr is
to do nothing. Any other value of ptr must be a value returned
earlier by a call as described above.
The default behavior for such a non-null value of ptr is to
reclaim storage allocated by the earlier call.
It is unspecified under what conditions part or all
of such reclaimed storage is allocated by a subsequent call to
operator new(size_t),
or to any of
calloc(size_t),
malloc(size_t), or
realloc(void*, size_t).
The second function is called by a
placement
delete expression corresponding to a
new expression
of the form
new(size_t).
It does nothing.
The third function is called by a placement
delete expression corresponding to a
new expression of the form
new(size_t, const nothrow_t&).
The program can define a function with this function signature that
replaces
the default version defined by the
Standard C++ library. The required behavior is to accept a value of
ptr that is null or that was returned by an earlier call to
operator new(size_t).
The default behavior is to evaluate delete(ptr).
void operator delete[](void *ptr) throw(); // REPLACEABLE
void operator delete[](void *, void *) throw();
void operator delete[](void *ptr, // REPLACEABLE
const nothrow_t&) throw();The first function is called by a
delete[] expression
to render the value of ptr invalid.
The program can define a function with this function signature that
replaces
the default version defined by the
Standard C++ library.
The required behavior is to accept a value of ptr
that is null or that was returned by an earlier call to
operator new[](size_t).
The default behavior is to evaluate delete(ptr).
The second function is called by a
placement
delete[] expression corresponding to a
new[] expression of the form
new[](size_t).
It does nothing.
The third function is called by a placement
delete expression corresponding to a
new[] expression of the form
new[](size_t, const nothrow_t&).
The program can define a function with this function signature that
replaces
the default version defined by the
Standard C++ library. The required behavior is to accept a value of
ptr that is null or that was returned by an earlier call to
operator new[](size_t).
The default behavior is to call
operator delete(ptr, nothrow).
void *operator new(size_t count) throw(bad_alloc); // REPLACEABLE
void *operator new(size_t count, const nothrow_t&) throw(); // REPLACEABLE
void *operator new(size_t count, void *ptr) throw();
The first function is called by a
new expression
to allocate count bytes of storage
suitably aligned to represent any object of that size.
The program can define a function with this function signature that
replaces
the default version defined by the Standard C++ library.
The required behavior is to return a non-null pointer only
if storage can be allocated as requested. Each such allocation
yields a pointer to storage disjoint from any other allocated storage.
The order and contiguity of storage allocated by successive calls
is unspecified. The initial stored value is unspecified.
The returned pointer designates the start (lowest
byte address) of the allocated storage. If count is zero, the
value returned does not compare equal to any other value returned
by the function.
The default behavior is to execute a loop. Within the loop,
the function first attempts to allocate the requested storage. Whether
the attempt involves a call to
malloc(size_t)
is unspecified. If the attempt is successful, the function returns
a pointer to the allocated storage.
Otherwise, the function calls the designated
new handler. If the
called function returns, the loop repeats. The loop terminates when
an attempt to allocate the requested storage is successful or when
a called function does not return.
The required behavior of a
new handler
is to perform one of the following operations:
- make more storage available for allocation and then return
- call either
abort() or
exit(int) - throw an object of type
bad_alloc
The default behavior of a
new handler is to throw an object of type
bad_alloc. A null pointer designates the default
new handler.
The order and contiguity of storage allocated by successive
calls to operator new(size_t) is unspecified,
as are the initial values stored there.
The second function:
void *operator new(size_t count,
const nothrow_t&) throw();is called by a
placement
new expression
to allocate count bytes of storage
suitably aligned to represent any object of that size.
The program can define a function with this function signature that
replaces
the default version defined by the Standard C++ library.
The default behavior is to return
operator new(count) if that
function succeeds. Otherwise, it returns a null pointer.
The third function:
void *operator new(size_t count, void *ptr) throw();
is called by a
placement new expression,
of the form new (args) T.
Here, args consists of a single object pointer.
The function returns ptr.
void *operator new[](size_t count) throw(bad_alloc); // REPLACEABLE
void *operator new[](size_t count, // REPLACEABLE
const nothrow_t&) throw();
void *operator new[](size_t count, void *ptr) throw();The first function is called by a
new[] expression
to allocate count bytes of storage
suitably aligned to represent any array object of
that size or smaller. The program can define a function
with this function signature that
replaces
the default version defined by the Standard C++ library.
The required behavior is the same as for
operator new(size_t).
The default behavior is to return
operator new(count).
The second function is called by a
placement
new[] expression
to allocate count bytes of storage
suitably aligned to represent any array object of that size.
The program can define a function with this function signature that
replaces
the default version defined by the Standard C++ library.
The default behavior is to return
operator new(count) if that
function succeeds. Otherwise, it returns a null pointer.
The third function is called by a
placement
new[] expression,
of the form new (args) T[N].
Here, args consists of a single object pointer.
The function returns ptr.
new_handler set_new_handler(new_handler pnew) throw();
The function stores pnew in a static
new handler pointer
that it maintains, then returns the value previously
stored in the pointer. The new handler is used by
operator new(size_t).
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
47 - new2
<new.h>
Include the traditional header <new.h>
to effectively include the standard header
<new>.
#include <new>
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
48 - ostream
<ostream>
// DECLARATIONS
class ostream;
// INSERTERS
ostream&
operator<<(ostream& ostr, const char *str);
ostream&
operator<<(ostream& ostr, char ch);
ostream&
operator<<(ostream& ostr, const signed char *str);
ostream&
operator<<(ostream& ostr, signed char ch);
ostream&
operator<<(ostream& ostr, const unsigned char *str);
ostream&
operator<<(ostream& ostr, unsigned char ch);
// MANIPULATORS
ostream& endl(ostream& ostr);
ostream& ends(ostream& ostr);
ostream& flush(ostream& ostr);
// END OF DECLARATIONSInclude the iostreams
standard header <ostream> to define
class ostream,
which mediates insertions for the iostreams.
The header also defines several related
manipulators.
(This header is typically included for you by another
of the iostreams headers. You seldom have occasion to include it
directly.)
ostream
· flush
· operator<<
· put
· seekp
· sentry
· tellp
· write
class ostream : public ios {
public:
explicit ostream(streambuf *strbuf);
class sentry;
virtual ~ostream();
ostream& operator<<(
ostream& (*pfn)(ostream&));
ostream& operator<<(
ios_base;& (*pfn)(ios_base&));
ostream& operator<<(
ios& (*pfn)(ios&));
ostream& operator<<(
streambuf *strbuf);
ostream& operator<<(bool val);
ostream& operator<<(short val);
ostream& operator<<(unsigned short val);
ostream& operator<<(int val);
ostream& operator<<(unsigned int val);
ostream& operator<<(long val);
ostream& operator<<(unsigned long val);
ostream& operator<<(float val);
ostream& operator<<(double val);
ostream& operator<<(long double val);
ostream& operator<<(const void *val);
ostream& put(char_type ch);
ostream& write(char_type *str, streamsize count);
ostream& flush();
pos_type tellp();
ostream& seekp(pos_type pos);
ostream& seekp(off_type off,
ios_base::seek_dir way);
};The class describes an object that controls
insertion of elements and encoded objects into a
stream buffer
with elements of type char, also known as
char_type, whose
character traits are determined by the
class char_traits,
also known as
traits_type.
Most of the member functions that overload
operator<<
are formatted output functions.
They follow the pattern:
iostate state = goodbit;
const sentry ok(*this);
if (ok)
{try
{<convert and insert elements
accumulate flags in state> }
catch (...)
{try
{setstate(badbit); }
catch (...)
{}
if ((exceptions() & badbit) != 0)
throw; }}
width(0); // except for operator<<(Elem)
setstate(state);
return (*this);Two other member functions are
unformatted output functions.
They follow the pattern:
iostate state = goodbit;
const sentry ok(*this);
if (!ok)
state |= badbit;
else
{try
{<obtain and insert elements
accumulate flags in state> }
catch (...)
{try
{setstate(badbit); }
catch (...)
{}
if ((exceptions() & badbit) != 0)
throw; }}
setstate(state);
return (*this);Both groups of functions call
setstate(badbit)
if they encounter a failure while inserting elements.
An object of class ostream stores only
a public base object of class
ios
explicit ostream(streambuf *strbuf);
The constructor initializes the base class by calling
init(strbuf).
ostream& flush();
If rdbuf() is
not a null pointer, the function calls
rdbuf()->pubsync().
If that returns -1, the function calls
setstate(badbit).
It returns *this.
ostream& operator<<(
ostream& (*pfn)(ostream&));
ostream& operator<<(
ios_base& (*pfn)(ios_base&));
ostream& operator<<(
ios& (*pfn)(ios&));
ostream& operator<<(
streambuf *strbuf);
ostream& operator<<(bool val);
ostream& operator<<(short val);
ostream& operator<<(unsigned short val);
ostream& operator<<(int val);
ostream& operator<<(unsigned int val);
ostream& operator<<(long val);
ostream& operator<<(unsigned long val);
ostream& operator<<(float val);
ostream& operator<<(double val);
ostream& operator<<(long double val);
ostream& operator<<(const void *val);The first member function ensures that an expression of the
form ostr << endl calls
endl(ostr), then returns *this.
The second and third functions ensure that other
manipulators,
such as hex behave
similarly. The remaining functions are all
formatted output functions.
The function:
ostream& operator<<(
streambuf *strbuf);extracts elements from strbuf,
if strbuf is not a null pointer, and inserts them.
If strbuf is a null pointer, the function calls
setstate(badbit).
Otherwise, extraction stops on end-of-file,
or if an extraction throws an exception (which is rethrown).
It also stops, without extracting the element in question,
if an insertion fails. If the function inserts no elements, or
if an extraction throws an exception, the function calls
setstate(failbit).
In any case, the function returns *this.
All the remaining functions generate an output field and insert it.
The output output field is generated by the same rules used by the
print functions
for generating a series of char elements to a file.
Where a print function pads a field with either spaces or the digit
0, however, the function instead uses
fill.
The equivalent
print conversion
specification is determined as described for each function below.
Padding occurs only if
the minimum number of elements N required to
specify the output field is less than
width().
Such padding consists of a sequence of N - width() copies of
fill().
Padding then occurs as follows:
- If
flags() &
ios_base::adjustfield ==
ios_base::left,
the flag - is prepended to the conversion specification.
(Padding occurs after the generated text.) - If
flags() & ios_base::adjustfield ==
ios_base::internal,
the flag 0 is prepended. (For a numeric output field,
padding occurs where the print functions pad with 0.) - Otherwise, no additional flag is prepended.
(Padding occurs before the generated sequence.)
The function:
ostream& operator<<(bool val);
converts val to a
boolean output field
and inserts it as an array of char, with
a conversion specifier of s.
A boolean output field takes one of two forms.
If flags() &
ios_base::boolalpha
is false, the generated sequence is either 0 (for false)
or 1 (for true).
Otherwise, the generated sequence is either
false (for false), or
true (for true). The
function then calls width(0) to reset the
field width to zero.
The function returns *this.
The functions:
ostream& operator<<(short val);
ostream& operator<<(unsigned short val);
ostream& operator<<(int val);
ostream& operator<<(unsigned int val);
ostream& operator<<(long val);
ostream& operator<<(unsigned long val);
ostream& operator<<(const void *val);
each convert val to an
integer output field
and inserts it. The equivalent
print conversion
specification is determined as follows:
- If
flags() &
ios_base::basefield ==
ios_base::oct, the
conversion specification is lo and the converted value is
(long)val. - If
flags() & ios_base::basefield ==
ios_base::hex, the
conversion specification is lx and the converted value is
(unsigned long)val. - Otherwise, the conversion specification is
ld
and the converted value is (long)val.
If width()
is nonzero, a field width of this value is prepended. The
function then calls width(0) to reset the
field width to zero.
Finally:
- If
flags() &
ios_base::showpos
is nonzero, the flag + is prepended to the conversion
specification. - If
flags() &
ios_base::showbase
is nonzero, the flag # is prepended to the conversion
specification.
The function returns *this.
The functions:
ostream& operator<<(float val);
ostream& operator<<(double val);
ostream& operator<<(long double val);
each convert val to a
floating-point output field
and insert it.
A period (.) separates the integer digits from the
fraction digits.
The equivalent print conversion specification is determined as follows:
- If
flags() &
ios_base::floatfield ==
ios_base::fixed, the
conversion specification is f. - If
flags() & ios_base::floatfield ==
ios_base::scientific, the
conversion specification is e.
If flags() &
ios_base::uppercase
is nonzero, e is replaced with E. - Otherwise, the conversion specification is
g.
If flags() & ios_base::uppercase
is nonzero, g is replaced with G.
If val has type double, the function prepends l
to the conversion specification. If val has type long double,
it prepends L to the conversion specification.
If flags() & ios_base::fixed is nonzero, or if
precision()
is greater than zero, a precision with the value
precision() is prepended to the conversion specification.
Any padding behaves the same
as for an integer output field.
If width()
is nonzero, a field width of this value is prepended. The
function then calls width(0) to reset the
field width to zero. Finally:
- If
flags() &
ios_base::showpos
is nonzero, the flag + is prepended to the conversion
specification. - If
flags() &
ios_base::showpoint
is nonzero, the flag # is prepended to the conversion
specification.
ostream& put(char_type ch);
The unformatted output function
inserts the element ch. It returns *this.
ostream& seekp(pos_type pos);
ostream& seekp(off_type off,
ios_base::seek_dir way);If fail() is false,
the first member function calls
newpos = rdbuf()->
pubseekpos(pos,
out),
for some pos_type temporary object newpos.
If fail() is false, the second function calls
newpos = rdbuf()->
pubseekoff(off, way,
out).
In either case, if (off_type)newpos == (off_type)(-1)
(the positioning operation fails) the function calls
istr.setstate(failbit).
Both functions return *this.
class sentry {
public:
explicit sentry(ostream& ostr);
operator bool() const;
~sentry();
private:
sentry(const sentry&); // not defined
sentry& operator=(const sentry&); // not defined
bool status;
};The nested class describes an object whose declaration structures the
formatted output functions
and the
unformatted output functions.
If ostr.good() is true, and
ostr.tie() is not
a null pointer, the constructor calls
ostr.tie->flush().
The constructor then stores the value returned by ostr.good()
in status.
A later call to operator bool() delivers this stored value.
If
flags() &
unitbuf is nonzero,
the destructor calls
flush().
pos_type tellp();
If fail() is false,
the member function returns
rdbuf()->
pubseekoff(0,
cur,
in).
Otherwise, it returns pos_type(-1).
ostream& write(const char_type *str, streamsize count);
The unformatted output function
inserts the sequence of count elements
beginning at str.
ostream endl(ostream& ostr);
The manipulator calls
ostr.put(ostr.
widen('\n')),
then calls
ostr.flush().
It returns ostr.
ostream& ends(ostream& ostr);
The manipulator calls
ostr.put(Elem('\0')).
It returns ostr.
ostream& flush(ostream& ostr);
The manipulator calls
ostr.flush().
It returns ostr.
ostream&
operator<<(ostream& ostr, const char *str);
ostream&
operator<<(ostream& ostr, char ch);
ostream&
operator<<(ostream& ostr, const signed char *str);
ostream&
operator<<(ostream& ostr, signed char ch);
ostream&
operator<<(ostream& ostr, const unsigned char *str);
ostream&
operator<<(ostream& ostr, unsigned char ch);All of these functions are
formatted output functions.
The function:
ostream&
operator<<(ostream& ostr, const char *str);determines the length N =
traits_type::length(str)
of the sequence beginning at str, and inserts the sequence. If
N < ostr.width(),
then the function also inserts a repetition of ostr.width() - N
fill characters.
The repetition precedes the sequence if
(ostr.flags() &
adjustfield !=
left.
Otherwise, the repetition follows the sequence.
The function returns ostr.
The function:
ostream&
operator<<(ostream& ostr, char ch);inserts the element ch. If
1 < ostr.width(),
then the function also inserts a repetition of ostr.width() - 1
fill characters.
The repetition precedes the sequence if
(ostr.flags() &
adjustfield !=
left.
Otherwise, the repetition follows the sequence.
It returns ostr.
The function:
ostream&
operator<<(ostream& ostr, const signed char *str);returns ostr << (const char *)str.
The function:
ostream&
operator<<(ostream& ostr, signed char ch);returns ostr << (char)ch.
The function:
ostream&
operator<<(ostream& ostr, const unsigned char *str);returns ostr << (const char *)str.
The function:
ostream&
operator<<(ostream& ostr, unsigned char ch);returns ostr << (char)ch.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
49 - preproc
Preprocessing
The translator processes each source file in a series of phases.
Preprocessing constitutes the earliest phases, which produce a
translation unit.
Preprocessing treats a source file as a sequence of
text lines. You can specify
directives and
macros
that insert, delete, and alter source text.
This document describes briefly just those aspects
of preprocessing most relevant to the use of the Standard C library:
The macro __FILE__
expands to a
string literal
that gives the remembered
filename
of the current source file. You can alter the value of this macro
by writing a
line directive.
The macro __LINE__
expands to a decimal integer constant
that gives the remembered line number within the current source file.
You can alter the value of this macro by writing a
line directive.
A define directive
defines a name as a macro.
Following the directive name define,
you write one of two forms:
- a name not immediately followed by a left parenthesis,
followed by any sequence of preprocessing tokens -- to define a
macro without parameters
- a name immediately followed by a left parenthesis with no
intervening white space, followed by zero or more distinct parameter
names separated by commas, followed by a right parenthesis, followed
by any sequence of preprocessing tokens -- to define a macro with
as many parameters as names that you write inside the parentheses
You can selectively skip groups of lines
within source files by writing an
if directive,
or one of the other conditional directives,
ifdef or ifndef.
You follow the conditional directive by the first group of lines
that you want to selectively skip.
Zero or more elif directives follow this first group of lines,
each followed by a group of lines that you want to selectively skip.
An optional else directive follows all groups of lines controlled
by elif directives, followed by the last group of lines you want
to selectively skip.
The last group of lines ends with an endif directive.
At most one group of lines is retained in the translation unit --
the one immediately preceded by a directive whose
#if expression has a nonzero value.
For the directive:
#ifdef X
this expression is defined (X), and for the directive:
#ifndef X
this expression is !defined (X).
A #if expression is a
conditional expression that the preprocessor evaluates.
You can write only
integer constant expressions, with the following
additional considerations:
- The expression
defined X, or defined (X),
is replaced by 1 if X is defined as a macro, otherwise 0. - You cannot write the
sizeof
or type cast operators. (The translator expands all macro
names, then replaces each remaining name with 0,
before it recognizes keywords.)
- The translator may be able to represent a broader range of integers
than the target environment.
- The translator represents type int the same as long,
and unsigned int the same as unsigned long.
- The translator can translate character constants to a set of
code values different from the set for the target environment.
An include directive
includes the contents of a
standard header
or another source file in a translation unit. The contents of
the specified standard header or source file replace the include
directive. Following the directive name include,
write one of the following:
- a standard header name between angle brackets
- a filename between double quotes
- any other form that expands to one of the two previous forms
after macro replacement
A line directive alters
the source line number and filename used by the predefined macros
__FILE__ and
__FILE__.
Following the directive name line,
write one of the following:
- a decimal integer (giving the new line number of the line following)
- a decimal integer as before, followed by a string literal (giving
the new line number and the new source filename)
- any other form that expands to one of the two previous forms
after macro replacement
Preprocessing translates each source file in a series of distinct
phases.
The first few phases of translation:
terminate each line with a newline character (NL),
convert trigraphs to their single-character equivalents,
and concatenate each line ending in a backslash (\)
with the line following. Later phases process
include directives,
expand macros, and so on to produce a
translation unit.
The translator combines separate translation units,
with contributions as needed from the
Standard C library, at
link time, to form the executable
program.
An undef directive
removes a macro definition. You might want to
remove a macro definition so that you can define it differently with
a define directive or to unmask any other meaning given to
the name. The name whose definition you want to remove
follows the directive name undef.
If the name is not currently defined as a macro,
the undef directive has no effect.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
50 - setjmp
<setjmp.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
51 - signal
<signal.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
52 - sstream
<sstream>
Include the iostreams
standard header <sstream>
to define several classes that support
iostreams operations on
sequences stored in an allocated array object.
Such sequences are easily converted to and from objects of
class
string.
// DECLARATIONS
class stringbuf;
class istringstream;
class ostringstream;
// END OF DECLARATIONSclass stringbuf : public streambuf {
public:
stringbuf(ios_base::openmode mode =
ios_base::in | ios_base::out);
stringbuf(const string& str,
ios_base::openmode mode =
ios_base::in | ios_base::out);
string str() const;
void str(const string& newstr);
protected:
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode mode =
ios_base::in | ios_base::out);
virtual pos_type seekpos(pos_type sp,
ios_base::openmode mode =
ios_base::in | ios_base::out);
virtual int_type underflow();
virtual int_type pbackfail(int_type meta =
traits_type::eof());
virtual int_type overflow(int_type meta =
traits_type::eof());
};The class
describes a stream buffer that controls
the transmission of elements
to and from a sequence of elements
stored in an array object. The object is allocated, extended, and
freed as necessary to accommodate changes in the sequence.
An object of class
stringbuf
stores a copy of the
ios_base::openmode
argument from its constructor as its
stringbuf mode mode:
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
stringbuf(ios_base::openmode mode =
ios_base::in | ios_base::out);
stringbuf(const string& str,
ios_base::openmode mode =
ios_base::in | ios_base::out);The first constructor stores a null pointer in all the pointers
controlling the
input buffer and the
output buffer. It
also stores mode as the
stringbuf mode.
The second constructor allocates a copy of the sequence controlled
by the string object str.
If mode & ios_base::in is nonzero,
it sets the input buffer to begin reading
at the start of the sequence.
If mode & ios_base::out is nonzero,
it sets the output buffer to begin
writing at the start of the sequence.
It also stores mode as the
stringbuf mode.
typedef char char_type;
The type is a synonym for char.
typedef traits_type::int_type int_type;
The type is a synonym for
traits_type::int_type.
typedef traits_type::off_type off_type;
The type is a synonym for
traits_type::off_type.
virtual int_type overflow(int_type meta =
traits_type::eof());If meta does not compare equal to
traits_type::eof(),
the protected virtual member function endeavors to insert the element
traits_type::to_char_type(meta)
into the
output buffer.
It can do so in various ways:
- If a write position
is available, it can store the element into the write position
and increment the next pointer for the output buffer.
- It can make a write position available by allocating
new or additional storage for the output buffer. (Extending the
output buffer this way also extends any associated
input buffer.)
If the function cannot succeed, it returns traits_type::eof().
Otherwise, it returns
traits_type::not_eof(meta).
virtual int_type pbackfail(int_type meta =
traits_type::eof());The protected virtual member function endeavors to put back an element
into the
input buffer,
then make it the current element (pointed to
by the next pointer).
If meta compares equal to
traits_type::eof(),
the element to push back is effectively the one already in the stream
before the current element. Otherwise, that element is replaced by
byte =
traits_type::to_char_type(meta).
The function can put back an element in various ways:
- If a putback position
is available, and the element stored there compares equal to
byte,
it can simply decrement the next pointer for the input buffer. - If a putback position is available,
and if the stringbuf mode permits
the sequence to be altered (
mode &
ios_base::out is nonzero),
it can store byte into the putback position and decrement the
next pointer for the input buffer.
If the function cannot succeed, it returns
traits_type::eof(). Otherwise, it returns
traits_type::not_eof(meta).
typedef traits_type::pos_type pos_type;
The type is a synonym for
traits_type::pos_type.
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode mode =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
stringbuf,
a stream position consists
purely of a stream offset. Offset zero designates the first element
of the controlled sequence.
The new position is determined as follows:
- If
way ==
ios_base::beg,
the new position is the beginning of the stream plus off. - If
way ==
ios_base::cur,
the new position is the current stream position plus off. - If
way ==
ios_base::end,
the new position is the end of the stream plus off.
If
mode & ios_base::in is nonzero,
the function alters the next position to read in the
input buffer.
If mode & ios_base::out is nonzero,
the function alters the next position to write in the
output buffer.
For a stream to be affected, its buffer must exist.
For a positioning operation to succeed, the resulting
stream position must lie within the controlled sequence.
If the function affects both stream positions, way
must be ios_base::beg or ios_base::end
and both streams are positioned at the same element.
Otherwise (or if neither position is affected) the positioning
operation fails.
If the function succeeds in altering either or both of the stream positions,
it returns the resultant stream position.
Otherwise, it fails and returns an invalid stream position.
virtual pos_type seekpos(pos_type sp,
ios_base::openmode mode =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
stringbuf,
a stream position consists
purely of a stream offset. Offset zero designates the first element
of the controlled sequence. The new position is determined
by sp.
If
mode & ios_base::in is nonzero,
the function alters the next position to read in the
input buffer.
If mode & ios_base::out is nonzero,
the function alters the next position to write in the
output buffer.
For a stream to be affected, its buffer must exist.
For a positioning operation to succeed, the resulting
stream position must lie within the controlled sequence.
Otherwise (or if neither position is affected) the positioning
operation fails.
If the function succeeds in altering either or both of the stream positions,
it returns the resultant stream position.
Otherwise, it fails and returns an invalid stream position.
string str() const;
void str(const string& newstr);
The first member function returns an object of class
string,
whose controlled sequence is a copy of the sequence controlled
by *this. The sequence copied depends on the stored
stringbuf mode mode:
- If
mode &
ios_base::out is nonzero
and an output buffer exists,
the sequence is the entire output buffer
(epptr() -
pbase()
elements beginning with pbase()). - Otherwise, if
mode &
ios_base::in is nonzero
and an input buffer exists,
the sequence is the entire input buffer
(egptr() -
eback()
elements beginning with eback()). - Otherwise, the copied sequence is empty.
The second member function deallocates any sequence currently
controlled by *this. It then
allocates a copy of the sequence controlled
by newstr. If mode & ios_base::in is nonzero,
it sets the input buffer to begin reading
at the beginning of the sequence.
If mode & ios_base::out is nonzero,
it sets the output buffer to begin
writing at the beginning of the sequence.
typedef char_traits traits_type;
The type is a synonym for
char_traits.
virtual int_type underflow();
The protected virtual member function endeavors to extract the current
element byte from the
input buffer,
then advance the current stream position, and return the element as
traits_type::to_int_type(byte).
It can do so in only one way:
If a read position
is available, it takes byte as the element stored
in the read position and advances the next pointer for the input buffer.
If the function cannot succeed, it returns
traits_type::eof(). Otherwise,
it returns the current element in the input stream,
converted as described above.
class istringstream : public istream {
public:
explicit istringstream(ios_base::openmode mode =
ios_base::in);
explicit istringstream(const string& str,
ios_base::openmode mode = ios_base::in);
stringbuf *rdbuf() const;
string str();
void str(const string& newstr);
};The class describes an object that controls
extraction of elements and encoded objects from a
stream buffer of class
stringbuf.
The object stores an object of class
stringbuf.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
explicit istringstream(ios_base::openmode mode =
ios_base::in);
explicit istringstream(const string& str,
ios_base::openmode mode = ios_base::in);The first constructor initializes the base class by calling
istream(sb),
where sb is the stored object of class
stringbuf.
It also initializes sb by calling
stringbuf(mode | ios_base::in).
The second constructor initializes the base class by calling
istream(sb).
It also initializes sb by calling
stringbuf(str,
mode | ios_base::in).
stringbuf *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
stringbuf.
string str() const;
void str(const string& newstr);
The first member function returns
rdbuf()->
str().
The second member function calls rdbuf()-> str(newstr).
class ostringstream : public ostream {
public:
typedef Alloc allocator_type;
explicit ostringstream(ios_base::openmode mode =
ios_base::out);
explicit ostringstream(const string& str,
ios_base::openmode mode = ios_base::out);
stringbuf *rdbuf() const;
string str();
void str(const string& newstr);
};The class describes an object that controls
insertion of elements and encoded objects into a
stream buffer of class
stringbuf.
The object stores an object of class
stringbuf.
typedef Alloc allocator_type;
The type is a synonym for the template parameter Alloc.
explicit ostringstream(ios_base::openmode mode =
ios_base::out);
explicit ostringstream(const string& str,
ios_base::openmode mode = ios_base::out);The first constructor initializes the base class by calling
ostream(sb),
where sb is the stored object of class
stringbuf.
It also initializes sb by calling
stringbuf(mode | ios_base::out).
The second constructor initializes the base class by calling
ostream(sb).
It also initializes sb by calling
stringbuf(str,
mode | ios_base::out).
stringbuf *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
stringbuf.
string str() const;
void str(const string& newstr);
The first member function returns
rdbuf()->
str().
The second member function calls rdbuf()-> str(newstr).
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
53 - stdarg
<stdarg.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
54 - stddef
<stddef.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
55 - stdexcep
<stdexcept>
Include the standard header <stdexcept>
to define several classes used for reporting exceptions.
The classes form a derivation hierarchy, as indicated by the indenting
above, all derived from class
exception.
// DECLARATIONS
class logic_error;
class domain_error;
class invalid_argument;
class length_error;
class out_of_range;
class runtime_error;
class range_error;
class overflow_error;
class underflow_error;
// END OF DECLARATIONSclass domain_error : public logic_error {
public:
domain_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report a
domain error. The value returned by
what() is a copy of
message.data().
class invalid_argument : public logic_error {
public:
invalid_argument(const string& message);
};The class serves as the base class for all exceptions thrown
to report an invalid argument. The value returned by
what() is a copy of
message.data().
class length_error : public logic_error {
public:
length_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report an attempt to generate an object too long to be specified.
The value returned by
what() is a copy of
message.data().
class logic_error : public exception {
public:
logic_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report errors presumably detectable before the program executes,
such as violations of logical preconditions. The value returned by
what() is a copy of
message.data().
class out_of_range : public logic_error {
public:
out_of_range(const string& message);
};The class serves as the base class for all exceptions thrown
to report an argument that is out of its valid range. The value returned by
what() is a copy of
message.data().
class overflow_error : public runtime_error {
public:
overflow_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report an arithmetic overflow. The value returned by
what() is a copy of
message.data().
class range_error : public runtime_error {
public:
range_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report a
range error. The value returned by
what() is a copy of
message.data().
class runtime_error : public exception {
public:
runtime_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report errors presumably detectable only when the program executes.
The value returned by
what() is a copy of
message.data().
class underflow_error : public runtime_error {
public:
underflow_error(const string& message);
};The class serves as the base class for all exceptions thrown
to report an arithmetic underflow. The value returned by
what() is a copy of
message.data().
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
56 - stdio
<stdio.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
57 - stdlib
<stdlib.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
58 - streambu
<streambuf>
Include the iostreams
standard header <streambuf> to define
class streambuf,
which is basic to the operation of the iostreams classes.
(This header is typically included for you by another
of the iostreams headers. You seldom have occasion to include it
directly.)
// DECLARATIONS
class streambuf;
// END OF DECLARATIONS
streambuf
· char_type
· eback
· egptr
· epptr
· gbump
· getloc
· gptr
· imbue
· in_avail
· int_type
· off_type
· overflow
· pbackfail
· pbase
· pbump
· pos_type
· pptr
· pubimbue
· pubseekoff
· pubseekpos
· pubsetbuf
· pubsync
· sbumpc
· seekoff
· seekpos
· setbuf
· setg
· setp
· sgetc
· sgetn
· showmanyc
· snextc
· sputbackc
· sputc
· sputn
· stossc
· sungetc
· sync
· traits_type
· uflow
· underflow
· xsgetn
· xsputn
class streambuf {
public:
typedef char char_type;
typedef char_traits traits_type;
typedef traits_type::int_type int_type;
typedef traits_type::pos_type pos_type;
typedef traits_type::off_type off_type;
virtual ~streambuf();
locale pubimbue(const locale& loc);
locale getloc() const;
streambuf *pubsetbuf(char_type *buffer,
streamsize count);
pos_type pubseekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
pos_type pubseekpos(pos_type sp,
ios_base::openmode which =
ios_base::in | ios_base::out);
int pubsync();
streamsize in_avail();
int_type snextc();
int_type sbumpc();
int_type sgetc();
void stossc(); [optional]
streamsize sgetn(char_type *ptr, streamsize count);
int_type sputbackc(char_type ch);
int_type sungetc();
int_type sputc(char_type ch);
streamsize sputn(const char_type *ptr, streamsize count);
protected:
streambuf();
char_type *eback() const;
char_type *gptr() const;
char_type *egptr() const;
void gbump(int count);
void setg(char_type *gbeg,
char_type *gnext, char_type *gend);
char_type *pbase() const;
char_type *pptr() const;
char_type *epptr() const;
void pbump(int count);
void setp(char_type *pbeg, char_type *pend);
virtual void imbue(const locale &loc);
virtual streambuf *setbuf(char_type *buffer,
streamsize count);
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual pos_type seekpos(pos_type sp,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual int sync();
virtual streamsize showmanyc();
virtual streamsize xsgetn(char_type *ptr,
streamsize count);
virtual int_type underflow();
virtual int_type uflow();
virtual int_type pbackfail(int_type meta =
traits_type::eof());
virtual streamsize xsputn(const char_type *ptr,
streamsize count);
virtual int_type overflow(int_type meta =
traits_type::eof());
};The class describes an abstract base class for deriving a
stream buffer, which controls
the transmission of elements to and from a specific
representation of a stream. An object of class
streambuf helps control
a stream with elements of type char, also known as
char_type, whose
character traits
are determined by the class
char_traits,
also known as
traits_type.
Every stream buffer conceptually controls
two independent streams, in fact, one for extractions (input) and one for
insertions (output). A specific representation may, however, make
either or both of these streams inaccessible. It typically maintains
some relationship between the two streams.
What you insert into the output stream of a
stringbuf
object, for example, is what you later extract from its input stream.
And when you position one stream of a
filebuf
object, you position the other stream in tandem.
The public interface to template class
streambuf
supplies the operations common to all stream buffers, however
specialized. The protected interface supplies the operations
needed for a specific representation of a stream
to do its work. The protected virtual member functions let you
tailor the behavior of a derived stream buffer for a specific
representation of a stream. Each of the derived stream buffers
in this library describes how it specializes the
behavior of its protected virtual member functions. Documented
here is the default behavior for the base class,
which is often to do nothing.
The remaining protected member
functions control copying to and from any storage supplied to
buffer transmissions to and from streams.
An input buffer,
for example, is characterized by:
eback(),
a pointer to the beginning of the buffergptr(),
a pointer to the next element to readegptr(),
a pointer just past the end of the buffer
Similarly, an output buffer
is characterized by:
pbase(),
a pointer to the beginning of the bufferpptr(),
a pointer to the next element to writeepptr(),
a pointer just past the end of the buffer
For any buffer, the protocol is:
- If the next pointer is null, no buffer exists. Otherwise,
all three pointers point into the same sequence. (They can
be safely compared for order.)
- For an output buffer, if the next pointer compares less
than the end pointer, you can store an element at the
write position
designated by the next pointer.
- For an input buffer, if the next pointer compares less
than the end pointer, you can read an element at the
read position
designated by the next pointer.
- For an input buffer, if the beginning pointer compares less
than the next pointer, you can put back an element at the
putback position
designated by the decremented next pointer.
Any protected virtual member functions you write for a
class derived from streambuf
must cooperate in maintaining this protocol.
An object of class streambuf
stores the six pointers described above.
streambuf();
The protected constructor stores a null pointer in all the pointers
controlling the
input buffer and the
output buffer.
typedef char char_type;
The type is a synonym for char.
char_type *eback() const;
The member function returns a pointer to the beginning of the
input buffer.
char_type *egptr() const;
The member function returns a pointer just past the end of the
input buffer.
char_type *epptr() const;
The member function returns a pointer just past the end of the
output buffer.
void gbump(int count);
The member function adds count to the next pointer for the
input buffer.
locale getloc() const;
The member function returns the stored locale object.
char_type *gptr() const;
The member function returns a pointer to the next element of the
input buffer.
virtual void imbue(const locale &loc);
The default behavior is to do nothing.
streamsize in_avail();
If a read position is available,
the member function returns
egptr() -
gptr().
Otherwise, it returns
showmanyc().
typedef traits_type::int_type int_type;
The type is a synonym for
traits_type::int_type.
typedef traits_type::off_type off_type;
The type is a synonym for
traits_type::off_type.
virtual int_type overflow(int_type meta =
traits_type::eof());If meta does not compare equal to
traits_type::eof(),
the protected virtual member function endeavors to insert the element
traits_type:: to_char_type(meta)
into the output stream. It can do so in various ways:
- If a write position is available,
it can store the element into the write position and increment the
next pointer for the
output buffer.
- It can make a write position available by allocating
new or additional storage for the output buffer.
- It can make a write position available by writing out, to some
external destination, some or all of the elements
between the beginning and next pointers for the output buffer.
If the function cannot succeed, it returns
traits_type::eof() or throws an exception.
Otherwise, it returns
traits_type::not_eof(meta).
The default behavior is to return traits_type::eof().
virtual int_type pbackfail(int_type meta =
traits_type::eof());The protected virtual member function endeavors to put back an element
into the input stream, then make it the current element (pointed to
by the next pointer).
If meta compares equal to
traits_type::eof(),
the element to push back is effectively the one already in the stream
before the current element. Otherwise, that element is replaced by
traits_type::
to_char_type(meta).
The function can put back an element in various ways:
- If a putback position is available,
it can store the element into the putback position and decrement the
next pointer for the
input buffer.
- It can make a putback position available by allocating
new or additional storage for the input buffer.
- For a stream buffer with common input and output streams,
it can make a putback position available by writing out, to some
external destination, some or all of the elements
between the beginning and next pointers for the output buffer.
If the function cannot succeed, it returns
traits_type::eof() or throws an exception. Otherwise,
it returns some other value.
The default behavior is to return traits_type::eof().
char_type *pbase() const;
The member function returns a pointer to the beginning of the
output buffer.
void pbump(int count);
The member function adds count to the next pointer for the
output buffer.
typedef traits_type::pos_type pos_type;
The type is a synonym for
traits_type::pos_type.
char_type *pptr() const;
The member function returns a pointer to the next element of the
output buffer.
locale pubimbue(const locale& loc);
The member function stores loc in the
locale object, calls
imbue(),
then returns the previous value stored in the locale object.
pos_type pubseekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);The member function returns
seekoff(off, way,
which).
pos_type pubseekpos(pos_type sp,
ios_base::openmode which =
ios_base::in | ios_base::out);The member function returns
seekpos(sp, which).
streambuf *pubsetbuf(char_type *buffer, streamsize count);
The member function returns
setbuf(buffer, count).
int pubsync();
The member function returns
sync().
int_type sbumpc();
If a read position is available,
the member function returns
traits_type::to_int_type(
*gptr())
and increments the next pointer for the
input buffer.
Otherwise, it returns
uflow().
virtual pos_type seekoff(off_type off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. The new position is determined
as follows:
- If
way ==
ios_base::beg,
the new position is the beginning of the stream plus off. - If
way ==
ios_base::cur,
the new position is the current stream position plus off. - If
way ==
ios_base::end,
the new position is the end of the stream plus off.
Typically, if
which & ios_base::in is nonzero,
the input stream is affected, and if which & ios_base::out
is nonzero, the output stream is affected. Actual use of this parameter
varies among derived stream buffers, however.
If the function succeeds in altering the stream position(s),
it returns the resultant stream position (or one of them).
Otherwise, it returns an invalid stream position.
The default behavior is to return an invalid stream position.
virtual pos_type seekpos(pos_type sp,
ios_base::openmode which =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams.
The new position is sp.
Typically, if
which & ios_base::in is nonzero,
the input stream is affected, and if which & ios_base::out
is nonzero, the output stream is affected. Actual use of this parameter
varies among derived stream buffers, however.
If the function succeeds in altering the stream position(s),
it returns the resultant stream position (or one of them).
Otherwise, it returns an invalid stream position.
The default behavior is to return an invalid stream position.
virtual streambuf *setbuf(char_type *buffer,
streamsize count);The protected virtual member function performs an operation
particular to each derived stream buffer. (See, for example,
filebuf.)
The default behavior is to return this.
void setg(char_type *gbeg, char_type *gnext,
char_type *gend);The member function stores gbeg in the beginning pointer,
gnext in the next pointer,
and gend in the end pointer for the
input buffer.
void setp(char_type *pbeg, char_type *pend);
The member function stores pbeg in the beginning pointer,
pbeg in the next pointer,
and pend in the end pointer for the
output buffer.
int_type sgetc();
If a read position is available,
the member function returns
traits_type::to_int_type(
*gptr())
Otherwise, it returns
underflow().
streamsize sgetn(char_type *ptr, streamsize count);
The member function returns
xsgetn(ptr, count).
virtual streamsize showmanyc();
The protected virtual member function returns a count of the
number of characters that can be extracted from the input
stream with no fear that the program will suffer an indefinite
wait. The default behavior is to return zero.
int_type snextc();
The member function calls
sbumpc() and,
if that function returns
traits_type::eof(),
returns traits_type::eof().
Otherwise, it returns
sgetc().
int_type sputbackc(char_type ch);
If a putback position is available
and ch compares equal to the character stored in that position,
the member function decrements the next pointer for the
input buffer and returns
traits_type::to_int_type(ch).
Otherwise, it returns
pbackfail(ch).
int_type sputc(char_type ch);
If a write position is available,
the member function stores ch in the write position,
increments the next pointer for the
output buffer, and returns
traits_type::to_int_type(ch).
Otherwise, it returns
overflow(ch).
streamsize sputn(const char_type *ptr, streamsize count);
The member function returns
xsputn(ptr, count).
void stossc(); [optional]
The member function calls
sbumpc().
Note that an implementation is not required to supply this member function.
int_type sungetc();
If a putback position is available,
the member function decrements the next pointer for the
input buffer and returns
traits_type::to_int_type(
*gptr()).
Otherwise it returns
pbackfail().
virtual int sync();
The protected virtual member function endeavors to synchronize
the controlled streams with any associated external streams.
Typically, this involves writing out any elements between the beginning
and next pointers for the
output buffer.
It does not involve putting back any elements between the next
and end pointers for the
input buffer.
If the function cannot succeed, it returns -1.
The default behavior is to return zero.
typedef char_traits traits_type;
The type is a synonym for
char_traits.
virtual int_type uflow();
The protected virtual member function endeavors to extract the current
element ch from the input stream,
then advance the current stream position, and return the element as
traits_type::to_int_type(ch).
It can do so in various ways:
- If a read position is available,
it takes
ch as the element stored in the read position
and advances the next pointer for the
input buffer. - It can read an element directly, from some external source,
and deliver it as the value
ch. - For a stream buffer with common input and output streams,
it can make a read position available by writing out, to some
external destination, some or all of the elements
between the beginning and next pointers for the output buffer.
Or it can allocate new or additional storage for the
input buffer. The function
then reads in, from some external source, one or more elements.
If the function cannot succeed, it returns
traits_type::eof(),
or throws an exception. Otherwise,
it returns the current element ch in the input stream,
converted as described above, and advances the next pointer
for the input buffer. The default behavior is to call
underflow()
and, if that function returns traits_type::eof(),
to return traits_type::eof(). Otherwise, the function
returns the current element ch in the input stream,
converted as described above, and advances the next pointer
for the input buffer.
virtual int_type underflow();
The protected virtual member function endeavors to extract the current
element ch from the input stream,
without advancing the current stream position, and return it as
traits_type::to_int_type(ch).
It can do so in various ways:
- If a read position is available,
ch is the element stored in the read position. - It can make a read position available by allocating
new or additional storage for the
input buffer, then reading in,
from some external source, one or more elements.
If the function cannot succeed, it returns
traits_type::eof(),
or throws an exception. Otherwise,
it returns the current element in the input stream,
converted as described above.
The default behavior is to return traits_type::eof().
virtual streamsize xsgetn(char_type *ptr, streamsize count);
The protected virtual member function extracts up to count
elements from the input stream, as if by repeated calls to
sbumpc,
and stores them in the array beginning at ptr.
It returns the number of elements actually extracted.
virtual streamsize xsputn(const char_type *ptr,
streamsize count);The protected virtual member function inserts up to count
elements into the output stream, as if by repeated calls to
sputc,
from the array beginning at ptr.
It returns the number of elements actually inserted.
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
59 - string
<string.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.
60 - string2
<string>
string
· char_allocator
· char_traits
· getline
· operator+
· operator!=
· operator==
· operator<
· operator<<
· operator<=
· operator>
· operator>=
· operator>>
· swap
Include the standard header <string>
to define the
class
string and various
supporting classes and functions.
// DECLARATIONS
class char_allocator;
class char_traits;
class string;
// FUNCTIONS
string operator+(
const string& left,
const string& right);
string operator+(
const string& left,
const char *right);
string operator+(
const string& left,
char right);
string operator+(
const char *left,
const string& right);
string operator+(
char left,
const string& right);
bool operator==(
const string& left,
const string& right);
bool operator==(
const string& left,
const char *right);
bool operator==(
const char *left,
const string& right);
bool operator!=(
const string& left,
const string& right);
bool operator!=(
const string& left,
const char *right);
bool operator!=(
const char *left,
const string& right);
bool operator<(
const string& left,
const string& right);
bool operator<(
const string& left,
const char *right);
bool operator<(
const char *left,
const string& right);
bool operator>(
const string& left,
const string& right);
bool operator>(
const string& left,
const char *right);
bool operator>(
const char *left,
const string& right);
bool operator<=(
const string& left,
const string& right);
bool operator<=(
const string& left,
const char *right);
bool operator<=(
const char *left,
const string& right);
bool operator>=(
const string& left,
const string& right);
bool operator>=(
const string& left,
const char *right);
bool operator>=(
const char *left,
const string& right);
void swap(
string& left,
string& right);
ostream& operator<<(
ostream& ostr,
const string& str);
istream& operator>>(
istream& istr,
string& str);
istream& getline(
istream& istr,
string& str);
istream& getline(
istream& istr,
string& str,
char delim);
// END OF DECLARATIONS
string
· allocator_type
· append
· assign
· at
· begin
· c_str
· capacity
· clear
· compare
· const_iterator
· const_pointer
· const_reference
· const_reverse_iterator
· copy
· data
· difference_type
· empty
· end
· erase
· find
· find_first_not_of
· find_first_of
· find_last_not_of
· find_last_of
· get_allocator
· insert
· iterator
· length
· max_size
· npos
· operator+=
· operator=
· operator[]
· pointer
· push_back
· rbegin
· reference
· rend
· replace
· reserve
· resize
· reverse_iterator
· rfind
· size
· size_type
· substr
· swap
· traits_type
· value_type
class string {
public:
typedef char_traits traits_type;
typedef char_allocator allocator_type;
typedef T0 iterator;
typedef T1 const_iterator;
typedef T2 size_type;
typedef T3 difference_type;
class const_reverse_iterator;
class reverse_iterator;
typedef allocator_type::pointer
pointer;
typedef allocator_type::const_pointer
const_pointer;
typedef allocator_type::reference
reference;
typedef allocator_type::const_reference
const_reference;
typedef allocator_type::value_type
value_type;
static const size_type npos = -1;
string();
explicit string(const allocator_type& al);
string(const string& right);
string(const string& right, size_type roff,
size_type count = npos);
string(const string& right, size_type roff,
size_type count, const allocator_type& al);
string(const value_type *ptr, size_type count);
string(const value_type *ptr, size_type count,
const allocator_type& al);
string(const value_type *ptr);
string(const value_type *ptr,
const allocator_type& al);
string(size_type count, value_type ch);
string(size_type count, value_type ch,
const allocator_type& al);
string(const_iterator first,
const_iterator last);
string(const_iterator first,
const_iterator last,
const allocator_type& al);
string& operator=(const string& right);
string& operator=(const value_type *ptr);
string& operator=(value_type ch);
iterator begin();
const_iterator begin() const;
iterator end();
const_iterator end() const;
reverse_iterator rbegin();
const_reverse_iterator rbegin() const;
reverse_iterator rend();
const_reverse_iterator rend() const;
const_reference at(size_type off) const;
reference at(size_type off);
const_reference operator[](size_type off) const;
reference operator[](size_type off);
void push_back(value_type ch);
const value_type *c_str() const;
const value_type *data() const;
size_type length() const;
size_type size() const;
size_type max_size() const;
void resize(size_type newsize, value_type ch = value_type());
size_type capacity() const;
void reserve(size_type count = 0);
bool empty() const;
string& operator+=(const string& right);
string& operator+=(const value_type *ptr);
string& operator+=(value_type ch); string& append(const string& right);
string& append(const string& right,
size_type roff, size_type count);
string& append(const value_type *ptr,
size_type count);
string& append(const value_type *ptr);
string& append(size_type count, value_type ch);
string& append(const_iterator first,
const_iterator last);
string& assign(const string& right);
string& assign(const string& right,
size_type roff, size_type count);
string& assign(const value_type *ptr,
size_type count);
string& assign(const value_type *ptr);
string& assign(size_type count, value_type ch);
string& assign(const_iterator first,
const_iterator last);
string& insert(size_type off,
const string& right);
string& insert(size_type off,
const string& right, size_type roff,
size_type count);
string& insert(size_type off,
const value_type *ptr, size_type count);
string& insert(size_type off,
const value_type *ptr);
string& insert(size_type off,
size_type count, value_type ch);
iterator insert(iterator where,
value_type ch = value_type());
void insert(iterator where, size_type count, value_type ch);
void insert(iterator where,
const_iterator first, const_iterator last);
string& erase(size_type off = 0,
size_type count = npos);
iterator erase(iterator where);
iterator erase(iterator first, iterator last);
void clear();
string& replace(size_type off, size_type n0,
const string& right);
string& replace(size_type off, size_type n0,
const string& right, size_type roff,
size_type count);
string& replace(size_type off, size_type n0,
const value_type *ptr, size_type count);
string& replace(size_type off, size_type n0,
const value_type *ptr);
string& replace(size_type off, size_type n0,
size_type count, value_type ch);
string& replace(iterator first, iterator last,
const string& right);
string& replace(iterator first, iterator last,
const value_type *ptr, size_type count);
string& replace(iterator first, iterator last,
const value_type *ptr);
string& replace(iterator first, iterator last,
size_type count, value_type ch);
string& replace(iterator first, iterator last,
const_iterator first2, const_iterator last2);
size_type copy(value_type *ptr, size_type count,
size_type off = 0) const;
void swap(string& right); size_type find(const string& right,
size_type off = 0) const;
size_type find(const value_type *ptr, size_type off,
size_type count) const;
size_type find(const value_type *ptr,
size_type off = 0) const;
size_type find(value_type ch, size_type off = 0) const;
size_type rfind(const string& right,
size_type off = npos) const;
size_type rfind(const value_type *ptr, size_type off,
size_type count = npos) const;
size_type rfind(const value_type *ptr,
size_type off = npos) const;
size_type rfind(value_type ch,
size_type off = npos) const;
size_type find_first_of(const string& right,
size_type off = 0) const;
size_type find_first_of(const value_type *ptr,
size_type off, size_type count) const;
size_type find_first_of(const value_type *ptr,
size_type off = 0) const;
size_type find_first_of(value_type ch,
size_type off = 0) const;
size_type find_last_of(const string& right,
size_type off = npos) const;
size_type find_last_of(const value_type *ptr,
size_type off, size_type count = npos) const;
size_type find_last_of(const value_type *ptr,
size_type off = npos) const;
size_type find_last_of(value_type ch,
size_type off = npos) const;
size_type find_first_not_of(const string& right,
size_type off = 0) const;
size_type find_first_not_of(const value_type *ptr,
size_type off, size_type count) const;
size_type find_first_not_of(const value_type *ptr,
size_type off = 0) const;
size_type find_first_not_of(value_type ch,
size_type off = 0) const;
size_type find_last_not_of(const string& right,
size_type off = npos) const;
size_type find_last_not_of(const value_type *ptr,
size_type off, size_type count) const;
size_type find_last_not_of(const value_type *ptr,
size_type off = npos) const;
size_type find_last_not_of(value_type ch,
size_type off = npos) const;
string substr(size_type off = 0,
size_type count = npos) const;
int compare(const string& right) const;
int compare(size_type off, size_type n0,
const string& right) const;
int compare(size_type off, size_type n0,
const string& right, size_type roff,
size_type count) const;
int compare(const value_type *ptr) const;
int compare(size_type off, size_type n0,
const value_type *ptr) const;
int compare(size_type off, size_type n0,
const value_type *ptr, size_type off) const;
allocator_type get_allocator() const;
};The class describes an object that controls a
varying-length sequence of elements of type char,
also known as
value_type.
Various important properties of the elements
in a string
are described by the class
char_traits,
also known as
traits_type.
The object allocates and frees storage for the sequence it controls
through a stored allocator object of class
char_allocator, also known as
allocator_type.
Note that the stored allocator object is not copied when the container
object is assigned.
The sequences controlled by an object of class
string are usually called
strings. These objects should not be
confused, however, with the null-terminated
C strings used throughout the
Standard C++ library.
Many member functions require an
operand sequence of elements.
You can specify such an operand sequence several
ways:
ch -- one element
with value chcount, ch -- a repetition of count elements each
with value chptr -- a null-terminated sequence
(such as a C string) beginning at
ptr (which must not be a null pointer),
where the terminating element is the value
value_type() and is not part of
the operand sequenceptr, count -- a sequence of count elements
beginning at ptr (which must not be a null pointer)right -- the sequence specified by the
string object rightright, roff, count -- the substring of the
string object right with up to count
elements (or through the end of the string, whichever comes first)
beginning at position rofffirst, last -- a sequence of elements delimited
by the iterators first and last, in the
range [first, last), which may overlap
the sequence controlled by the string object whose member function
is being called
If a position argument
(such as roff above) is beyond the end of the string on a
call to a string member function, the function
reports an
out-of-range error by
throwing an object of class
out_of_range.
If a function is asked to generate a sequence longer than
max_size() elements,
the function reports a
length error by
throwing an object of class
length_error.
References, pointers, and iterators that designate elements of the
controlled sequence can become invalid after any call to a function
that alters the controlled sequence, or after the first call to the
non-const member functions
at,
begin,
end,
operator[],
rbegin, or
rend.
(The idea is to permit multiple strings to share the same representation
until one string becomes a candidate for change, at which point that string
makes a private copy of the representation, using a discipline called
copy on write.)
typedef char_allocator allocator_type;
The type is a synonym for
char_allocator.
string& append(const value_type *ptr);
string& append(const value_type *ptr,
size_type count);
string& append(const string& right,
size_type roff, size_type count);
string& append(const string& right);
string& append(size_type count, value_type ch);
string& append(const_iterator first,
const_iterator last);The
member functions each append the
operand sequence to the end of the
sequence controlled by *this,
then return *this.
string& assign(const value_type *ptr);
string& assign(const value_type *ptr,
size_type count);
string& assign(const string& right,
size_type roff, size_type count);
string& assign(const string& right);
string& assign(size_type count, value_type ch);
string& assign(const_iterator first,
const_iterator last);The
member functions each replace
the sequence controlled by *this with the
operand sequence, then return *this.
const_reference at(size_type off) const;
reference at(size_type off);
The member functions each return a reference to the element of the
controlled sequence at position off,
or report an out-of-range error.
string(const value_type *ptr);
string(const value_type *ptr,
const allocator_type& al);
string(const value_type *ptr, size_type count);
string(const value_type *ptr, size_type count,
const allocator_type& al);
string(const string& right);
string(const string& right, size_type roff,
size_type count = npos);
string(const string& right, size_type roff,
size_type count, const allocator_type& al);
string(size_type count, value_type ch);
string(size_type count, value_type ch,
const allocator_type& al);
string();
explicit string(const allocator_type& al);
string(const_iterator first, const_iterator last);
string(const_iterator first, const_iterator last,
const allocator_type& al);All constructors store an
allocator object and
initialize the controlled sequence. The allocator object is the argument
al, if present. For the copy constructor, it is
right.get_allocator().
Otherwise, it is Alloc().
The controlled sequence is initialized to a copy of the
operand sequence specified by the
remaining operands. A constructor with no operand sequence specifies an
empty initial controlled sequence.
const_iterator begin() const;
iterator begin();
The member functions each return a random-access iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).
const value_type *c_str() const;
The member function returns a pointer to a non-modifiable
C string constructed by adding a
terminating null element
(value_type()) to the controlled
sequence. Calling any non-const member function for
*this can invalidate the pointer.
size_type capacity() const;
The member function returns the storage currently allocated to hold
the controlled sequence, a value at least as large as
size().
void clear();
The member function calls
erase(
begin(),
end()).
int compare(const string& right) const;
int compare(size_type off, size_type n0,
const string& right) const;
int compare(size_type off, size_type n0,
const string& right, size_type roff, size_type count) const;
int compare(const value_type *ptr) const;
int compare(size_type off, size_type n0,
const value_type *ptr) const;
int compare(size_type off, size_type n0,
const value_type *ptr, size_type off) const;The member functions each compare up to n0 elements of the
controlled sequence beginning with position off, or the
entire controlled sequence if these arguments are not supplied,
to the operand sequence.
Each function returns:
- a negative value if the first differing element in the controlled
sequence compares less than the corresponding element in the operand
sequence (as determined by
traits_type::compare), or if the
two have a common prefix but the operand sequence is longer - zero if the two compare equal element by element and are the same
length
- a positive value otherwise
typedef T1 const_iterator;
The type describes an object that can serve as a constant
random-access iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T1.
typedef allocator_type::const_pointer
const_pointer;The type is a synonym for allocator_type::const_pointer.
typedef allocator_type::const_reference
const_reference;The type is a synonym for allocator_type::const_reference.
class const_reverse_iterator;
The type describes an object that can serve as a constant reverse
iterator for the controlled sequence. You can, for example, access each of
the elements in the controlled sequence in reverse order by writing:
string::const_reverse_iterator rit;
for (rit = rbegin(); rit != rend(); ++rit)
process *ritsize_type copy(value_type *ptr, size_type count,
size_type off = 0) const;The member function copies up to count elements from the
controlled sequence, beginning at position off, to the
array of value_type beginning at ptr. It returns the
number of elements actually copied.
const value_type *data() const;
The member function returns a pointer to the first element
of the sequence (or, for an empty sequence, a non-null pointer
that cannot be dereferenced).
typedef T3 difference_type;
The signed integer type describes an object that can represent the
difference between the addresses of any two elements in the controlled
sequence. It is described here as a
synonym for the implementation-defined type T3.
bool empty() const;
The member function returns true for an empty controlled sequence.
const_iterator end() const;
iterator end();
The member functions each return a random-access iterator that points
just beyond the end of the sequence.
iterator erase(iterator first, iterator last);
iterator erase(iterator where);
string& erase(size_type off = 0,
size_type count = npos);The first member function removes the elements of the controlled
sequence in the range [first, last).
The second member function removes the element of the controlled
sequence pointed to by where.
Both return an iterator that designates the first element remaining
beyond any elements removed, or
end()
if no such element exists.
The third member function removes up to count elements of
the controlled sequence beginning at position off, then
returns *this.
size_type find(value_type ch, size_type off = 0) const;
size_type find(const value_type *ptr,
size_type off = 0) const;
size_type find(const value_type *ptr, size_type off,
size_type count) const;
size_type find(const string& right,
size_type off = 0) const;The member functions each find the first (lowest beginning position)
subsequence in the controlled sequence, beginning on or after position
off, that matches the
operand sequence specified by the
remaining operands. If it succeeds, it returns the position where the
matching subsequence begins. Otherwise, the function returns
npos.
size_type find_first_not_of(value_type ch,
size_type off = 0) const;
size_type find_first_not_of(const value_type *ptr,
size_type off = 0) const;
size_type find_first_not_of(const value_type *ptr,
size_type off, size_type count) const;
size_type find_first_not_of(const string& right,
size_type off = 0) const;The member functions each find the first (lowest position) element of the
controlled sequence, at or after position off, that
matches none of the elements in the
operand sequence specified by the
remaining operands. If it succeeds, it returns the position. Otherwise,
the function returns
npos.
size_type find_first_of(value_type ch,
size_type off = 0) const;
size_type find_first_of(const value_type *ptr,
size_type off = 0) const;
size_type find_first_of(const value_type *ptr,
size_type off, size_type count) const;
size_type find_first_of(const string& right,
size_type off = 0) const;The member functions each find the first (lowest position) element of the
controlled sequence, at or after position off, that
matches any of the elements in the
operand sequence specified by the
remaining operands. If it succeeds, it returns the position. Otherwise,
the function returns
npos.
size_type find_last_not_of(value_type ch,
size_type off = npos) const;
size_type find_last_not_of(const value_type *ptr,
size_type off = npos) const;
size_type find_last_not_of(const value_type *ptr,
size_type off, size_type count) const;
size_type find_last_not_of(const string& right,
size_type off = npos) const;The member functions each find the last (highest position) element of the
controlled sequence, at or before position off, that
matches none of the elements in the
operand sequence specified by the
remaining operands. If it succeeds, it returns the position. Otherwise,
the function returns
npos.
size_type find_last_of(value_type ch,
size_type off = npos) const;
size_type find_last_of(const value_type *ptr,
size_type off = npos) const;
size_type find_last_of(const value_type *ptr,
size_type off, size_type count = npos) const;
size_type find_last_of(const string& right,
size_type off = npos) const;The member functions each find the last (highest position) element of the
controlled sequence, at or before position off, that
matches any of the elements in the
operand sequence specified by the
remaining operands. If it succeeds, it returns the position. Otherwise,
the function returns
npos.
allocator_type get_allocator() const;
The member function returns the stored
allocator object.
string& insert(size_type off, const value_type *ptr);
string& insert(size_type off, const value_type *ptr,
size_type count);
string& insert(size_type off,
const string& right);
string& insert(size_type off,
const string& right, size_type roff, size_type count);
string& insert(size_type off,
size_type count, value_type ch);
iterator insert(iterator where,
value_type ch = value_type());
void insert(iterator where,
const_iterator first, const_iterator last);
void insert(iterator where, size_type count, value_type ch);The member functions each insert, before position off or
before the element pointed to by where in the controlled
sequence, the
operand sequence specified by the
remaining operands. A function that returns a value returns
*this.
typedef T0 iterator;
The type describes an object that can serve as a random-access
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type T0.
size_type length() const;
The member function returns the length of the controlled sequence
(same as size()).
size_type max_size() const;
The member function returns the length of the longest sequence that
the object can control.
static const size_type npos = -1;
The constant is the largest representable value of type
size_type. It is
assuredly larger than
max_size(), hence
it serves as either a very large value or as a special code.
string& operator+=(value_type ch);
string& operator+=(const value_type *ptr);
string& operator+=(const string& right);
The operators each append the
operand sequence to the end of the
sequence controlled by *this, then return *this.
string& operator=(value_type ch);
string& operator=(const value_type *ptr);
string& operator=(const string& right);
The operators each replace the sequence controlled by *this
with the
operand sequence,
then return *this.
const_reference operator[](size_type off) const;
reference operator[](size_type off);
The member functions each return a reference to the element of the
controlled sequence at position off. If that position is
invalid, the behavior is undefined. Note, however, that
cstr[cstr.size()] == 0 for the first member function.
typedef allocator_type::pointer
pointer;The type is a synonym for allocator_type::pointer.
void push_back(value_type ch);
The member function effectively calls
insert(
end(), ch).
const_reverse_iterator rbegin() const;
reverse_iterator rbegin();
The member function returns a reverse iterator that points just
beyond the end of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.
typedef allocator_type::reference
reference;The type is a synonym for allocator_type::reference.
const_reverse_iterator rend() const;
reverse_iterator rend();
The member functions each return a reverse iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, the function designates the end of the reverse sequence.
string& replace(size_type off, size_type n0,
const value_type *ptr);
string& replace(size_type off, size_type n0,
const value_type *ptr, size_type count);
string& replace(size_type off, size_type n0,
const string& right);
string& replace(size_type off, size_type n0,
const string& right, size_type roff, size_type count);
string& replace(size_type off, size_type n0,
size_type count, value_type ch);
string& replace(iterator first, iterator last,
const value_type *ptr);
string& replace(iterator first, iterator last,
const value_type *ptr, size_type count);
string& replace(iterator first, iterator last,
const string& right);
string& replace(iterator first, iterator last,
size_type count, value_type ch);
string& replace(iterator first, iterator last,
const_iterator first2, const_iterator last2);The member functions each replace up to n0 elements of the
controlled sequence beginning with position off, or the
elements of the controlled sequence beginning with the one pointed to by
first, up to but not including last. The
replacement is the
operand sequence specified by the
remaining operands. The function then returns
*this.
void reserve(size_type count = 0);
The member function ensures that
capacity()
henceforth returns at least count.
void resize(size_type newsize, value_type ch = value_type());
The member function ensures that
size() henceforth
returns newsize. If it must make the controlled sequence longer,
it appends elements with value ch.
To make the controlled sequence shorter, the member function effectively calls
erase(begin() + newsize, end()).
class reverse_iterator;
The type describes an object that can serve as a reverse
iterator for the controlled sequence. You can, for example, access each of
the elements in the controlled sequence in reverse order by writing:
string::reverse_iterator rit;
for (rit = rbegin(); rit != rend(); ++rit)
process *ritsize_type rfind(value_type ch, size_type off = npos) const;
size_type rfind(const value_type *ptr,
size_type off = npos) const;
size_type rfind(const value_type *ptr,
size_type off, size_type count = npos) const;
size_type rfind(const string& right,
size_type off = npos) const;The member functions each find the last
(highest beginning position) subsequence in
the controlled sequence, beginning on or before position off,
that matches the
operand sequence specified by the
remaining operands. If it succeeds, the function returns the position where the
matching subsequence begins. Otherwise, it returns
npos.
size_type size() const;
The member function returns the length of the controlled sequence.
typedef T2 size_type;
The unsigned integer type describes an object that can represent the
length of any controlled sequence. It is described here as a
synonym for the implementation-defined type T2.
string substr(size_type off = 0,
size_type count = npos) const;The member function returns an object whose controlled sequence is a
copy of up to count elements of the controlled sequence
beginning at position off.
void swap(string& right);
The member function swaps the controlled sequences between
*this and str. If
get_allocator()
== right.get_allocator(), it does so in constant time,
it throws no exceptions, and it invalidates no references, pointers,
or iterators that designate elements in the two controlled sequences.
Otherwise, it performs a number of element assignments and constructor calls
proportional to the number of elements in the two controlled sequences.
typedef char_traits traits_type;
The type is a synonym for
char_traits.
typedef allocator_type::value_type
value_type;The type is a synonym for allocator_type::value_type.
class char_allocator {
public:
char_allocator();
pointer allocate(size_type count, const void *hint);
void deallocate(pointer ptr, size_type count);
size_type max_size() const;
bool operator==(char_allocator& left,
char_allocator& right) const;
};The class describes an object that manages
storage allocation and freeing for arrays of objects of type char.
An object of class char_allocator is the
allocator object
used by class
string.
It is used here primarily to minimize differences with full Standard C++.
pointer allocate(size_type count, const void *hint);
The member function allocates storage for
an array of count elements of type char, by calling
operator new(count).
It returns a pointer to the allocated object.
The hint argument is unused here. To supply no
hint, use a null pointer argument instead.
char_allocator();
The constructor does nothing.
void deallocate(pointer ptr, size_type count);
The member function frees storage for
the array of count objects of type
char beginning at ptr, by calling
operator delete(ptr).
The pointer ptr must have been earlier returned by a call to
allocate for an allocator
object that compares equal to *this, allocating an array object
of the same size and type.
size_type max_size() const;
The member function returns the length of the longest sequence
of elements of type char that an object of class
char_allocator might be able to allocate.
bool operator==(char_allocator& left,
char_allocator& right) const;The operator returns true. (Two allocator objects should
compare equal only if an object allocated through one can be deallocated
through the other. If the value of one object is determined from another
by assignment or by construction, the two object should compare equal.)
class char_traits {
public:
typedef char char_type;
typedef int int_type;
typedef streampos pos_type;
typedef streamoff off_type;
typedef mbstate_t state_type;
static void assign(char_type& left, const char_type& right);
static char_type *assign(char_type *first, size_t count,
char_type ch);
static bool eq(const char_type& left,
const char_type& right);
static bool lt(const char_type& left,
const char_type& right);
static int compare(const char_type *first1,
const char_type *first2, size_t count);
static size_t length(const char_type *first);
static char_type *copy(char_type *first1,
const char_type *first2, size_t count);
static char_type *move(char_type *first1,
const char_type *first2, size_t count);
static const char_type *find(const char_type *first,
size_t count, const char_type& ch);
static char_type to_char_type(const int_type& meta);
static int_type to_int_type(const char_type& ch);
static bool eq_int_type(const int_type& left,
const int_type& right);
static int_type eof();
static int_type not_eof(const int_type& meta);
};The class describes various
character traits
for type char.
The class
string
as well as several iostreams classes, including
ios, use this information
to manipulate elements of type char.
None of the member functions of class char_traits may
throw exceptions.
static void assign(char_type& left, const char_type& right);
static char_type *assign(char_type *first, size_t count,
char_type ch);The first static member function assigns right
to left. The second static member function assigns ch
to each element X[N] for N
in the range [0, count).
typedef char char_type;
The type is a synonym for char.
static int compare(const char_type *first1,
const char_type *first2, size_t count);The static member function compares the sequence of length count
beginning at first1to the sequence of the same length beginning
at first2. The function returns:
- a negative value if the first differing element in
first1
(as determined by
eq) compares less
than the corresponding element in first2 (as determined by
lt) - zero if the two compare equal element by element
- a positive value otherwise
static char_type *copy(char_type *first1, const char_type *first2,
size_t count);The static member function copies the sequence of count
elements beginning at first2 to the array beginning at first1,
then returns first1. The source and destination
must not overlap.
static int_type eof();
The static member function returns a value that represents
end-of-file (EOF).
static bool eq(const char_type& left, const char_type& right);
The static member function returns true if left compares
equal to right.
static bool eq_int_type(const int_type& left,
const int_type& right);The static member function returns true if
left compares equal to right.
static const char_type *find(const char_type *first,
size_t count, const char_type& ch);The static member function determines the lowest N
in the range [0, count) for which
eq(first[N], ch)
is true. If successful, it returns first + N. Otherwise,
it returns a null pointer.
typedef int int_type;
The type is a synonym for int.
static size_t length(const char_type *first);
The static member function returns the number of elements
N in the sequence beginning at first
up to but not including the element first[N] which
compares equal to char_type().
static bool lt(const char_type& left, const char_type& right);
The static member function returns true if left compares
less than right.
static char_type *move(char_type *first1, const char_type *first2,
size_t count);The static member function copies the sequence of count
elements beginning at first2 to the array beginning at first1,
then returns first1. The source and destination may overlap.
static int_type not_eof(const int_type& meta);
If
!eq_int_type(
eof(), meta),
the static member function returns meta.
Otherwise, it returns a value other than
eof().
typedef streamoff off_type;
The type is a synonym for
streamoff.
typedef streampos pos_type;
The type is a synonym for
streampos.
typedef mbstate_t state_type;
The type is a synonym for
mbstate_t.
static char_type to_char_type(const int_type& meta);
The static member function returns meta represented as
type Elem. A value of meta that cannot be so
represented yields an unspecified result.
static int_type to_int_type(const char_type& ch);
The static member function returns ch represented as
type int_type. It must be possible to convert any value ch of type
Elem to int_type (by evaluating
meta = to_int_type(ch))
then back to Elem (by evaluating
ch = to_char_type(meta))
and obtain a value that compares equal to ch.
istream& getline(istream& istr,
string& str);
istream& getline(istream& istr,
string& str, char delim);The first function returns getline(istr, str, istr.widen('\n')).
The second function replaces the sequence controlled by
str with a sequence of elements extracted from the stream
istr. In order of testing, extraction stops:
- at end of file
- after the function extracts an element that compares equal to
delim, in which case the element is neither put back nor
appended to the controlled sequence - after the function extracts
str.max_size()
elements, in which case the function calls
setstate(ios_base::failbit).
If the function extracts no elements, it calls
setstate(failbit).
In any case, it returns istr.
string operator+(
const string& left,
const string& right);
string operator+(
const string& left,
const char *right);
string operator+(
const string& left,
char right);
string operator+(
const char *left,
const string& right);
string operator+(
char left,
const string& right);The functions each overload operator+ to
concatenate two objects of class
string.
All effectively return
string(left).append(right).
bool operator!=(
const string& left,
const string& right);
bool operator!=(
const string& left,
const char *right);
bool operator!=(
const char *left,
const string& right);The functions each overload operator!= to compare
two objects of class
string. All effectively
return string(left).compare(right)
!= 0.
bool operator==(
const string& left,
const string& right);
bool operator==(
const string& left,
const char *right);
bool operator==(
const char *left,
const string& right);The functions each overload operator== to compare
two objects of class
string. All effectively
return string(left).compare(right)
== 0.
bool operator<(
const string& left,
const string& right);
bool operator<(
const string& left,
const char *right);
bool operator<(
const char *left,
const string& right);The functions each overload operator< to
compare two objects of class
string. All effectively
return string(left).compare(right)
< 0.
ostream& operator<<(
ostream& ostr,
const string& str);The function is a
formatted output functions
that overloads operator<< to
determine the length len =
str.size()
of the sequence controlled by str, and insert the sequence. If
len < ostr.width(),
then the function also inserts a repetition of ostr.width() - len
fill characters.
The repetition precedes the sequence if
(ostr.flags() &
adjustfield !=
left.
Otherwise, the repetition follows the sequence.
The function returns ostr.
bool operator<=(
const string& left,
const string& right);
bool operator<=(
const string& left,
const char *right);
bool operator<=(
const char *left,
const string& right);The functions each overload operator<= to
compare two objects of class
string. All effectively
return string(left).compare(right)
<= 0.
bool operator>(
const string& left,
const string& right);
bool operator>(
const string& left,
const char *right);
bool operator>(
const char *left,
const string& right);The functions each overload operator> to
compare two objects of class
string. All effectively
return string(left).compare(right)
> 0.
bool operator>=(
const string& left,
const string& right);
bool operator>=(
const string& left,
const char *right);
bool operator>=(
const char *left,
const string& right);The functions each overload operator>= to
compare two objects of class
string. All effectively
return string(left).compare(right)
>= 0.
istream& operator>>(
istream& istr,
string& str);The template function overloads operator>> to
replace the sequence controlled by str with a sequence of
elements extracted from the stream istr. Extraction stops:
- at end of file
- after the function extracts
istr.width()
elements, if that value is nonzero - after the function extracts
istr.max_size()
elements - after the function extracts an element
ch for which
isspace(ch)
is true, in which case the character is put back
If the function extracts no elements, it calls
setstate(ios_base::failbit).
In any case, it calls istr.width(0) and
returns *this.
template<class Tr, class Alloc>
void swap(
string& left,
string& right);The template function executes
left.swap(right).
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
61 - strstrea
<strstream>
Include the iostreams
standard header <strstream>
to define several classes that support
iostreams operations on
sequences stored in an allocated array of char object.
Such sequences are easily converted to and from
C strings.
// DECLARATIONS
class strstreambuf;
class istrstream;
class ostrstream;
// END OF DECLARATIONSclass strstreambuf : public streambuf {
public:
explicit strstreambuf(streamsize count = 0);
strstreambuf(void (*allocfunc)(size_t),
void (*freefunc)(void *));
strstreambuf(char *getptr, streamsize count,
char *putptr = 0);
strstreambuf(signed char *getptr, streamsize count,
signed char *putptr = 0);
strstreambuf(unsigned char *getptr, streamsize count,
unsigned char *putptr = 0);
strstreambuf(const char *getptr, streamsize count);
strstreambuf(const signed char *getptr, streamsize count);
strstreambuf(const unsigned char *getptr, streamsize count);
void freeze(bool freezeit = true);
char *str();
streamsize pcount();
protected:
virtual streampos seekoff(streamoff off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual streampos seekpos(streampos sp,
ios_base::openmode which =
ios_base::in | ios_base::out);
virtual int underflow();
virtual int pbackfail(int meta = EOF);
virtual int overflow(int meta = EOF);
};The class describes a
stream buffer that controls
the transmission of elements to and from a sequence of elements
stored in a char array object. Depending on how it
is constructed, the object can be allocated, extended, and
freed as necessary to accommodate changes in the sequence.
An object of class strstreambuf
stores several bits of mode information as its
strstreambuf mode.
These bits indicate whether the controlled sequence:
- has been allocated,
and hence needs to be freed eventually
- is modifiable
- is extendable by reallocating storage
- has been frozen
and hence needs to be unfrozen before the object is destroyed,
or freed (if allocated) by an agency other than the object
A controlled sequence that is frozen cannot be modified or extended,
regardless of the state of these separate mode bits.
The object also stores pointers to two functions that control
strstreambuf allocation.
If these are null pointers, the object devises its own method
of allocating and freeing storage for the controlled sequence.
void freeze(bool freezeit = true);
If freezeit is true, the function alters the stored
strstreambuf mode to make the
controlled sequence frozen. Otherwise, it makes the controlled
sequence not frozen.
streamsize pcount();
The member function returns a count of the number of elements
written to the controlled sequence. Specifically, if
pptr() is a
null pointer, the function returns zero. Otherwise, it returns
pptr() -
pbase().
virtual int overflow(int meta = EOF);
If meta != EOF,
the protected virtual member function endeavors to insert the element
(char)meta
into the
output buffer.
It can do so in various ways:
- If a write position
is available, it can store the element into the write position
and increment the next pointer for the output buffer.
- If the stored
strstreambuf mode says the
controlled sequence is modifiable, extendable, and not frozen,
the function can make a write position available by allocating
new for the output buffer. (Extending the
output buffer this way also extends any associated
input buffer.)
If the function cannot succeed, it returns
EOF. Otherwise, if meta == EOF it returns some
value other than EOF. Otherwise, it returns meta.
virtual int pbackfail(int meta = EOF);
The protected virtual member function endeavors to put back an element
into the
input buffer,
then make it the current element (pointed to
by the next pointer).
If meta == EOF,
the element to push back is effectively the one already in the stream
before the current element. Otherwise, that element is replaced by
ch = (char)meta.
The function can put back an element in various ways:
- If a putback position
is available, and the element stored there compares equal to
ch,
it can simply decrement the next pointer for the input buffer. - If a putback position is available,
and if the strstreambuf mode
says the controlled sequence is modifiable, the function
can store
ch into the putback position and decrement the
next pointer for the input buffer.
If the function cannot succeed, it returns
EOF. Otherwise, if meta == EOF it returns some
value other than EOF. Otherwise, it returns meta.
virtual streampos seekoff(streamoff off,
ios_base::seekdir way,
ios_base::openmode which =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
strstreambuf, a stream position consists
purely of a stream offset. Offset zero designates the first element
of the controlled sequence.
The new position is determined as follows:
- If
way ==
ios_base::beg,
the new position is the beginning of the stream plus off. - If
way ==
ios_base::cur,
the new position is the current stream position plus off. - If
way ==
ios_base::end,
the new position is the end of the stream plus off.
If
which & ios_base::in is nonzero and
the input buffer exist,
the function alters the next position to read in the
input buffer.
If which & ios_base::out is also nonzero,
way != ios_base::cur,
and the output buffer exists,
the function also sets the next position to write to
match the next position to read.
Otherwise, if which & ios_base::out is nonzero
and the output buffer exists,
the function alters the next position to write in the
output buffer.
Otherwise, the positioning operation fails.
For a positioning operation to succeed, the resulting
stream position must lie within the controlled sequence.
If the function succeeds in altering either or both stream positions,
it returns the resultant stream position.
Otherwise, it fails and returns an invalid stream position.
virtual streampos seekpos(streampos sp,
ios_base::openmode which =
ios_base::in | ios_base::out);The protected virtual member function endeavors to alter the current
positions for the controlled streams. For an object of class
strstreambuf, a stream position consists
purely of a stream offset. Offset zero designates the first element
of the controlled sequence. The new position is determined
by sp.
If
which & ios_base::in is nonzero
and the input buffer exists,
the function alters the next position to read in the
input buffer.
(If which & ios_base::out is nonzero
and the output buffer exists,
the function also sets the next position to write to
match the next position to read.)
Otherwise, if which & ios_base::out is nonzero
and the output buffer exists,
the function alters the next position to write in the
output buffer.
Otherwise, the positioning operation fails.
For a positioning operation to succeed, the resulting
stream position must lie within the controlled sequence.
If the function succeeds in altering either or both stream positions,
it returns the resultant stream position.
Otherwise, it fails and returns an invalid stream position.
char *str();
The member function calls
freeze(), then
returns a pointer to the beginning of the controlled sequence.
(Note that no terminating null element exists, unless you insert
one explicitly.)
explicit strstreambuf(streamsize count = 0);
strstreambuf(void (*allocfunc)(size_t),
void (*freefunc)(void *));
strstreambuf(char *getptr, streamsize count,
char *putptr = 0);
strstreambuf(signed char *getptr, streamsize count,
signed char *putptr = 0);
strstreambuf(unsigned char *getptr, streamsize count,
unsigned char *putptr = 0);
strstreambuf(const char *getptr, streamsize count);
strstreambuf(const signed char *getptr, streamsize count);
strstreambuf(const unsigned char *getptr, streamsize count);The first constructor stores a null pointer in all the pointers
controlling the
input buffer, the
output buffer, and
strstreambuf allocation.
It sets the stored
strstreambuf mode to make the
controlled sequence modifiable and extendable.
And it accepts count as a suggested initial allocation size.
The second constructor behaves much as the first, except that
it stores allocfunc as the pointer to the function to
call to allocate storage, and freefunc as the pointer
to the function to call to free that storage.
The three constructors:
strstreambuf(char *getptr, streamsize count,
char *putptr = 0);
strstreambuf(signed char *getptr, streamsize count,
signed char *putptr = 0);
strstreambuf(unsigned char *getptr, streamsize count,
unsigned char *putptr = 0);also behave much as the first, except that getptr
designates the array object used to hold the controlled
sequence. (Hence, it must not be a null pointer.) The number
of elements N in the array is determined as
follows:
- If
(count > 0), then N is count. - If
(count == 0), then N is
strlen((const char *)getptr). - If
(count < 0), then N is
INT_MAX.
If putptr is a null pointer, the function establishes
just an input buffer, by executing:
setg(getptr, getptr, getptr + N);
Otherwise, it establishes both input and output buffers, by
executing:
setg(getptr, getptr, putptr);
setp(putptr, getptr + N);
In this case, putptr must be in the interval
[getptr, getptr + N].
Finally, the three constructors:
strstreambuf(const char *getptr, streamsize count);
strstreambuf(const signed char *getptr, streamsize count);
strstreambuf(const unsigned char *getptr, streamsize count);
all behave the same as:
streambuf((char *)getptr, count);
except that the stored mode makes the controlled sequence neither
modifiable not extendable.
virtual int underflow();
The protected virtual member function endeavors to extract the current
element ch from the
input buffer,
then advance the current stream position, and return the element as
(int)(unsigned char)ch.
It can do so in only one way:
If a read position
is available, it takes ch as the element stored
in the read position and advances the next pointer for the input buffer.
If the function cannot succeed, it returns
EOF. Otherwise,
it returns the current element in the input stream,
converted as described above.
class istrstream : public istream {
public:
explicit istrstream(const char *ptr);
explicit istrstream(char *ptr);
istrstream(const char *ptr, streamsize count);
istrstream(char *ptr, streamsize count);
strstreambuf *rdbuf() const;
char *str();
};The class describes an object that controls
extraction of elements and encoded objects from a
stream buffer of class
strstreambuf.
The object stores an ojbect of class
strstreambuf.
explicit istrstream(const char *ptr);
explicit istrstream(char *ptr);
istrstream(const char *ptr, streamsize count);
istrstream(char *ptr, streamsize count);
All the constructors initialize the base class by calling
istream(sb),
where sb is the stored object of class
strstreambuf.
The first two constructors also initialize sb by calling
strstreambuf((const
char *)ptr, 0). The remaining two constructors instead call
strstreambuf((const char *)ptr, count).
strstreambuf *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
strstreambuf.
char *str();
The member function returns
rdbuf()->
str().
class ostrstream : public ostream {
public:
ostrstream();
ostrstream(char *ptr, streamsize count,
ios_base::openmode mode = ios_base::out);
strstreambuf *rdbuf() const;
void freeze(bool freezeit = true);
char *str();
streamsize pcount() const;
};The class describes an object that controls
insertion of elements and encoded objects into a
stream buffer of class
strstreambuf.
The object stores an ojbect of class
strstreambuf.
void freeze(bool freezeit = true)
The member function calls
rdbuf()->
freeze(freezeit).
ostrstream();
ostrstream(char *ptr, streamsize count,
ios_base::openmode mode = ios_base::out);Both constructors initialize the base class by calling
ostream(sb),
where sb is the stored object of class
strstreambuf.
The first constructor also initializes sb by calling
strstreambuf().
The second constructor initializes the base class one of two ways:
- If
mode &
ios_base::app == 0, then
ptr must designate the first element of an array of count
elements, and the constructor calls
strstreambuf(ptr, count, ptr). - Otherwise,
ptr must designate the first element of an
array of count elements that contains a
C string
whose first element is designated
by ptr, and the constructor calls
strstreambuf(ptr, count, ptr +
strlen(ptr).
streamsize pcount() const;
The member function returns
rdbuf()->
pcount().
strstreambuf *rdbuf() const
The member function returns the address of the stored
stream buffer, of type pointer to
strstreambuf.
char *str();
The member function returns
rdbuf()->
str().
See also the
Table of Contents and the
Index.
Copyright © 1992-2002
by P.J. Plauger. All rights reserved.
62 - time
<time.h>
Note for Green Hills Software customers:
Green Hills Software tools provide their own version of this file in
the Green Hills Software C Library. They does not use the version normally
provided by the Dinkumware libraries.
For documentation pertaining to this
file, please instead refer to documentation provided in the "manuals" directory
of your Green Hills Software compiler installation.
See also the
Table of Contents and the
Index.
Copyright © 1989-2002
by P.J. Plauger and Jim Brodie. All rights reserved.