                                       C                      Compaq_C++____________________________________ 3                      Class Library Reference Manual   .                      Order Number: AA-PY3EB-TK                          June 1999  F                      This document describes a library of C++ classes.          C                      Revision/Update Information: This is a revised 9                                                   manual.   D                      Software Version:            C++ Version 5.3 or7                                                   later C                                                   C++ Class Library =                                                   Version 4.0                 0                      Compaq Computer Corporation#                      Houston, Texas                  H               __________________________________________________________,               First Printing, September 1992'               First Revision, June 1993 )               Second Revision, April 1996 '               Third Revision, June 1999   C               The information in this document is subject to change H               without notice and should not be construed as a commitmentA               by Digital Equipment Corporation. Digital Equipment G               Corporation assumes no responsibility for any errors that *               may appear in this document.  H               The software described in this document is furnished underD               a license and may be used or copied only in accordance-               with the terms of such license.   E               No responsibility is assumed for the use or reliability F               of software on equipment that is not supplied by Digital@               Equipment Corporation or its affiliated companies.  G               Restricted Rights: Use, duplication, or disclosure by the H               U.S. Government is subject to restrictions as set forth inE               subparagraph (c)(1)(ii) of the Rights in Technical Data A               and Computer Software clause at DFARS 252.227-7013.   7               1993-1999 Digital Equipment Corporation.   "               All Rights Reserved.  @               Compaq, the Compaq logo, and Alpha, DEC, DEC FUSE,@               DECthreads, DIGITAL, OpenVMS, ULTRIX, VAX, VMS are=               Registered in U.S. Patent and Trademark Office.   7               The following are third-party trademarks:   D               AT&T is a registered trademark of American Telephone &                Telegraph Company.  E               UNIX is a registered trademark in the United States and B               other countries, licensed exclusively through X/Open               Company, Ltd.   3               This document is available on CD-ROM.   H                                                                   ZK6026  C               This document was prepared using DECdocument, Version                3.2-1M.                                E      ________________________________________________________________   E                                                              Contents     E      Preface..................................................    vii           1  Overview  E          1.1  Thread Safe Programming.........................    1-1         2  complex Package   E               Global Declarations.............................    2-2   E               complex class...................................    2-4   E               c_exception class...............................   2-11         3  generic Package   E               Global Declarations.............................    3-3         4  iostream Package  E               Global Declarations.............................    4-5   E               filebuf class...................................   4-14   E               fstream class...................................   4-19   E               IAPP(TYPE) class................................   4-22   E               ifstream class..................................   4-24   E               IMANIP(TYPE) class..............................   4-27   E               IOAPP(TYPE) class...............................   4-29   E               IOMANIP(TYPE) class.............................   4-31   E               ios class.......................................   4-33   E               iostream class..................................   4-46   E               iostream_withassign class.......................   4-48   E               istream class...................................   4-50   E                                                                   iii                  H                 istream_withassign class........................    4-58  H                 istrstream class................................    4-60  H                 OAPP(TYPE) class................................    4-62  H                 ofstream class..................................    4-64  H                 OMANIP(TYPE) class..............................    4-67  H                 ostream class...................................    4-69  H                 ostream_withassign class........................    4-74  H                 ostrstream class................................    4-76  H                 SAPP(TYPE) class................................    4-78  H                 SMANIP(TYPE) class..............................    4-79  H                 stdiobuf class..................................    4-81  H                 stdiostream class...............................    4-84  H                 streambuf class.................................    4-87  H                 strstream class.................................    4-99  H                 strstreambuf class..............................   4-101           5  Messages Package   H                 Messages class..................................     5-2           6  Mutex Package  H                 Mutex class.....................................     6-2           7  Objection Package  H                 Global Declaration..............................     7-2  H                 Objection class.................................     7-3           8  Stopwatch Package  H                 Stopwatch class.................................     8-2  
         iv                          9  String Package   H                 String class....................................     9-2           10  task Package  H                 Global Declarations.............................    10-3  H                 erand class.....................................    10-7  H                 histogram class.................................    10-9  H                 Interrupt_handler class.........................   10-12  H                 object class....................................   10-16  H                 qhead class.....................................   10-20  H                 qtail class.....................................   10-26  H                 randint class...................................   10-31  H                 sched class.....................................   10-33  H                 task class......................................   10-39  H                 timer class.....................................   10-45  H                 urand class.....................................   10-49           11  vector Package  H                 stack(TYPE) class...............................    11-3  H                 vector(TYPE) class..............................    11-7  
         Index            Figures   7            4-1     Inheritance Diagram for the iostream H                    Package.......................................    4-2  H            10-1    Inheritance Diagram for the task Package .....   10-1  H                                                                        v                          Tables  H            1       Conventions Used in this Manual ..............     ix                                                                                    
         vi                           H         ________________________________________________________________  H                                                                  Preface      H               This manual describes the library of classes supplied withG               C++ Version 5.6 for OpenVMS systems. It contains detailed G               information on members of these classes (including member G               functions) and information on other associated functions, $               variables, and macros.           Intended Audience   E               This manual is intended for experienced programmers who A               have a basic understanding of the C++ language, and D               who are using C++ with the OpenVMS operating system inD               either a single or multiple platform environment. Some?               familiarity with the operating system is assumed.            Document Structure  D               This manual consists of an introductory chapter and 10D               chapters describing each of the packages of predefined5               classes supplied with the C++ compiler.            Associated Documents  D               The following documents contain information related to               this manual:  1               o  Using Compaq C++ for OpenVMS VAX   F                  This manual supplies information needed to use C++ on!                  OpenVMS systems.   D               o  Stroustrup, Bjarne. Stroustrup, The C++ ProgrammingF                  Language, 3nd Edition, Addison-Wesley, 1997. Reading,5                  Massachusetts. Addison-Wesley, 1997.   H                                                                      vii                 G                  This text combines a user guide and language reference                   manual.  E               o  Stroustrup, Bjarne and Margaret Ellis. The Annotated G                  C++ Reference Manual. Reading, Massachusetts. Addison-                   Wesley, 1990.  F                  This text contains the current language definition of                  C++.                                                                                  viii                 H               o  C Run-Time Library Reference Manual for OpenVMS Systems  G                  This manual describes C run-time library routines that '                  are supported for C++.   >               o  Compaq C++ Installation Guide for OpenVMS VAX  F                  This guide supplies information needed to ensure thatD                  the C++ Class Library installs correctly on OpenVMS?                  systems and is accessible to the C++ compiler.            Conventions   @               Table 1 lists the conventions used in this manual.  H               Table_1_Conventions_Used_in_this_Manual___________________  H               Conventions_____________Meaning___________________________  H               class complex {         A vertical ellipsis indicates thatF                     .                 some intervening program code orH                     .                 output is not shown. Only the moreH                     .                 pertinent material is shown in the.               };                      example.  G               , . . .                 A horizontal ellipsis in a syntax D                                       description indicates that youF                                       can enter additional parameters,A                                       options, or values. A comma F                                       preceding the ellipsis indicatesC                                       that successive items must be :                                       separated by commas.  G               The complex class . . . Monospaced type denotes the names H                                       of C++ language elements, and alsoD               The get() func-         the names of classes, members,H               tion . . .              and nonmembers. Monospaced type isD                                       also used in text to reference@                                       code elements displayed in/                                       examples.   H                                                 (continued on next page)      H                                                                       ix                 H               Table_1_(Cont.)_Conventions_Used_in_this_Manual___________  H               Conventions_____________Meaning___________________________  C               italic                  Italic type denotes the names A                                       of variables that appear as C                                       parameters or in arguments to 0                                       functions.  E               boldface                Boldface type in text indicates A                                       the first instance of terms H               ________________________defined_in_text.__________________           Reader's Comments   F               You may send your comments or suggestions regarding thisD               manual, or any C++ document, by electronic mail to the)               following Internet address:   '                     cxx_docszko.dec.com                                                   	         x                        H                                                                        1H         ________________________________________________________________  H                                                                 Overview      G               The C++ Class Library is a set of headers and other files D               implementing a collection of basic C++ classes. In theA               library, these classes are arranged in functionally -               related groups called packages.   C               The DEC C++ Class Library makes use of other run-time                libraries.  F                 ________________________Note  ________________________  D                 Identifiers beginning with cxxl or CXXL are reservedD                 for the DEC C++ Class Library and should not be used@                 by customer programs except as specified in this                 manual.   C                 Error message examples in this manual are displayed ?                 without their OpenVMS facility, error severity, @                 or message identification code prefixes. You canA                 achieve this result by entering the following DCL                  command:  .                 $ set message/nofac/nosev/noid  E                 _____________________________________________________   #         1.1 Thread Safe Programming   F               Developers of multithreaded applications should note the               following:  E               o  Internal class library data is thread safe; multiple D                  threads can access the DEC C++ Class Library simul-D                  taneously without compromising the integrity of the                  internal data.   H                                                             Overview 1-1                    Overview#         1.1 Thread Safe Programming   D               o  The predefined stream objects, cerr, cin, clog, andC                  cout are thread safe. However, you need to provide H                  synchronization around sequences of operations on theseF                  objects. For more information on synchronizing accessA                  to the predefined stream objects, see Chapter 4.   E               o  User-defined objects are not thread safe; users must A                  provide synchronization for such objects if they D                  are shared between threads. For more information onB                  synchronizing access to user-defined objects, see                  Chapter 6.   @               o  The ios class member function sync_with_stdio()C                  is not thread safe; if your application calls this H                  function, the call must come before any threads use theE                  predefined stream objects: cerr, cin, clog, or cout.   G               o  Generation of error messages within the vector package A                  is not thread safe; the package uses static data_@                  members to handle the current error message andE                  there is no synchronization between threads. Digital D                  recommends that you define a single Mutex object to;                  synchronize all use of the vector package.   G               o  The task package is not thread safe; only one task can #                  execute at a time.l                                               1-2 Overview s                     H                                                                        2H         ________________________________________________________________  H                                                          complex Package      G               The complex package provides ways to perform arithmetical D               operations, such as initialization, assignment, input,B               and output, on complex values (that is, numbers withD               a real part and an imaginary part). Additionally, thisD               package supports operations that are unique to complexF               values, such as principal argument operations, conjugateH               operations, and conversions to and from polar coordinates.  F               With the c_exception class and its c_exception function,?               the complex package also provides a mechanism foriA               reporting and handling complex arithmetical errors.c                                                H                                                      complex Package 2-1 o  u               Global Declarationss    H         ________________________________________________________________           Global Declarationse  D               These declarations are used by the complex package but8               they are not members of the complex class.           Header  $               #include <complex.hxx>                  Alternative Header  "               #include <complex.h>           Declarations  N         typedef int (*cxxl_p_complex_error_t)(c_exception &error_information);)         static const complex_zero (0, 0);eG         cxxl_p_complex_error_t set_complex_error(cxxl_p_complex_error_to         p_complex_error);A           Type  $               cxxl_p_complex_error_t8               Is the type of the complex_error function.           Data  .               static const complex_zero (0, 0)F               Is a constant object of type complex and value 0 created;               in each module that uses the complex package.n           Function  G               cxxl_p_complex_error_t set_complex_error (cxxl_p_complex_e&               error_t p_complex_error)E               Causes the function pointed to by p_complex_error to besH               called instead of the complex_error function on subsequentA               complex arithmetical errors. If set_complex_error()d@               previously has not been called, then it returns 0;D               otherwise, it returns the address of the last function               passed to it.              2-2 complex Package            H                                                      Global Declarations    G               See the Other Function section of c_exception class for aa9               description of the error-handling function.a                                                                                      H                                                      complex Package 2-3                    complex class.    H         ________________________________________________________________           complex class.  @               Provides a representation of, and lets you perform,               operations on, complex values.           Header  $               #include <complex.hxx>                  Alternative Header  "               #include <complex.h>           Declaration.                 class complexT               {.=                   friend complex   polar(double, double = 0);s8                   friend double    abs(const complex &);9                   friend double    norm(const complex &); 8                   friend double    arg(const complex &);9                   friend double    arg1(const complex &);.9                   friend complex   conj(const complex &);.8                   friend complex   sin(const complex &);Q                   friend complex   sinh(const complex &); // c_exception OVERFLOWm8                   friend complex   cos(const complex &);Q                   friend complex   cosh(const complex &); // c_exception OVERFLOW 8                   friend complex   tan(const complex &);9                   friend complex   tanh(const complex &);.9                   friend double    imag(const complex &);m9                   friend double    real(const complex &); L                   friend complex   log(const complex &); // c_exception SING3                   // c_exception OVERFLOW UNDERFLOW 8                   friend complex   exp(const complex &);@                   friend complex   pow(double, const complex &);=                   friend complex   pow(const complex &, int);i@                   friend complex   pow(const complex &, double);I                   friend complex   pow(const complex &, const complex &); 9                   friend complex   sqrt(const complex &); 8                   friend complex   sqr(const complex &);>                   friend complex   operator-(const complex &);O                   friend complex   operator+(const complex &, const complex &);.           2-4 complex Package            H                                                            complex class    O                   friend complex   operator-(const complex &, const complex &);cO                   friend complex   operator*(const complex &, const complex &); O                   friend complex   operator/(const complex &, const complex &); P                   friend int       operator==(const complex &, const complex &);P                   friend int       operator!=(const complex &, const complex &);K                   friend ostream   &operator<<(ostream &, const complex &);.E                   friend istream   &operator>>(istream &, complex &);                  public:s  ?                                    complex(double, double = 0); -                                    complex();   @                   inline complex   &operator-=(const complex &);@                   inline complex   &operator+=(const complex &);@                   complex          &operator*=(const complex &);@                   complex          &operator/=(const complex &);               };           Description.  B               This class contains methods to perform complex valueE               operations. These include arithmetical, assignment, and.D               comparison operators for complex values; Cartesian andH               polar coordinates; mixed-mode arithmetic; and mathematicalA               functions for complex values equivalent to standard.%               mathematical functions.            Exception Handling  A               When a complex arithmetical error is detected, a c_cC               exception object is created with one of the following                values for type:  H               __________________________________________________________H               Value________Error_Description____________________________  <               OVERFLOW     Value too large to be represented  :               SING         Function undefined for argument  H               UNDERFLOW____Value_too_small_to_be_represented____________  F               This object is then passed to the complex_error function*               (see the c_exception class).  H                                                      complex Package 2-5                    complex class       $         Constructors and Destructors                 complex() >               Constructs and initializes a complex value to 0.  -               complex(double x, double y = 0) G               Constructs and initializes a complex value from Cartesian                coordinates.           Overloaded Operators  B               complex operator + (const complex &z1, const complex               &z2)G               Returns the arithmetical sum of the complex values z1 ande               z2.   4               complex operator - (const complex &z1)C               Returns the arithmetical negation of a complex value.g  B               complex operator - (const complex &z1, const complex               &z2)D               Returns the arithmetical difference of complex values.0               That is, z2 is subtracted from z1.  B               complex operator * (const complex &z1, const complex               &z2)G               Returns the arithmetical product of the complex values z1                and z2.m  B               complex operator / (const complex &z1, const complex               &z2)G               Returns the arithmetical quotient of complex values. Thats&               is, z1 is divided by z2.  =               inline complex &operator += (const complex &z1)nC               Assigns the arithmetical sum of complex values to the F               complex object on the left side of an equation. That is,/               z1+=z2 is equivalent to z1=z1+z2.   =               inline complex &operator -= (const complex &z1) H               Assigns the arithmetical difference of two complex numbersD               to the complex object on the left side of an equation.8               That is, z1-=z2 is equivalent to z1=z1-z2.           2-6 complex Packagee n         H                                                            complex class    6               complex &operator *= (const complex &z2)H               Assigns the arithmetical product of two complex numbers toF               the complex object on the left side of an equation. That3               is, z1*=z2 is equivalent to z1=z1*z2.   6               complex &operator /= (const complex &z2)F               Assigns the arithmetical quotient of two complex numbersD               to the complex object on the left side of an equation.8               That is, z1/=z2 is equivalent to z1=z1/z2.  B               ostream &operator << (ostream &s, const complex &z1)E               Sends a complex value to an output stream in the formatl:               (real,imag). It returns the left argument s.  <               istream &operator >> (istream &s, complex &z1)E               Takes a complex value from an input stream. The numbersfG               may be of the forms (real,imag) or (real), where real andsG               imag are what the iostream library accepts for parameters F               of type double. The iostream library also determines howC               to handle white space. This operator returns the leftnC               argument s. The following input format omissions willi               cause an error:_  ;               o  Parenthesis missing before a complex valuee  E               o  Comma missing before the imaginary part of a complexe                  value, if any  <               o  Parenthesis missing after the complex value  ?               int operator == (const complex &z1, const complex                &z2)H               Compares two complex values and returns a nonzero value ifA               the two numbers are equal; otherwise, it returns 0.   ?               int operator != (const complex &z1, const complex                &z2)H               Compares two complex values and returns a nonzero value ifE               the two numbers are not equal; otherwise, it returns 0.             H                                                      complex Package 2-7 b                  complex class                Other Functions   +               double abs(const complex &z1)dH               Returns the absolute value (magnitude) of a complex value.  +               double arg(const complex &z1)(D               Returns the angle, in radians, of a complex value. TheH               result is normalized such that it is greater than or equal%               to 0, and less than 2*.f  ,               double arg1(const complex &z1)F               Returns the principal value of the angle, in radians, ofG               a complex value. The result is normalized such that it isp9               greater than -, and less than or equal to .   -               complex conj(const complex &z1) G               Returns the conjugate of a complex value; that is, if the                number is_=               (real, imag), then the result is (real, -imag).t  ,               complex cos(const complex &z1)4               Returns the cosine of a complex value.  -               complex cosh(const complex &z1) ?               Returns the hyperbolic cosine of a complex value. @               The value of real(z1) must be small enough so thatF               exp(real(z1)) does not overflow; otherwise, the functionH               creates a c_exception object and invokes the complex_error               function._  ,               complex exp(const complex &z1)E               Returns the value of e (2.71828...) raised to the power E               of a complex value. The conditions described for cosh()oE               must be met; otherwise, it creates a c_exception object 5               and invokes the complex_error function.   ,               double imag(const complex &z1)<               Returns the imaginary part of a complex value.  ,               complex log(const complex &z1)E               Returns the natural logarithm (base e, 2.71828...) of a E               complex value. The conditions described for cosh() musta             2-8 complex Package            H                                                            complex class    D               be met; otherwise, it creates a c_exception object and1               invokes the complex_error function.   ,               double norm(const complex &z1)G               Returns the square of the absolute value (magnitude) of a_               complex value.  9               complex polar(double rho, double theta = 0)dG               Creates a complex value given a pair of polar coordinates :               (magnitude rho and angle theta, in radians).  4               complex pow(const complex &z1, int i2)@               Returns the value of z1 raised to the power of i2.  7               complex pow(const complex &z1, double x2) @               Returns the value of z1 raised to the power of x2.  7               complex pow(double z1, const complex &z2) @               Returns the value of z1 raised to the power of z2.  ?               complex pow(const complex &z1, const complex &z2)_@               Returns the value of z1 raised to the power of z2.  ,               double real(const complex &z1)7               Returns the real part of a complex value.t  ,               complex sin(const complex &z1)2               Returns the sine of a complex value.  -               complex sinh(const complex &z1)wA               Returns the hyperbolic sine of a complex value. The E               conditions described for cosh() must be met; otherwise,vF               it creates a c_exception object and invokes the complex_               error function.e  ,               complex sqr(const complex &z1)4               Returns the square of a complex value.  -               complex sqrt(const complex &z1)n9               Returns the square root of a complex value.o  ,               complex tan(const complex &z1)5               Returns the tangent of a complex value.,    H                                                      complex Package 2-9 e  m               complex classe    -               complex tanh(const complex &z1) D               Returns the hyperbolic tangent of a complex value. TheE               conditions described for cosh() must be met; otherwise, F               it creates a c_exception object and invokes the complex_               error function.i             Examples  "               1. complex zz(3,-5);  F                  Declares zz to be a complex object and initializes itC                  to the value of real part 3 and imaginary part -5.   %               2. complex myarray[30];   F                  Declares an array of 30 complex objects, all initial-                  ized to (0,0).                  3. complex zz;*                 while (!(cin >> zz).eof())'                     cout << zz << endl;i  ?                  Reads a stream of complex values [for example,oD                  (3.400000,5.000000)] and writes them in the default0                  format [for example, (3.4, 5)].  .               4. complex cc = complex (3.4,5);<                 cout << real(cc) << "+" << imag(cc) << "*i";  H                  Prints out 3.4 as the real part of a complex object and@                  5 as the imaginary part. The result is 3.4+5*i.                                   2-10 complex Package           H                                                        c_exception class    H         ________________________________________________________________           c_exception class   G               Contains information on a complex arithmetical exception.u           Header  $               #include <complex.hxx>                  Alternative Header  "               #include <complex.h>           Declaration                  class c_exception                {n8                   friend complex   exp(const complex &);9                   friend complex   sinh(const complex &);c9                   friend complex   cosh(const complex &);h8                   friend complex   log(const complex &);@                   friend int       complex_error(c_exception &);                 public: (                   int              type;)                   char             *name;2(                   complex          arg1;(                   complex          arg2;*                   complex          retval;                 public:n<                   c_exception(char *, const complex &, const,                   complex & = complex_zero);               };           Descriptionr  A               Objects of this class handle exceptions for complex A               arithmetic. This includes information on functions,sA               parameters, error types, and default return values.r        H                                                     complex Package 2-11 r  t               c_exception class_               Data Members                 complex arg1D               Is the left argument of the function that incurred the               error.                 complex arg2E               Is the right argument of the function that incurred thet               error.                 char *nameB               Is the name of the function that incurred the error.                 complex retvalG               Is the value to be returned by the function that incurredpE               the error. You may use the complex_error(c_exception &)r,               function to change this value.                 int type@               Is one of these kinds of error: SING, OVERFLOW, or               UNDERFLOW.           Constructorb  G               c_exception(char *function_name, const complex &function_r@               arg1, const complex &function_arg2 = complex_zero)F               Constructs a complex arithmetical exception object, withF               reference to the name and arguments of the function that!               incurred the error.s           Other Function  @               int complex_error (c_exception &error_information)F               Is the default error-handling function that is called byD               certain complex arithmetical functions in this packageE               (namely, cosh, exp, log, and sinh) when those functions_@               detect an arithmetical error. You may replace thisE               function with your own function that takes an identical D               parameter list and returns a value as specified in the               following table:                 2-12 complex Package           H                                                        c_exception class  H               __________________________________________________________               Return Value fromuH               Error-handling        Action Taken by Complex ArithmeticalH               Function______________Function____________________________  F                        0            Set the global value errno; if theF                                     error type is SING, print an error,                                     message.  E                     non 0           Do not set errno; do not print an H               ______________________error_message.______________________  B               To substitute your own error-handling function, passA               a pointer to your function to the set_complex_error >               function. (See the Function section under Global4               Declarations for the complex package.)  F               The complex arithmetical functions that invoke the errorD               handling function always return the value specified inH               error_information.retval. Your error-handling function may               set this value.                                                   H                                                     complex Package 2-13                       H                                                                        3H         ________________________________________________________________  H                                                          generic Package      C               The generic package provides ways to simulate parame- B               terized types by allowing the instantiation of class@               declarations using the macro facilities of the C++H               preprocessor. You can use the generic package to constructE               container classes. The actual types of the data members H               are passed at compile time as parameters to the class when%               you use the class name.   (               To declare a generic type:  F               1. Define a name for the class and specify the number of!                  type parameters:d  =                  #define YOUR_CLASS_NAME(TYPE_PARAMETER_NAME) =                   name2(TYPE_PARAMETER_NAME, YOUR_CLASS_NAME)   E                  To specify two type parameters, use the name3 macro.)  2               2. Define the class body as a macro:  R                  #define YOUR_CLASS_NAMEdeclare(TYPE_PARAMETER_NAME) class { . . .
         };M                  #define YOUR_CLASS_NAMEimplement(TYPE_PARAMETER_NAME)  . . .   *               3. Declare the actual class:  ;                  declare(YOUR_CLASS_NAME, ACTUAL_TYPE_NAME)&  E                  By substituting one or another class of ACTUAL_TYPE_ H                  NAME, you can declare multiple instances of the genericA                  class template with various component types. FornB                  example, depending on the type parameter you use,D                  you can declare such types as list of ints, list of6                  Strings, or list of lists of Strings.  E                  If it is not a type name, ACTUAL_TYPE_NAME must be ah                  typedef name.  H                                                      generic Package 3-1 e  a            H                  You must do this in each compilation unit that uses the;                  parameterized type with a given parameter._  B               4. Define the functions or static data of the actual                  class._  =                  implement(YOUR_CLASS_NAME, ACTUAL_TYPE_NAME)r  D                  You must do this once in each program that uses the;                  parameterized type with a given parameter.t  F               5. Declare an instance of the class you have declared byH                  specifying objects of type YOUR_CLASS_NAME(ACTUAL_TYPE_#                  NAME), as follows:   D                  YOUR_CLASS_NAME(ACTUAL_TYPE_NAME) object1, object2;                                                                   3-2 generic Packagea i  i      H                                                      Global Declarations    H         ________________________________________________________________           Global Declarations   D               These declarations are used by the generic package but0               they are not members of any class.           Header  $               #include <generic.hxx>                  Alternative Header  "               #include <generic.h>           Compile-Time Parameters   ?               TYPE, TYPE1, TYPE2-The types for which this class @               is parameterized; TYPE, TYPE1, or TYPE2 must be an               identifier.rD               CLASS-The class that is parameterized. For a vector ofE               integers, for example, CLASS is vector and TYPE is int.            Declarations  /               typedef int  (*GPT)(int, char *);c:               int          genericerror(int n, char *msg);           Type                 GPT(@               Is a pointer to a generic error-handling function.           Function  1               int genericerror (int n, char *msg) H               Is the default error-handling function; it prints an errorE               number (n) and message (msg) on cerr and calls abort().e           Macros  C               Macros provide preprocessor facilities for simulating G               parameterized types. The following macros are defined forc"               the generic package:  H                                                      generic Package 3-3                    Global Declarationst    *               callerror(CLASS, TYPE, N, S)E               Calls the current error handler for a given instance of B               a parameterized class. CLASS denotes the name of theC               generic class (for example, vector). TYPE denotes thepG               type parameter for which to instantiate the generic classuF               (for example, int to get a vector of integers); the typeH               must be an identifier (for example, char* is not valid). NF               denotes the first argument to pass to the error handler;E               the default is the function genericerror(int, char*). SmG               denotes the second argument to pass to the error handler.z  "               declare(CLASS, TYPE)F               Declares the class specified by a macro with the name ofH               the generic class. The word declare follows the class nameF               (for example, vectordeclare). It also defines the inlineF               member functions of the class. CLASS denotes the name ofG               the generic class (for example, vector). TYPE denotes the G               type parameter for which to instantiate the generic classoF               (for example, int to get a vector of integers). The typeF               must be an identifier (for example, char* is not valid).  *               declare2(CLASS, TYPE1,TYPE2)C               Declares the class specified by a macro with the name D               of the generic class. The name is followed by the wordC               declare2. The declare2 macro differs from the declarer?               macro only in that you use it to declare two type *               parameters, TYPE1 and TYPE2.  '               errorhandler(CLASS, TYPE)nC               Is the name of the pointer to the error handler for apC               given instance of a parameterized class (for example, ?               intvectorhandler to handle errors for a vector of D               integers). CLASS denotes the name of the generic classD               (for example, vector). TYPE denotes the type parameterF               for which to instantiate the generic class (for example,C               int to get a vector of integers). The type must be an ;               identifier (for example, char* is not valid).   $               implement(CLASS, TYPE)@               Defines the noninline member functions of a class,F               specified by a macro with the name of the generic class.F               The name is followed by the word implement (for example,               3-4 generic Package  e  t      H                                                      Global Declarations    B               vectorimplement). The implement macro takes the same-               arguments as the declare macro.n  ,               implement2(CLASS, TYPE1,TYPE2)@               Defines the noninline member functions of a class,?               specified by a macro with the name of the genericnE               class. The name is followed by the word implement2. TheeG               implement2 macro differs from the implement macro only in G               that you use it to declare two type parameters, TYPE1 andp               TYPE2.                 name2(S1,S2)@               Concatenates two identifier segments to form a new/               identifier using the ## operator.l                 name3(S1,S2,S3)uB               Concatenates three identifier segments to form a new/               identifier using the ## operator.                   name4(S1,S2,S3,S4)A               Concatenates four identifier segments to form a new /               identifier using the ## operator.   /               set_handler(CLASS, TYPE, HANDLER) C               Specifies a function as the current error handler fordC               a given instance of a parameterized class. Initially,cE               the error-handling function is set to genericerror(int, F               char*). CLASS denotes the name of the generic class (forC               example, vector). TYPE denotes the type parameter forsB               which to instantiate the generic class (for example,C               int to get a vector of integers); the type must be aniC               identifier (for example, char* is not valid). HANDLER F               denotes a pointer to the function you want to set to theH               new error handler. Also, you can use the set_handler macro6               in a function declaration or definition.                    H                                                      generic Package 3-5 l  (               Global Declarationsp               Example   E               The following program shows the use of the genericerror -               function and associated macros:                    extern "C"               { !               #include <stdlib.h>e!               #include <stddef.h>                 #include <stdio.h>               }o  $               #include <generic.hxx>  6               #define my_vector(T) name2(T, my_vector)  R               // Declare a vector of objects of type T (the class and extern data)+               #define my_vectordeclare(T) \ &                   class my_vector(T) \                   { \o                   private: \                       int s; \                       T *p; \e                   public: \b*                       my_vector(T)(int); \(                       ~my_vector(T)(); \+                       T &operator[](int); \)                   }; \:                   extern GPT errorhandler(my_vector, T); \<                   extern GPT set_handler(my_vector, T, GPT);                                   3-6 generic Packager d  r      H                                                      Global Declarations    8               // Implement a vector of objects of type T7               // (Define the functions and global data) -               #define my_vectorimplement(T) \ 8                   my_vector(T)::my_vector(T)(int size) \                   { \f!                       s = size; \ (                       p = new T[size]; \                   } \ 1                   my_vector(T)::~my_vector(T)() \                    { \ #                       delete[] p; \                    } \ 6                   T &my_vector(T)::operator[](int i) \                   { \y+                       if(i < 0 || i >= s) \                        { \bN                           callerror(my_vector, T, i, "Index out of bounds"); \2                           static T error_object; \0                           return error_object; \                       } \ $                       return p[i]; \                   } \eC                   GPT errorhandler(my_vector, T) = &genericerror; \ G                   GPT set_handler(my_vector, T, GPT new_genericerror) \e                   { \xJ                       GPT old_genericerror = errorhandler(my_vector, T); \F                       errorhandler(my_vector, T) = new_genericerror; \0                       return old_genericerror; \                   }x  4               // Declare and implement vector of int%               declare(my_vector, int) '               implement(my_vector, int)   (               // Error-handling function               my_handler(                    int n,                   char *msg                    ).            H                                                      generic Package 3-7    u               Global Declarations                    {m!                   fflush(stderr); ?                   printf("in my_handler(%d,\"%s\")\n", n, msg); !                   fflush(stdout);_                   return 0;_               }   .               int main(int argc, char *argv[])               {o(                   my_vector(int) v1(10);  (                   GPT old_error_handler;  F                   // Set the handler to a function that does not abortO                   old_error_handler = set_handler(my_vector, int, &my_handler);                     v1[12345] = 0;  ;                   // Restore the handler and cause an error(&                   // This should abortU                   old_error_handler = set_handler(my_vector, int, old_error_handler);m                    v1[12345] = 0;  &                   return EXIT_SUCCESS;               }u           See Also                 vector Package                                           3-8 generic Packagep                       H                                                                        4H         ________________________________________________________________  H                                                         iostream Package      G               Classes in the iostream package provide methods to handlecE               input and output streams, including reading and writingoF               built-in data types. You also can extend certain methods3               described here to handle class types.   F               This package includes, among others, the classes ios andC               streambuf, and the subclasses derived from these base H               classes. Figure 4-1 shows the inheritance structure of theE               iostream package. In the diagram, arrows point from thet.               base classes to derived classes.  H               The istream (input stream) class supports input operationsG               (extractions); the ostream (output stream) class supports @               output operations (insertions). The iostream classF               derives from both istream and ostream, and supports both)               extractions and insertions.   :               The following stream objects are predefined:  D               cin    An istream_withassign object linked to standard                      input  D               cout   An ostream_withassign object linked to standard                      outputn  D               cerr   An ostream_withassign object linked to standard:                      error that supports unbuffered output  D               clog   An ostream_withassign object linked to standard8                      error that supports buffered output  G               To generate output, you apply the insertion operator (<<)h9               to cout, as shown in the following example:o  !               cout << "Hello\n" ;p  H                                                     iostream Package 4-1                 ?         Figure 4-1 Inheritance Diagram for the iostream Packageu              E               Obtaining input is similar to generating output, exceptaD               that you apply the extraction operator (>>) to cin, as-               shown in the following example:                  int eye, jay ;!               cin >> eye >> jay ;p  B               If you include these fragments of code in a program,E               your system expects users to type in two integer values-E               (for eye and jay) from a terminal. The iostream packagecH               supplies predefined extraction and insertion operators for7               all built-in data types, including char*.   F               This package also supports file manipulation. To connectE               a specific file to your program, instantiate one of the $               following class types:                                                   4-2 iostream Package _               *                  ifstream (for file input)+                  ofstream (for file output) 4                  fstream (for both input and output)  E               To format within character arrays, the iostream packagef<               includes the following associated class types:  C                  istrstream (for fetching characters from an array)lB                  ostrstream (for storing characters into an array)D                  strstream (for both fetching and storing characters                  into an array)   F                 ________________________Note  ________________________  ?                 On systems with IEEE floating-point arithmetic, <                 certain values may be printed as symbols for@                 Infinity (for example, INF) or Not a Number (for                 example, NaN).  E                 _____________________________________________________   .               Deriving Your Own Class from ios  F               If you derive your own class from the ios class, or fromC               one of its derived classes, the ios subobject must berF               initialized properly during instantiation. Specifically,G               you must ensure that the streambuf pointer within the iosr!               subobject is valid.e  H               To do this, you can specify the ios(streambuf *) construc-E               tor as a member initializer for your class constructor.cH               Optionally, you can call the ios::init(streambuf *) member               function._                 Thread Safety   F               The predefined stream objects, cerr, cin, clog, and coutD               are thread safe only for individual calls into the DECH               C++ Class Library. You must provide synchronization aroundG               sequences of calls. For more information on synchronizing E               access to predefined stream objects, see the section on 2               Global Declarations in this chapter.  E               User-defined stream objects are not thread safe, so you B               must provide synchronization around individual callsA               as well as sequences of calls. For more informationrB               on synchronizing access to user-defined objects, see  H                                                     iostream Package 4-3                 F               Chapter 6 and the section on Global Declarations in this               chapter.  E               The ios member function sync_with_stdio() is not threadbD               safe. If your application calls this function, it mustF               make the call before any threads use cerr, cin, clog, or               cout.t                                                                                     4-4 iostream Package           H                                                      Global Declarations    H         ________________________________________________________________           Global Declarations   E               These declarations are used by the iostream package buti0               they are not members of any class.           Header  %               #include <iostream.hxx>                   Alternative Header  #               #include <iostream.h>            Declarations  '               typedef long    streamoffY'               typedef long    streampos   +               ios             &dec(ios &s); +               ios             &hex(ios &s); +               ios             &oct(ios &s); ,               ios             &lock(ios &s);.               ios             &unlock(ios &s);  .               istream         &ws(istream &i);0               ostream         &endl(ostream &o);0               ostream         &ends(ostream &o);1               ostream         &flush(ostream &o);e  
         Types   $               typedef long streamoffH               Is the type representing a character offset into a stream.F               For more information, see the description of the seekoff;               and seekpos functions in the streambuf class.   $               typedef long streamposH               Is the type representing a character position in a stream.F               For more information, see the description of the seekoff;               and seekpos functions in the streambuf class.       H                                                     iostream Package 4-5    (               Global Declarationse               Manipulators  B               The following functions insert values into a stream,E               extract values from a stream, or specify the conversion F               base format. For more information on the conversion base.               format flags, see the ios class.                 ios &dec(ios &s)?               Sets the conversion base format for s to decimal,gF               essentially clearing the ios::oct and ios::hex flags and(               setting the ios::dec flag.                 ios &hex(ios &s)C               Sets the conversion base format for s to hexadecimal,TF               essentially clearing the ios::oct and ios::dec flags and(               setting the ios::hex flag.                 ios &oct(ios &s)A               Sets the conversion base format for s to octal, es- D               sentially clearing the ios::dec and ios::hex flags and(               setting the ios::oct flag.  %               istream &ws(istream &i) =               Extracts (skips) white-space characters from i.l  '               ostream &endl(ostream &o)uF               Ends a line by inserting a new-line character into o and               flushing o.r  '               ostream &ends(ostream &o)gF               Ends a string by inserting a null '/0' character into o.  (               ostream &flush(ostream &o)               Flushes o.  9         Synchronizing Access to Predefined Stream Objectsw  D               The following unparameterized manipulators are for useG               in synchronizing access to the predefined stream objects,t(               cerr, cin, clog, and cout:                 4-6 iostream Package           H                                                      Global Declarations                   ios &lock(ios &s)vC               Locks s if s is one of the predefined stream objects.r  !               ios &unlock(ios &s) E               Unlocks s if s is one of the predefined stream objects.s  D               If your application needs to lock two or more of theseG               objects at the same time, your application must adhere tom*               the following locking order:                                                                        H                                                     iostream Package 4-7                    Global Declarations                    1. cin                 2. cerro                 3. clogf                 4. cout   F               For example, if your application needs to lock both cerrF               and cout, lock cerr first and cout second. The unlocking%               order is not important.r  D               Keep in mind that when your application calls a memberA               function for a predefined stream object, the membersF               function will typically lock the object for the durationH               of the call. Therefore, if your application has locked oneH               of the stream objects and then uses another, this use mustG               also adhere to the predefined locking order. For example,oH               your application should not send output to cerr while cout               is locked.  D               The locking order necessarily matches the default ties4               between the stream objects as follows:  $                  cin is tied to cout%                  cerr is tied to cout %                  clog is tied to cout !                  cout has no tiess  F               Any input/output operation on a stream object causes theG               iostream package to flush the object to which it is tied. 3               Thus, an output to cerr flushes cout.a           Examples  (               1. #include <iostream.hxx>&                 #include <iomanip.hxx>                   int main ()S                 {o"                    int value = 10;  Y                    cout << hex << value << ',';   // Change the base conversion format to3Z                                                   // hexadecimal; note that the default is\                                                   // decimal as set by the ios constructors.  Z                    cout << value << ',';          // The base conversion format set in theS                                                   // previous line is still active.            4-8 iostream Package           H                                                      Global Declarations    Y                    cout << dec << value << endl;  // Change the base conversion format toaW                                                   // decimal; lastly, insert a new-lineeX                                                   // character into the stream and flush:                                                   // cout.                    return 0;                 }   &                  The output is a,a,10.  &               2. #include <string.hxx>'                 #include <iostream.hxx>s  -                 void print_name(String &name)                  {lG                    cout << lock << "Hello, " << name << endl << unlock;                  }   H                  This synchronizes access to the cout object so that theG                  "Hello, ", name, and new-line character are written toeF                  cout as a single unit. If you do not use the lock andD                  unlock manipulators in this example, another threadD                  could possibly insert its own text into cout in the&                  midst of your output.                                            H                                                     iostream Package 4-9 o  c               Global Declarationsd               Header  $               #include <iomanip.hxx>                  Alternative Header  "               #include <iomanip.h>           Declarations  5               SMANIP(long)       resetiosflags(long); 3               SMANIP(long)       setiosflags(long);(.               SMANIP(int)        setfill(int);3               SMANIP(int)        setprecision(int); -               SMANIP(int)        setw(int w);G  /               SMANIPREF(Mutex)   lock(Mutex &m) 1               SMANIPREF(Mutex)   unlock(Mutex &m)            Functions   A               These functions are used for extending the iostream C               package with user-defined parameterized manipulators.e  0               SMANIP(long) resetiosflags(long x)F               In the stream (ios or a stream derived from ios), clears,               the format flags denoted by x.  (               SMANIP(int) setfill(int x)E               Sets the fill character to be the value specified by x. C               The fill character is a data member of the ios class;)H               however, setting it with this function affects only output               streams.  .               SMANIP(long) setiosflags(long x)H               In the stream (ios or a stream derived from ios), turns onF               the format flags denoted by x. If you are setting a flagD               that is part of a collection (for example, basefield),G               note that this manipulator does not clear the other flagsc                in the collection.                 4-10 iostream Package            H                                                      Global Declarations    -               SMANIP(int) setprecision(int x) B               Sets the variable that controls the number of digitsC               inserted by the floating-point inserter to be x. This B               variable is a data member of the ios class; however,H               setting it with this function affects only output streams.  %               SMANIP(int) setw(int w)iH               In the stream (ios or a stream derived from ios), sets the-               field width of the stream to w.u  ;         Synchronizing Access to User-Defined Stream Objects   E               The following parameterized manipulators are for use in E               synchronizing access to user-defined stream objects. To C               use these manipulators, you must first define a Mutex A               object, which you then pass to the manipulator. The%C               association of a Mutex object with a stream object is G               not enforced by the iostream package. This association is F               enforced only by you, the programmer. Refer to Chapter 61               for information on the Mutex class.   -               SMANIPREF(Mutex) lock(Mutex &m)o9               Locks the recursive Mutex represented by m.d  /               SMANIPREF(Mutex) unlock(Mutex &m) ;               Unlocks the recursive Mutex represented by m.a           Examples                 1. char c;1                 cin >> resetiosflags(ios::skipws)e                     >> c0                     >> setiosflags(ios::skipws);  C                  Turns off the flag (resets it to 0) that tells the D                  extractor (>>) to skip leading white space and then>                  turns that flag back on again (sets it to 1).                H                                                    iostream Package 4-11 _  _               Global Declarations_                     2. cout.fill(*) 6                 cout.setf(ios::left,ios::adjustfield);.                 cout << setw(6) << 23 << "," ;                 cout.fill(%); 7                 cout.setf(ios::right,ios::adjustfield);n/                 cout << setw(4) << 34 << "\n" ;u  G                  Places padding characters (specified by the fill stateaG                  variable) after the first number and before the seconds3                  number. The output is 23****,%%34.e  &               3. #include <string.hxx>&                 #include <fstream.hxx>$                 #include <mutex.hxx>&                 #include <iomanip.hxx>                   main ()                  {i(                    String name("Henry");B                    void print_name (String &, ostream &, Mutex &);  (                    ofstream mystream(1);'                    Mutex mystream_lock;   =                    print_name(name, mystream, mystream_lock);                     return 0;                 }   U                    void print_name(String &name, ostream &stream, Mutex &stream_lock)i                 { N                       stream << lock(stream_lock) << "Hello, " << name << endl4                              << unlock(stream_lock);                 }a  E                  This example associates a Mutex object with a streamsF                  object to synchronize access to the stream. The MutexD                  is locked before using the stream and then unlockedF                  afterwards. For the synchronization to work properly,H                  each thread that uses this stream must perform the same:                  lock/unlock sequence with the same Mutex.                 4-12 iostream Packageo           H                                                      Global Declarations               See Also                  IMANIP(TYPE) class!               IOMANIP(TYPE) class                 OMANIP(TYPE) class                SMANIP(TYPE) class                                                                            H                                                    iostream Package 4-13                    filebuf classp    H         ________________________________________________________________           filebuf classt  A               Provides a data buffer abstraction for input/outputy2               facilities through file descriptors.           Header  $               #include <fstream.hxx>                  Alternative Header  "               #include <fstream.h>           Declaration   -               class filebuf: public streambuf                {l               public:a/                   static const int    openprot;   0                                       filebuf();6                                       filebuf(int fd);H                                       filebuf(int fd, char *p, int len);1                                       ~filebuf();d  6                   filebuf             *attach(int fd);/                   filebuf             *close();t+                   int                 fd(); 0                   int                 is_open();G                   filebuf             *open(const char *name, int mode, ;                                       int prot = openprot);r  :                   virtual int         overflow(int = EOF);M                   virtual streampos   seekoff(streamoff, seek_dir, int mode); C                   virtual streampos   seekpos(streampos, int mode);t@                   virtual streambuf   *setbuf(char *p, int len);-                   virtual int         sync(); 2                   virtual int         underflow();               };                 4-14 iostream Package     e      H                                                            filebuf class               Description   A               This class specializes the streambuf class to use a E               file as a repository of characters. Writing to the file A               consumes characters; reading from the file producesoB               characters. Files that allow searches are said to beA               seekable. When a file is readable and writable, thesH               filebuf object permits character insertion and extraction.  C               If your program expects a buffer to be allocated wheniE               none was allocated, then the iostream package allocatesrC               a default buffer with a length specified by BUFSIZ as G               defined in stdio.h. The package then issues the followingY               warning:  L               Warning; a null pointer to streambuf was passed to ios::init()           Data Member   '               const int openprot = 0644eG               Provides default protection for the open() function. (For G               an explanation of the file protection, see the C Run-Time (               Library Reference Manual.)  $         Constructors and Destructors                 filebuf()mC               Constructs a filebuf object that is initially closed.e                 filebuf(int fd) F               Constructs a filebuf object connected to file descriptor               fd.   /               filebuf(int fd, char *p, int len) F               Constructs a filebuf object connected to file descriptorG               fd, which is initialized to use the reserve area (buffer)a5               starting at p and containing len bytes.                  ~filebuf()'               Deletes a filebuf object.         H                                                    iostream Package 4-15 o  e               filebuf class                Member Functions  %               filebuf *attach(int fd) ?               Connects the filebuf object to an open file whose_G               descriptor is passed through the fd argument. It normallysF               returns a reference to the filebuf object, but returns 0A               if the filebuf object is connected to an open file.e                 filebuf *close()E               Flushes any waiting output, closes the file descriptor,oG               and disconnects a filebuf object. Unless an error occurs,gC               the filebuf object's error state will be cleared. The A               close() function returns the address of the filebuf E               object unless errors occur, in which case this function F               returns 0. Even if errors occur, close() leaves the file3               descriptor and filebuf object closed.(                 int fd()C               Returns the file descriptor associated with a filebuffF               object. If the filebuf object is closed, fd returns EOF.                 int is_open() H               Returns a nonzero value when a filebuf object is connected<               to a file descriptor; otherwise, it returns 0.  A               filebuf *open(const char *name, int mode, int prot) G               Opens a file with the name specified by name and connectsoE               a filebuf object to it. If the file does not exist, the G               function tries to create it with the protection mode protsD               unless ios::nocreate is specified in mode. By default,(               prot is filebuf::openprot.  C               The function fails if the filebuf object is open. ThenA               open() function normally returns the address of theuC               filebuf object, but returns 0 if an error occurs. TheaG               members of open_mode are bits that may be joined togethersG               by or (because this joining takes an int, open() takes ansH               int rather than an open_mode argument). For an explanationA               of the meanings of these bits in open_mode, see the 9               Enumerated Types section for the ios class.                  4-16 iostream Package     o      H                                                            filebuf class    )               virtual int overflow(int c).B               Called to consume characters in classes derived fromA               streambuf. If c is not EOF, this function must alsogG               either save c or consume it. Although it can be called atfG               other times, this function usually is called when the putkF               area is full and an attempt is being made to store a newG               character. The normal action is to consume the charactersoE               between pbase() and pptr(), call setp()  to establish aaD               new put area, and (if c != EOF) store c using sputc().D               A call to overflow(c) should return EOF to indicate an@               error; otherwise, it should return something else.  H               virtual streampos seekoff(streamoff off, seek_dir dir, int               mode)nG               Moves the get pointer, put pointer, or both as designated C               by the off and dir arguments. It may fail if the file B               does not support seeking, or if the attempted motionC               is otherwise invalid (for example, attempting to seek C               a position before the beginning of the file). The offu@               argument is interpreted as a count relative to theC               place in the file specified by dir. The mode argumentcF               is ignored. A call to seekoff() returns the new positionG               or EOF if a failure occurs. After a failure, the position '               of the file is undefined.   @               virtual streampos seekpos(streampos pos, int mode)D               Moves the file to a position pos. The mode argument isG               ignored. The function normally returns pos but it returns                EOF on failure.u  9               virtual streambuf *setbuf(char *p, int len) G               Sets up the reserve area as the number of bytes specifiedTH               in the second argument, beginning at the pointer specifiedC               in the first argument. If the pointer is null, or thecC               number of bytes is less than 1, the filebuf object isiE               unbuffered. This function normally returns a pointer toeH               the filebuf object; however, if the filebuf object is openH               and a buffer is allocated, then no changes are made to theD               reserve area and to the buffering status, and setbuf()               returns 0.          H                                                    iostream Package 4-17 r                  filebuf classl                    virtual int sync()@               Tries to get the state of the get pointer, the putH               pointer, or both, to agree (synchronize) with the state ofE               the file to which the filebuf object is connected. ThistF               means that the function may write characters to the fileF               if some of the characters have been buffered for output,F               or the function may try to reposition (seek) the file ifH               characters have been read and buffered for input. NormallyE               sync() returns 0, but it returns EOF if synchronization                is not possible.  C               When certain characters must be written together, the F               program should use setbuf() (or a constructor) to ensureF               that the reserve area is at least as large as the numberD               of characters to be written together. Your program canC               then call sync(), store the characters, and then call                 sync() once again.  %               virtual int underflow() @               Called in classes derived from streambuf to supplyH               characters for fetching; that is, to create a condition inH               which the get area is not empty. If the function is calledC               when characters occupy the get area, it should createnE               a nonempty area and return the next character (which itcG               should also leave in the get area). If no more characters G               are available, underflow() should return EOF and leave an                empty get area.a           See Also                 ios class>               streambuf classt                                   4-18 iostream Packagee           H                                                            fstream class    H         ________________________________________________________________           fstream classe  F               Supports formatted and unformatted input from and output               to files.s           Header Filed  $               #include <fstream.hxx>                  Alternative Header  "               #include <fstream.h>           Declarationo  ,               class fstream: public iostream               {                public: )                                fstream(); B                                fstream(const char *name, int mode,A                                    int prot = filebuf::openprot);c/                                fstream(int fd);eA                                fstream(int fd, char *p, int len); *                                ~fstream();  .                   void         attach(int fd);'                   void         close();t?                   void         open(const char *name, int mode,sB                                    int prot = filebuf::openprot) ;(                   filebuf      *rdbuf();8                   void         setbuf(char *p, int len);               };           Descriptionu  C               This class specializes the iostream class to files byhE               using a filebuf object to do the input and output. Your)D               program can perform common operations, such as openingF               and closing files, without explicitly mentioning filebuf               objects.      H                                                    iostream Package 4-19    x               fstream classa      $         Constructors and Destructors                 fstream()i4               Constructs an unopened fstream object.                 fstream(int fd)MF               Constructs an fstream object connected to the file whoseD               descriptor is passed through the fd argument. The file               must be open.   /               fstream(int fd, char *p, int len)oD               Constructs an fstream object connected to a file whoseD               descriptor is passed through the fd argument, and alsoF               initializes the associated filebuf object to use the lenF               bytes starting at p as the reserve area. If p is null or9               len is 0, the filebuf object is unbuffered.   ;               fstream(const char *name, int mode, int prot)hG               Constructs an fstream object and opens the file specifiedaG               by the name argument. The mode and prot arguments specifynD               the file open mode and protection. By default, prot isD               filebuf::openprot. If the open action fails, the error@               state (io_state) of the constructed fstream object                indicates failure.                 ~fstream()(               Deletes an fstream object.           Member Functions  !               void attach(int fd) C               Connects an fstream object to a file whose descriptorsF               is passed through the fd argument. A failure occurs whenF               the fstream object is connected to a file, in which caseF               ios::failbit is set in the filebuf object's error state.                 void close()C               Closes any associated filebuf object and consequently6F               breaks the connection of the fstream object to the file.E               The error state of the fstream object is cleared except G               on failure. A failure occurs when the call to the filebuf .               object's close() function fails.             4-20 iostream Package            H                                                            fstream class    =               void open(const char *name, int mode, int prot) C               Opens a file with the file name specified by name and E               connects the fstream object to it. If the file does not H               exist, the function tries to create it with the protectionD               specified by the prot argument unless ios::nocreate is9               set. By default, prot is filebuf::openprot.   F               Failure occurs if the fstream object is open or when theD               call to the filebuf object's open() function fails, inB               which case ios::failbit is set in the filebuf objectH               error state. The members of open_mode are bits that may beG               joined together by or (because this joining takes an int, E               open() takes an int rather than an open_mode argument). G               For an explanation of the meanings of these bits in open_sG               mode, see the Enumerated Types section for the ios class.u                 filebuf *rdbuf()E               Returns a pointer to the filebuf object associated with G               the fstream object. This function has the same meaning ase5               ios::rdbuf(), but has a different type.o  +               void setbuf(char *p, int len)mF               Calls the associated filebuf object setbuf() function toG               request space for a reserve area. A failure occurs if the F               filebuf object is open or if the call to rdbuf()->setbuf)               fails for any other reason.                                       H                                                    iostream Package 4-21                    IAPP(TYPE) class    H         ________________________________________________________________           IAPP(TYPE) class  F               For an istream object, declares predefined parameterized               applicators.           Header Filet  $               #include <iomanip.hxx>                  Alternative Header  "               #include <iomanip.h>           Compile-Time Parameter  @               TYPE-The type of the istream object. It must be an               identifier.            Declaration                  class IAPP(TYPE)               {l               public:N=                   IAPP(TYPE)(istream &(*f)(istream &, TYPE)); 2                   IMANIP(TYPE) operator()(TYPE a);               };           Constructor   :               IAPP(TYPE) (istream &(*f) (istream &, TYPE))B               Creates an applicator; *f is the left operand of the!               insertion operator._           Operator  /               IMANIP(TYPE) operator () (TYPE a) G               Casts an object of type a into a manipulator function forp                an istream object.                   4-22 iostream Packagee r         H                                                         IAPP(TYPE) class               See Also                  IMANIP(TYPE) class                                                                                  H                                                    iostream Package 4-23                    ifstream class    H         ________________________________________________________________           ifstream class  B               Supports formatted and unformatted input from files.           Header File   $               #include <fstream.hxx>                  Alternative Header  "               #include <fstream.h>           Declaration   ,               class ifstream: public istream               {i               public:()                               ifstream(); L                               ifstream(const char *name, int mode = ios::in,A                                    int prot = filebuf::openprot); /                               ifstream(int fd); A                               ifstream(int fd, char *p, int len); *                               ~ifstream();  -                   void        attach(int fd); &                   void        close();H                   void        open(const char *name, int mode = ios::in,A                                    int prot = filebuf::openprot); '                   filebuf     *rdbuf(); 7                   void        setbuf(char *p, int len);t               };           Description   H               This class specializes the istream class to files by usingH               a filebuf object to do the input. Your program can performC               common operations, such as opening and closing files, <               without explicitly mentioning filebuf objects.                   4-24 iostream Packaged t  t      H                                                           ifstream class      $         Constructors and Destructors                 ifstream()5               Constructs an unopened ifstream object.                  ifstream(int fd)E               Constructs an ifstream object connected to a file whosenD               descriptor is passed through the fd argument. The file#               must already be open.   0               ifstream(int fd, char *p, int len)E               Constructs an ifstream object connected to a file whose D               descriptor is passed through the fd argument, and alsoF               initializes the associated filebuf object to use the lenF               bytes starting at p as the reserve area. If p is null or9               len is 0, the filebuf object is unbuffered.n  <               ifstream(const char *name, int mode, int prot)G               Constructs an ifstream object and opens the file with the*F               file name specified by name. The mode and prot argumentsD               specify the file open mode and protection. By default,E               prot is filebuf::openprot. If the open fails, the error A               state (io_state) of the constructed ifstream objectt                indicates failure.                 ~ifstream()i)               Deletes an ifstream object.            Member Functions  !               void attach(int fd)iD               Connects an ifstream object to a file whose descriptorF               is passed through the fd argument. A failure occurs whenG               the ifstream object is connected to a file, in which casejE               ios::failbit is set in the ifstream object error state.                  void close()C               Closes any associated filebuf object and consequentlytG               breaks the connection of the ifstream object to the file.eE               The error state of the fstream object is cleared exceptlG               on failure. A failure occurs when the call to the filebuf .               object's close() function fails.    H                                                    iostream Package 4-25 u  c               ifstream class    =               void open(const char *name, int mode, int prot) F               Opens a file specified by the name argument and connectsH               the ifstream object to it. If the file does not exist, theG               function tries to create it with the protection specifiedhB               by the prot argument unless ios::nocreate is set. By1               default, prot is filebuf::openprot.   C               Failure occurs if the ifstream object is open or wheneC               the call to the filebuf object open() function fails,uE               in which case ios::failbit is set in the filebuf objectnH               error state. The members of open_mode are bits that may beG               joined together by or (because this joining takes an int,eE               open() takes an int rather than an open_mode argument).tG               For an explanation of the meanings of these bits in open_sG               mode, see the Enumerated Types section for the ios class.                  filebuf *rdbuf()E               Returns a pointer to the filebuf object associated withuH               the ifstream object. This function has the same meaning as4               ios::rdbuf() but has a different type.  +               void setbuf(char *p, int len)oF               Calls the associated filebuf object setbuf() function toG               request space for a reserve area. A failure occurs if the F               filebuf object is open or if the call to rdbuf()->setbuf)               fails for any other reason.                                                4-26 iostream Package  e  u      H                                                       IMANIP(TYPE) class    H         ________________________________________________________________           IMANIP(TYPE) class  D               For an istream object, declares the predefined parame-G               terized manipulators and provides macros for user-definedt)               parameterized manipulators.r           Header Filea  $               #include <iomanip.hxx>                  Alternative Header  "               #include <iomanip.h>           Compile-Time Parameter  @               TYPE-The type of the istream object. It must be an               identifier.e           Declaration                   class IMANIP(TYPE)               {                public:nG                   IMANIP(TYPE)(istream &(*f)(istream &, TYPE), TYPE a);rJ                   friend istream &operator>>(istream &s, IMANIP(TYPE) &m);               };           Description   E               These manipulators serve the istream class by producing C               some useful effect, such as embedding a function callrD               in an expression containing a series of insertions andG               extractions. You also can use manipulators to shorten thedD               long names and sequences of operations required by the               iostream class.l  C               In its simplest form, a manipulator takes an istream& C               argument, operates on it in some way, and returns it.         H                                                    iostream Package 4-27 f  t               IMANIP(TYPE) class               Constructorn  B               IMANIP(TYPE)(istream &(*f)(istream &, TYPE), TYPE a)B               Creates a manipulator; *f is the left operand of the!               extractor operator.n           Operator  @               istream &operator >> (istream &s, IMANIP(TYPE) &m)0               Takes data from an istream object.                                                                             4-28 iostream Packager r  a      H                                                        IOAPP(TYPE) class    H         ________________________________________________________________           IOAPP(TYPE) classa  G               For an iostream object, declares predefined parameterized                applicators.           Header File   $               #include <iomanip.hxx>                  Alternative Header  "               #include <iomanip.h>           Compile-Time Parameter  A               TYPE-The type of the iostream object. It must be ann               identifier.            Declarationh                 class IOAPP(TYPE).               {                public:t@                   IOAPP(TYPE)(iostream &(*f)(iostream &, TYPE));3                   IOMANIP(TYPE) operator()(TYPE a);                };           Constructor   ;               IOAPP(TYPE)(iostream &(*f)(iostream &, TYPE)) $               Creates an applicator.           Operator  0               IOMANIP(TYPE) operator () (TYPE a)G               Casts an object of type a into a manipulator function forr!               an iostream object.             H                                                    iostream Package 4-29 a                  IOAPP(TYPE) classr               See Also  !               IOMANIP(TYPE) classo                                                                                           4-30 iostream Package            H                                                      IOMANIP(TYPE) class    H         ________________________________________________________________           IOMANIP(TYPE) classh  G               For an iostream object, declares predefined parameterizedn?               manipulators and provides macros for user-defined )               parameterized manipulators.e           Header File   $               #include <iomanip.hxx>                  Alternative Header  "               #include <iomanip.h>           Compile-Time Parameter  A               TYPE-The type of the iostream object. It must be an                identifier.s           Declaration   !               class IOMANIP(TYPE)                {                public: J                   IOMANIP(TYPE)(iostream &(*f)(iostream &, TYPE), TYPE a);L                   friend istream &operator>>(iostream &s, IOMANIP(TYPE) &m);L                   friend ostream &operator<<(iostream &s, IOMANIP(TYPE) &m);               };  "               IOMANIPdeclare(int);#               IOMANIPdeclare(long);            Description   F               These manipulators serve the iostream class by producingC               some useful effect, such as embedding a function calluD               in an expression containing a series of insertions andG               extractions. You can also use manipulators to shorten the D               long names and sequences of operations required by the               iostream class.   D               In its simplest form, a manipulator takes an iostream&C               argument, operates on it in some way, and returns it.c  H                                                    iostream Package 4-31                    IOMANIP(TYPE) class     D               Two ios manipulators for using Mutex objects, lock andD               unlock, come in both parameterized and unparameterizedF               forms. The parameterized manipulators let users synchro-G               nize iostream objects, the parameter being a user-defined G               Mutex object. To use parameterized manipulators, you must C               include iomanip.hxx. Unparameterized manipulators let D               users synchronize the predefined stream objects: cerr,"               cin, clog, and cout.  E               For examples of using the lock and unlock manipulators, E               see Chapter 6 and the section on Global Declarations in                this chapter.            Constructorn  B               IOMANIP(TYPE)(iostream &(*f)(iostream &, TYPE), TYPE               a)$               Creates a manipulator.  
         Macro   "               IOMANIPdeclare(TYPE)E               Declares the manipulators (and the manipulator classes)(D               that have an operator() member function for type TYPE.           Operatorsw  B               ostream &operator << (iostream &s, IOMANIP(TYPE) &m)/               Sends data to an iostream object.l  B               istream &operator >> (iostream &s, IOMANIP(TYPE) &m)1               Takes data from an iostream object.0                                   4-32 iostream Packager (  s      H                                                                ios class    H         ________________________________________________________________           ios classf  B               Contains state variables common to most of the other.               classes in the iostream package.           Header  %               #include <iostream.hxx>                   Alternative Header  #               #include <iostream.h>            Declaration                  class ioso               {                public: A                   enum io_state       { goodbit = 0, eofbit = 01,bD                                         failbit = 02, badbit = 04 };D                   enum open_mode      { in = 01, out = 02, ate = 04,?                                         app = 010, trunc = 020,iK                                         nocreate = 040, noreplace = 0100 }; F                   enum seek_dir       { beg = 0, cur = 01, end = 02 };  4                   enum                { skipws = 01,N                                         left = 02, right = 04, internal = 010,I                                         dec = 020, oct = 040, hex = 0100, J                                         showbase = 0200, showpoint = 0400,:                                         uppercase = 01000,8                                         showpos = 02000,K                                         scientific = 04000, fixed = 010000, K                                         unitbuf = 020000, stdio = 040000 };c  0                   static const long   basefield;2                   static const long   adjustfield;1                   static const long   floatfield;s  7                                       ios(streambuf *);f-                   virtual             ~ios();u      H                                                    iostream Package 4-33 e  s               ios classn    2                   inline int          bad() const;1                   static long         bitalloc();s;                   inline void         clear(int state = 0);t2                   inline int          eof() const;3                   inline int          fail() const;e3                   inline char         fill() const; 1                   char                fill(char);e4                   inline long         flags() const;2                   long                flags(long);3                   inline int          good() const; 2                   long                &iword(int);2                   inline int          operator!();8                   inline              operator void *();8                   inline int          precision() const;5                   int                 precision(int);p3                   void                *&pword(int); /                   inline streambuf    *rdbuf();o6                   inline int          rdstate() const;E                   long                setf(long setbits, long field); 1                   long                setf(long); 8                   static void         sync_with_stdio();3                   inline ostream      *tie() const; 6                   ostream             *tie(ostream *);3                   long                unsetf(long); 4                   inline int          width() const;3                   int                 width(int n);t/                   static int          xalloc();                  protected:,                                       ios();8                   void                init(streambuf *);:                   inline void         setstate(int state);                 };           Description   E               Classes derived from the ios class provide an interface D               for transferring formatted and unformatted information0               into and out of streambuf objects.                   4-34 iostream Package  a  i      H                                                                ios class               Enumerated Types                 io_stateC               Represents a collection of bits (flags) that describenG               the internal error states of an object. The values are asr               follows:  ,               goodbit    No errors occurred.  E               eofbit     End-of-file encountered during an extractionN#                          operation.   G               failbit    Extraction or conversion failed but the stream )                          is still usable.   C               badbit     A severe error, usually in an operation on_D                          the associated streambuf object, from which.                          recovery is unlikely.                 open_mode D               Represents a collection of bits (flags) for specifyingF               the mode of the open() function. Use this data type withE               objects of the fstream, ifstream, and ofstream classes.e(               The values are as follows:  A               app        Performs a seek to the end-of-file. This F                          appends to the end of the file any subsequentC                          data written to the file. ios::app implies "                          ios::out.  E               ate        Performs a seek to the end-of-file during an B                          open() operation. ios::ate does not imply"                          ios::out.  D               in         Opens the file for input. Constructions andB                          open operations of ifstream objects implyH                          ios::in. For fstream objects, ios::in signifiesC                          that input operations should be allowed if D                          possible. Including ios::in in the modes ofC                          an ofstream object is legal, implying thatpG                          the original file (if it exists) should not bee#                          truncated.     H                                                    iostream Package 4-35    k               ios class       E               out        Opens the file for output. Constructions and B                          open operations of ofstream objects imply@                          ios::out. For fstream objects, ios::outF                          indicates that output operations are allowed.  F               trunc      Truncates (discards) the contents of the fileA                          (if it exists). ios::trunc is implied if B                          ios::out is specified (including implicitA                          specification for ofstream objects), and D                          neither ios::app nor ios::ate is specified.  G               nocreate   Causes an open() operation to fail if the file (                          does not exist.  G               noreplace  Causes an open() operation to fail if the filef                           exists.                                                                 4-36 iostream Package            H                                                                ios class                   seek_dirE               Represents a collection of bits for positioning get and D               put pointers. Use this data type with functions of theC               filebuf, istream, ostream, and streambuf classes. The $               values are as follows:  >               beg        Indicates the beginning of the stream  7               cur        Indicates the current positionj  F               end        Indicates the end of the stream (end-of-file)           Data Members  $               const long adjustfieldB               Collectively specifies the flags (bits) that control2               padding (left, right, and internal).  "               const long basefield@               Collectively specifies the flags that control base-               conversion (dec, hex, and oct).t  #               const long floatfieldtE               Collectively specifies the flags that control floating- <               point value conversion (fixed and scientific).  F                 ________________________Note  ________________________  @                 When you set a flag that is part of adjustfield,B                 basefield, or floatfield, you must ensure that theC                 other flags within the collection are cleared. Only C                 one flag within the collection should be set at anyo                 one time.   C                 Be aware that the setiosflags(flag) manipulator and C                 the setf(flag) member function set only the flag or B                 flags that you specify. If the flag you specify isB                 part of a collection, these do not clear the other(                 flags in the collection.  C                 The setf(flag, field) member function is useful fornB                 setting fields within a collection. Also, the hex,B                 oct, and dec manipulators do ensure that the otherB                 flags within the basefield collection are cleared.  E                 _____________________________________________________s  H                                                    iostream Package 4-37 i  c               ios classi      $         Constructors and Destructors                 ios()cD               Constructs an ios object with the effect undefined. ItE               lets derived classes inherit the ios class as a virtualtF               base class. The object is initialized with the following               default values:   H               __________________________________________________________H               Element____Default_Value__________________________________  ,               fill()     The space character  /               flags()    ios::dec | ios::skipws                  precision()6  %               rdstate()  ios::goodbit   H               width()____0______________________________________________                 ios(streambuf *b)_C               Constructs an ios object, associating the constructedtG               ios object with the streambuf object pointed to by b. TheuG               object is initialized with the same default values as the                 ios() constructor.                 virtual ~ios()$               Deletes an ios object.           Overloaded Operators  D               When defined, the following operators allow convenient4               checking of the error state of an ios.                 int operator !()@               Returns nonzero if failbit or badbit is set in theC               error state, which allows the use of such expressionsi"               as if (!cin) . . . .  #               int operator void *()tC               Converts an ios object to a pointer so that it can be C               compared to 0. The conversion returns a nonzero valuenG               (not meant for further use) if neither failbit nor badbit D               is set in the error state. This allows the use of suchE               expressions as if (cin) . . . and if (cin >> x) . . . .d           4-38 iostream Packageq c  o      H                                                                ios class               Other Member Functions                 int bad() constuC               Returns a nonzero value if badbit is set in the error D               state; otherwise, it returns 0. This usually indicatesA               that some operation on rdbuf() has failed, and that E               continued operations on the associated streambuf object "               may not be possible.                 long bitalloc() >               Returns a long integer with a single, previouslyD               unallocated bit set. This gives you an additional flagG               should you need one (to pass to ios::set(), for example).   #               void clear(int state)iC               Stores an integer value as the error state. A 0 value                clears all bits.                 int eof() const_C               Returns a nonzero value if eofbit is set in the error E               state; otherwise, it returns 0. This bit is usually setaC               during an extraction and when an end-of-file has been                encountered.                 int fail() constH               Returns a nonzero value if either badbit or failbit is setG               in the error state; otherwise, it returns 0. This usuallynH               indicates that some extraction or conversion operation hasF               failed, but that the stream remains usable; once failbitD               clears, operations on the stream can usually continue.                 char fill() const G               Returns the variable currently used as the fill (padding)t               character.                 char fill(char c)iE               Sets c as the fill (padding) character if one is neededT@               (see width ()) and returns the previous value. TheA               default fill character is a space. The right, left, B               and internal flags determine positioning of the fillF               character. A parameterized manipulator, setfill, is also7               available for setting the fill character.     H                                                    iostream Package 4-39 a  g               ios class                     long flags() const/               Returns the current format flags._                  long flags(long f)E               Resets all the format flags to those specified in f and F               returns the previous settings. The flags are as follows:  D               skipws     For scalar operations, instructs the arith-E                          metical extractor to skip white space before<F                          beginning conversion. As a precaution againstC                          looping, arithmetical extractors signal anEG                          error if the next character is white space andr6                          the skip variable is not set.  A               left       Control padding of values. The left flag C               right      adds a fill character after a value, right B               internal   adds a fill character before a value, andA                          internal adds a fill character after anyED                          leading sign or base indication, but beforeC                          the value. Right-adjustment is the default C                          if none of these flags are set. The fields B                          are collectively identified by the staticD                          member ios::adjustfield. The fill characterE                          is controlled by the fill() function and the E                          width after the padding is controlled by the *                          width() function.  @               dec        Control the conversion base of a value.C               oct        Insertions are in decimal if none of these F               hex        flags are set. Extractions follow C++ lexicalF                          conventions for integral constants. The flagsB                          are collectively identified by the staticE                          member ios::basefield. The manipulators hex,zH                          dec, and oct are also available for setting the)                          conversion base.   E               showbase   Converts insertions to an external form that A                          can be read according to the C++ lexical H                          conventions for integral constants. By default,-                          showbase is not set.x  ?               showpos    Inserts a plus sign (+) into a decimaleA                          conversion of a positive integral value.              4-40 iostream Packagec n         H                                                                ios class      G               uppercase  Uses an uppercase X for hexadecimal conversionOE                          when showbase is set, or uses uppercase E tonC                          print floating-point numbers in scientifictD                          notation. By default, uppercase is not set.  B               showpoint  Specifies that trailing zeros and decimalH                          points appear in the result of a floating-point$                          conversion.  E               scientific Control the format to which a floating-pointsH                          value is converted for insertion into a stream.D               fixed      These two flags are collectively identifiedB                          by the static member ios::floatfield. TheA                          scientific flag converts the value using G                          scientific notation, with one digit before the H                          decimal point. Depending on the uppercase flag,H                          an E or an e introduces the exponent. The fixedE                          flag converts the value to decimal notation.m?                          For both flags, the precision function F                          determines the number of digits following theE                          decimal point (6 is the default). If neither F                          flag is set, then scientific notation is usedD                          only if the exponent from the conversion isD                          less than -4 or greater than the precision.D                          If showpoint is not set, trailing zeros areD                          removed from the result and a decimal point=                          appears only if followed by a digit.   F               unitbuf    Causes ostream::osfx() to perform a flush af-G                          ter each insertion. Unit buffering constitutes F                          a performance compromise between buffered and+                          unbuffered output.   C               stdio      Causes ostream::osfx() to flush stdout and 5                          stderr after each insertion.                  int good() constD               Returns a nonzero value if the error state has no bits+               set; otherwise, it returns 0.m  %               void init(streambuf *b) E               Initializes the ios object; intended for use by classes                derived from ios.   H                                                    iostream Package 4-41                    ios class                     long& iword(int i)?               Returns a reference to the ith user-defined word,nE               where i is an index into an array of words allocated bya               ios::xalloc. [1]  #               int precision() const :               Returns the precision format state variable.  "               int precision(int i)G               Sets the precision format state variable to i and returns B               the previous value. The variable controls the numberB               of significant digits inserted by the floating-pointF               inserter. The default is 6. A parameterized manipulator,H               setprecision, is also available for setting the precision.  &               void *&ios::pword(int i)E               Returns a reference to the ith user-defined word, wherea?               i is an index into an array of words allocated by(B               ios::xalloc. This function differs from iword() only               in type.  %               streambuf *ios::rdbuf() @               Returns a pointer to the streambuf object that wasC               associated with an ios object when the ios object wasa               constructed.  !               int rdstate() const .               Returns the current error state.  %               long setf(long setbits) H               Makes available to the streambuf object associated with anG               ios object the format flags marked in setbits and returns A               the previous settings. A parameterized manipulator,*A               setiosflags, performs the same function. If you are G               setting a flag that is part of a collection (for example,rG               basefield), note that this manipulator does not clear ther,               other flags in the collection.  !               ___________________.G               [1]This function references a single array that is shared B                  among all instances of ios objects.  This differsC                  from the Digital UNIX operating system, where thisnF                  function references the array that is specific to the                    ios instance.           4-42 iostream Packagel :         H                                                                ios class    1               long setf(long setbits, long field) D               Clears, in the streambuf object associated with an iosF               object, the format flags specified by field, then resetsG               these flags to the settings marked in setbits. It returns G               the previous settings. Specifying 0 in setbits clears all D               the bits specified in field, as does the parameterized(               manipulator, resetioflags.  &               void setstate(int state)D               Changes only the bits specified in the state argument.  $               void sync_with_stdio()G               Solves problems that arise with mixing stdio and iostream ?               objects. When first called, the sync_with_stdio() C               function resets the standard iostream functions (cin, @               cout, cerr, and clog) to be streams using stdiobufA               objects. Subsequently, input and output using thesemB               streams may be mixed with input and output using theH               corresponding FILE parameters (stdin, stdout, and stderr),G               and properly synchronized. The sync_with_stdio() function A               makes cout and cerr unit buffered (see ios::unitbuf B               and ios::stdio). Invoking sync_with_stdio() degradesA               performance variably; the shorter the strings beingw4               inserted, the greater the degradation.  '               ostream *ios::tie() const @               Returns the tie variable (see the following member$               function description).  -               ostream *ios::tie(ostream *osp)cC               Sets the tie variable to osp and returns its previousaD               value. The tie variable supports automatic flushing ofF               ios objects. The ios object that the tie variable pointsC               at is flushed if the variable is not null, and an ios F               object either needs more characters or has characters toG               be consumed. By default, cin is initially tied to cout so F               that attempts to get more characters from standard inputD               result in flushing standard output. Additionally, cerrG               and clog are tied to cout by default. By default, the tiei9               variable is set to 0 for other ios objects.           H                                                    iostream Package 4-43 e                  ios classf    '               long unsetf(long setbits).D               Unsets, in the streambuf object associated with an iosF               object, the bits set in setbits; it returns the previous               settings.                  int width() const H               Returns the field-width format variable (see the followingC               member function description). The field width settingeE               within the ios class is ignored during single character E               output: operator<<(char) and operator<<(unsigned char).s                 int width(int n)C               Sets the field-width format variable to n and returnsdE               the previous value. The field width specifies a minimumsF               number of characters for inserters. When the variable isG               0 (the default), inserters insert only as many charactersoC               as needed to represent the value being inserted. When C               the variable is nonzero, and the value being inserted H               needs fewer than field-width characters to be represented,F               inserters insert at least that many characters using theC               fill character to pad the value. Numeric inserters dosE               not truncate values even if the value being inserted isoG               more than field-width characters. After each insertion or_F               extraction, the field-width format variable resets to 0.F               A parameterized manipulator, setw, is also available for&               setting the field width.                 int xalloc()F               Returns a previously unused index into an array of wordsB               available for use by derived classes as format state               variables. [1]            !               ___________________eG               [1]This function references a single array that is sharedtB                  among all instances of ios objects.  This differsC                  from the Digital UNIX operating system, where thiseF                  function references the array that is specific to the                    ios instance.           4-44 iostream Packagel           H                                                                ios class               Examples                   1. cout.width(6); &                 cout << x << " " << y;  G                  Outputs x in at least six characters, but uses only as G                  many characters as needed for the separating space and                   y.a  D                  In the following examples, mystrm is an ios object.  6               2. mystrm.clear(ios::badbit|s.rdstate())  G                  Sets the badbit member of the io_state enumerated datas;                  type without clearing previously set bits.   5               3. mystrm.setf(ios::hex,ios::basefield)_  F                  Changes the conversion base in mystrm to be hexadeci-                  mal._                                              H                                                    iostream Package 4-45                    iostream class    H         ________________________________________________________________           iostream class  G               Provides the means to both insert into and extract from as,               single sequence of characters.           Header Fileu  %               #include <iostream.hxx>                   Alternative Header  #               #include <iostream.h>            Declaration   <               class iostream: public istream, public ostream               {r               public: 3                              iostream(streambuf *); )                   virtual    ~iostream();r                 protected:(                              iostream();               };           Descriptione  F               This class combines the istream and ostream classes. YouE               use it to carry out bidirectional operations (insertingvH               into and extracting from a single sequence of characters).  $         Constructors and Destructors                 iostream()B               Constructs an iostream object, in undefined form, to4               enable inheritance by derived classes.  $               iostream(streambuf *b)E               Constructs an iostream object. It initializes ios state C               variables and associates the iostream object with the /               streambuf object pointed to by b.              4-46 iostream Package            H                                                           iostream class    !               virtual ~iostream()e)               Deletes an iostream object.                                                                                       H                                                    iostream Package 4-47 s  l      !         iostream_withassign class     H         ________________________________________________________________  !         iostream_withassign classd  C               Adds an assignment operator and a constructor with no -               operands to the iostream class.s           Header Filet  %               #include <iostream.hxx>                   Alternative Header  #               #include <iostream.h>_           Declaration   8               class iostream_withassign: public iostream               {e               public:t7                                  iostream_withassign();w7                   virtual       ~iostream_withassign();   =                   iostream_withassign &operator=(iostream &); >                   iostream_withassign &operator=(streambuf *);               };           Description   F               This class adds an assignment operator and a constructor5               with no operands to the iostream class.a  $         Constructors and Destructors  #               iostream_withassign()uB               Constructs an iostream_withassign object; it does no               initialization.e  ,               virtual ~iostream_withassign()F               Deletes an iostream_withassign object; no user action is               required.n                 4-48 iostream Package( a  r      H                                                iostream_withassign class               Overloaded Operators  :               iostream_withassign &operator = (iostream &)F               Associates iostream->rdbuf() with an iostream_withassignE               object and initializes the entire state of that object.   ;               iostream_withassign &operator = (streambuf *) F               Associates streambuf* with an iostream_withassign object>               and initializes the entire state of that object.                                                                      H                                                    iostream Package 4-49 o  w               istream class     H         ________________________________________________________________           istream classs  E               Supports interpretation of characters extracted from ani*               associated streambuf object.           Header Filer  %               #include <iostream.hxx>r                  Alternative Header  #               #include <iostream.h>s           Declaration.  0               class istream : virtual public ios               {                public: :                                      istream(streambuf *);0                   virtual            ~istream();  .                   inline int         gcount();=                   istream            &get(char *ptr, int len,r>                                            char delim = '\n');F                   istream            &get(unsigned char *ptr, int len,>                                            char delim = '\n');2                   istream            &get(char &);;                   inline istream     &get(unsigned char &); L                   istream            &get(streambuf &sb, char delim = '\n');+                   int                get();oA                   istream            &getline(char *ptr, int len, >                                            char delim = '\n');J                   istream            &getline(unsigned char *ptr, int len,?                                             char delim = '\n'); 9                   istream            &ignore(int len = 1,f9                                            int delim = );b8                   int                ipfx(int need = 0);,                   void               isfx();,                   int                peek();4                   istream            &putback(char);;                   istream            &read(char *s, int n); D                   inline istream     &read(unsigned char *s, int n);           4-50 iostream Package  n  t      H                                                            istream class    7                   istream            &seekg(streampos);iA                   istream            &seekg(streamoff, seek_dir);n1                   void               skipwhite(); ,                   int                sync();-                   streampos          tellg(); 9                   istream            &operator>>(char *);l9                   istream            &operator>>(char &);,:                   istream            &operator>>(short &);8                   istream            &operator>>(int &);9                   istream            &operator>>(long &); :                   istream            &operator>>(float &);;                   istream            &operator>>(double &);iB                   istream            &operator>>(unsigned char *);B                   istream            &operator>>(unsigned char &);C                   istream            &operator>>(unsigned short &); A                   istream            &operator>>(unsigned int &); B                   istream            &operator>>(unsigned long &);>                   istream            &operator>>(streambuf *);K                   inline istream     &operator>>(istream &(*f)(istream &)); C                   istream            &operator>>(ios &(*f)(ios &));                  protected:/                                      istream();                  };           Description   >               This class provides facilities for formatted and<               unformatted extraction from streambuf objects.  $         Constructors and Destructors  $               istream(streambuf *sb)D               Constructs an istream object. It initializes ios stateB               variables and associates the istream object with the&               buffer pointed to by sb.                  virtual ~istream()(               Deletes an istream object.          H                                                    iostream Package 4-51 h  e               istream class                Overloaded Operators  E               The following operators are all formatted input extrac- B               tors. Given the expression ins >> x, these operatorsA               extract characters from ins and convert them to theeE               variable x. The argument to the operator determines theuD               type of x. Extractions are performed only if a call toF               ipfx(0) returns a nonzero value. Errors are indicated byE               setting the error state of ins. ios::failbit means thateD               characters in ins did not represent the required type.C               ios::badbit means that attempts to extract characters G               failed. ins is always returned. The details of conversioniG               depend on the values of the ins object format state flagsgD               and variables, and the type of x. Extractions that useF               width reset it to 0; otherwise, the extraction operatorsB               do not change the value of the istream object format               state.  ,               istream &operator >> (char &x)5               istream &operator >> (unsigned char &x)a6               Extracts a character and stores it in x.  ,               istream &operator >> (char *x)5               istream &operator >> (unsigned char *x) F               Extracts characters and stores them in the array pointedD               at by x, until a white-space character is found in theG               iostream object. The action leaves the terminating white-aE               space character in the iostream object. If the iostream)E               object's width() is nonzero, it is taken to be the sizeaD               of the array and no more than width()-1 characters areF               extracted. A terminating null character ('\0') is alwaysA               stored, even if nothing else is done because of the B               iostream object's error state. The iostream object's$               width() is reset to 0.  -               istream &operator >> (short &x) +               istream &operator >> (int &x) ,               istream &operator >> (long &x)6               istream &operator >> (unsigned short &x)4               istream &operator >> (unsigned int &x)                 4-52 iostream Packageg a  d      H                                                            istream class    5               istream &operator >> (unsigned long &x)fH               Extracts characters and converts them to an integral valueC               according to the conversion specified in the iostreamlF               object's format flags. Converted values are stored in x.E               The first character can be a sign (- or +). After that,fH               the conversion is octal if ios::oct is set in the iostreamH               object's flags, decimal if ios::dec is set, or hexadecimal!               if ios::hex is set.   D               The first nondigit that is left in the iostream objectC               terminates the conversion. If no conversion base flag F               is set, the conversion proceeds according to C++ lexicalF               conventions: if the first characters (after the optionalG               sign) are 0x or 0X, the conversion is hexadecimal; if the G               first character is 0, the conversion is octal; otherwise, C               the conversion is decimal. If no digits are available E               (not counting the 0 in 0x or 0X during hex conversion), "               ios::failbit is set.  -               istream &operator >> (float &x)o.               istream &operator >> (double &x)D               Extracts characters and converts them according to C++C               syntax for a float value or a double value. ConvertedvC               values are stored in x. If no digits are available in E               the iostream object, or if the iostream object does notiG               begin with a well formed floating-point or double number,r"               ios::failbit is set.  1               istream &operator >> (streambuf *b)oG               Keeps getting characters from ios and inserting them intopH               the buffer b until EOF is reached, if ios::ipfx(0) returns:               nonzero. Always returns the iostream object.  5               istream &operator >> (ios &(*f)(ios &))cG               Calls an ios object manipulator function f for an istreamk               object.e  =               istream &operator >> (istream &(*f)(istream &))gC               Calls an istream object manipulator function f for an                istream object.o          H                                                    iostream Package 4-53 u  i               istream class                Other Member Functions  E               The unformatted input extractors, get, getline, ignore, D               and read, are among these functions. Before performingE               any extractions, these extractors, plus the unformatted E               function peek (which returns the next character without H               extracting it), call ipfx(1) and proceed only if a nonzero                value is returned.                 int gcount()D               Returns the number of characters extracted by the lastC               unformatted input function (get, getline, ignore, andeA               read). Note that formatted input functions can call E               unformatted input functions and also reset this number.                  int get() D               Extracts a character and returns it, or returns EOF ifF               the extraction encounters the end-of-file. It never sets               ios::failbit.f  %               istream &get(char &ptr) .               istream &get(unsigned char &ptr)@               Extracts a single character and stores it in &ptr.  :               istream &get(char *ptr, int len, char delim)C               istream &get(unsigned char *ptr, int len, char delim) C               Extracts characters and stores them in the byte arrayuF               beginning at ptr and extending for len bytes. ExtractionA               stops when any of the following conditions are met:   E               o  The extractor encounters delim (delim is left in the 0                  istream object and not stored.)  ;               o  The istream object has no more characters.t  2               o  The array has only one byte left.  E               The function stores a terminating null, even if it doestE               not extract any characters because of its error status.aD               The extraction sets ios::failbit only if it reaches an8               end-of-file before storing any characters.               4-54 iostream Packageu g  e      H                                                            istream class    5               istream &get(streambuf &sb, char delim)i@               Extracts characters from an istream object rdbuf()>               function and stores them into sb. It stops if itC               encounters the end-of-file, if a store into sb fails,iG               or if it encounters delim (which it leaves in the istream G               object). The function sets ios::failbit if the extraction >               stops because the store operation into sb fails.  >               istream &getline(char *ptr, int len, char delim)@               istream &getline(unsigned char *ptr, int len, char               delim)A               Functions the same as get(char *, int, char) excepttC               that these extract a terminating delim character fromsA               an istream object. If delim occurs when exactly lena?               characters have been extracted, a filled array is C               considered to be the cause of the termination and the A               extraction leaves this delim in the istream object.   1               istream &ignore(int len, int delim)oD               Extracts and discards up to len characters. ExtractionD               stops prematurely if delim is extracted or the end-of-B               file is reached. If delim is EOF, it can never cause               termination.                  int ipfx(int need)B               Returns 0 if the error state of an istream object is@               nonzero. If necessary (and if it is not null), theF               function flushes any ios tied to the istream object (seeD               the description of ios::tie()). Flushing is consideredA               necessary if need is set to 0 or if fewer than need_E               characters are immediately available. If ios::skipws is D               set in the istream object's flags() function, and needF               is 0, then the function extracts the leading white-spaceH               characters from the istream object. The function returns 0G               if an error occurs while skipping white space; otherwise,s)               it returns a nonzero value.l                 void isfx()<A               Performs input suffix operations (used for internal                processing).          H                                                    iostream Package 4-55                    istream classc                   int peek()F               Begins by calling ipfx(1). If that call returns 0, or ifD               the istream object is at the end-of-file, the functionC               returns EOF. Otherwise, it returns the next characterc$               without extracting it.  &               istream &putback(char c)D               Tries to back up an istream object rdbuf() function. cG               must be the character before the get pointer belonging torE               the istream object rdbuf(). (Unless some other activitymG               is modifying the istream object rdbuf(), this is the lasteC               character extracted from the istream object.) If c issE               not the character before the get pointer, the effect ofiD               the function is undefined; the backup may fail and setF               the error state. The putback function is a member of theD               istream object, but it never extracts characters so itC               does not call ipfx. However, it returns without doinge5               anything if the error state is nonzero.   +               istream &read(char *s, int n) 4               istream &read(unsigned char *s, int n)@               Extracts n characters and stores them in the arrayA               begining at s. If it reaches the end-of-file before_C               extracting n characters, the function stores whatever D               it can extract and sets ios::failbit. To determine theF               number of characters extracted, use the istream gcount()               function.e  '               istream &seekg(streampos)r1               istream &seekg(streamoff, seek_dir) F               Repositions the get pointer of an istream object rdbuf()               function.                  int sync()F               Establishes consistency between internal data structuresE               and the external source of characters. Calls an istreamgE               object rdbuf()->sync(), which is a virtual function, soaE               the details depend on the derived class. Returns EOF to                indicate errors.                 void skipwhite()5               Skips extracted white-space characters.                4-56 iostream Package            H                                                            istream class                   streampos tellg()tC               Returns the current position of the get pointer of an .               istream object rdbuf() function.             Examples                 1. char c;                 cin.get(c);(  6                  Extracts a single character from cin.  '               2. tmp.seekg(10,ios::cur)   D                  Moves the point in a file from which information is'                  read forward 10 bytes.s           See Also                 ios class &               istream_withassign class               istrstream class                                              H                                                    iostream Package 4-57    e                istream_withassign class    H         ________________________________________________________________            istream_withassign class  C               Adds an assignment operator and a constructor with no ,               operands to the istream class.           Header File_  %               #include <iostream.hxx>                   Alternative Header  #               #include <iostream.h>c           Declaration   6               class istream_withassign: public istream               {i               public: ;                                       istream_withassign();<<                   virtual             ~istream_withassign();  ;                   istream_withassign &operator=(istream &);l=                   istream_withassign &operator=(streambuf *);;               };           Descriptions  F               This class adds an assignment operator and a constructor4               with no operands to the istream class.  $         Constructors and Destructors  "               istream_withassign()A               Constructs an istream_withassign object; it does no                initialization.a  +               virtual ~istream_withassign() E               Deletes an istream_withassign object; no user action isd               required.                  4-58 iostream Packages c         H                                                 istream_withassign class               Overloaded Operators  9               istream_withassign &operator = (istream &s) E               Associates an istream object's rdbuf() function with ancH               istream_withassign object and initializes the entire state               of that object.s  <               istream_withassign &operator = (streambuf *sb)A               Associates sb with an istream_withassign object and :               initializes the entire state of that object.                                                                    H                                                    iostream Package 4-59    &               istrstream class    H         ________________________________________________________________           istrstream class  G               Specializes the istream class to perform extractions froms(               arrays of bytes in memory.           Header File   &               #include <strstream.hxx>                  Alternative Header  $               #include <strstream.h>           Declaration   .               class istrstream: public istream               {                public:r9                                       istrstream(char *);r>                                       istrstream(char *, int);  /                   strstreambuf        *rdbuf();                };           Description   D               Objects of this class perform in-core extractions from(               arrays of bytes in memory.  $         Constructors and Destructors  "               istrstream(char *cp)D               Constructs an istrstream object and fetches charactersC               from the (null terminated) string cp. The terminating H               null character does not become part of the sequence. SeeksC               (istream::seekg()) are permitted within the allocatedr               space.  +               istrstream(char *cp, int len)aD               Constructs an istrstream object and fetches charactersB               from the array beginning at cp and extending for lenD               bytes. Seeks (istream::seekg()) are permitted anywhere                within that array.           4-60 iostream Package     ;      H                                                         istrstream class               Member Functionm  #               strstreambuf *rdbuf().A               Returns the strstreambuf object associated with thet                istrstream object.                                                                              H                                                    iostream Package 4-61 .                  OAPP(TYPE) class    H         ________________________________________________________________           OAPP(TYPE) class  F               For an ostream object, declares predefined parameterized               applicators.           Header File   $               #include <iomanip.hxx>                  Alternative Header  "               #include <iomanip.h>           Compile-Time Parameter  @               TYPE-The type of the ostream object. It must be an               identifier.e           Declarationy                 class OAPP(TYPE)               {o               public: =                   OAPP(TYPE)(ostream &(*f)(ostream &, TYPE)); 2                   OMANIP(TYPE) operator()(TYPE a);               };           Constructor   8               OAPP(TYPE)(ostream &(*f)(ostream &, TYPE))$               Creates an applicator.           Operator  /               OMANIP(TYPE) operator () (TYPE a)eG               Casts an object of type a into a manipulator function for                 an ostream object.                     4-62 iostream Package            H                                                         OAPP(TYPE) class               See Also                  OMANIP(TYPE) class                                                                                  H                                                    iostream Package 4-63 o                  ofstream class    H         ________________________________________________________________           ofstream class  '               Supports output to files.p           Header Filet  $               #include <fstream.hxx>                  Alternative Header  "               #include <fstream.h>           Declaration   ,               class ofstream: public ostream               {                public:h*                                ofstream();N                                ofstream(const char *name, int mode = ios::out,E                                        int prot = filebuf::openprot); 0                                ofstream(int fd);B                                ofstream(int fd, char *p, int len);+                                ~ofstream();   .                   void         attach(int fd);'                   void         close();xJ                   void         open(const char *name, int mode = ios::out,E                                        int prot = filebuf::openprot);n(                   filebuf      *rdbuf();8                   void         setbuf(char *p, int len);               };           Description   G               This class specializes the ostream class to files using arG               filebuf object to do the output. Your program can performoC               common operations, such as opening and closing files,e<               without explicitly mentioning filebuf objects.                   4-64 iostream Package-           H                                                           ofstream class      $         Constructors and Destructors                 ofstream()5               Constructs an unopened ofstream object.                  ofstream(int fd)E               Constructs an ofstream object connected to a file whose D               descriptor is passed through the fd argument. The file#               must already be open.   0               ofstream(int fd, char *p, int len)E               Constructs an ofstream object connected to a file whoseaD               descriptor is passed through the fd argument, and alsoF               initializes the associated filebuf object to use the lenF               bytes starting at p as the reserve area. If p is null or9               len is 0, the filebuf object is unbuffered.   <               ofstream(const char *name, int mode, int prot)H               Constructs an ofstream object and opens the file specifiedG               by the name argument. The mode and prot arguments specifylD               the file open mode and protection. By default, prot isC               filebuf::openprot. If the open fails, the error state E               (io_state) of the constructed ofstream object indicates                failure.                 ~ofstream().)               Deletes an ofstream object.e           Member Functions  !               void attach(int fd)nD               Connects an ofstream object to a file whose descriptorF               is passed through the fd argument. A failure occurs whenG               the ifstream object is connected to a file, in which case E               ios::failbit is set in the ofstream object error state.                  void close()C               Closes any associated filebuf object and consequently G               breaks the connection of the ofstream object to the file.sF               The error state of the ofstream object is cleared exceptG               on failure. A failure occurs when the call to the filebuf ,               object close() function fails.    H                                                    iostream Package 4-65                    ofstream class    =               void open(const char *name, int mode, int prot)hF               Opens a file specified by the name argument and connectsH               the ofstream object to it. If the file does not exist, theG               function tries to create it with the protection specifieduB               by the prot argument unless ios::nocreate is set. By1               default, prot is filebuf::openprot.e  C               Failure occurs if the ofstream object is open or whentF               the call to the filebuf object open() function fails, inD               which case ios::failbit is set in the filebuf object'sE               error state. The members of open_mode are bits that mayrF               be joined together by or (and because this joining takesB               an int, open() takes an int rather than an open_modeD               argument). For an explanation of the meanings of theseE               bits in open_mode, see the Enumerated Types section fore               the ios class.                 filebuf *rdbuf()E               Returns a pointer to the filebuf object associated with H               the ofstream object. This function has the same meaning as5               ios::rdbuf(), but has a different type.o  +               void setbuf(char *p, int len) F               Calls the associated filebuf object setbuf() function toG               request space for a reserve area. A failure occurs if theaF               filebuf object is open or if the call to rdbuf()->setbuf)               fails for any other reason.                                              4-66 iostream Packageh c  s      H                                                       OMANIP(TYPE) class    H         ________________________________________________________________           OMANIP(TYPE) class  F               For an ostream object, declares predefined parameterized?               manipulators and provides macros for user-defined&)               parameterized manipulators.a           Header File   $               #include <iomanip.hxx>                  Alternative Header  "               #include <iomanip.h>           Compile-Time Parameter  @               TYPE-The type of the ostream object. It must be an               identifier.t           Declarations                  class OMANIP(TYPE)               {a               public: E                   OMANIP(TYPE)(ostream &(*f)(ostream &, TYPE), T a );aK                   friend ostream &operator<<(ostream & s, OMANIP(TYPE) &m);                };           Descriptionn  E               These manipulators serve the ostream class by producingtC               some useful effect, such as embedding a function calljD               in an expression containing a series of insertions andG               extractions. You also can use manipulators to shorten theuD               long names and sequences of operations required by the               ostream class.  C               In its simplest form, a manipulator takes an ostream&rC               argument, operates on it in some way, and returns it.p        H                                                    iostream Package 4-67    i               OMANIP(TYPE) class               Constructor   @               OMANIP(TYPE)(ostream &(*f)(ostream &, TYPE), T a )$               Creates a manipulator.           Operator  A               ostream &operator << (ostream & s, OMANIP(TYPE) &m)s.               Sends data to an ostream object.                                                                               4-68 iostream Packaget    r      H                                                            ostream class    H         ________________________________________________________________           ostream class   8               Supports insertion into streambuf objects.           Header Fileh  %               #include <iostream.hxx>                   Alternative Header  #               #include <iostream.h>            Declarationa  0               class ostream : virtual public ios               {s               public:s;                                       ostream(streambuf *); 1                   virtual             ~ostream();s  /                   ostream             &flush();l-                   int                 opfx(); -                   void                osfx();n3                   ostream             &put(char c);e8                   ostream             &seekp(streampos);B                   ostream             &seekp(streamoff, seek_dir);.                   streampos           tellp();E                   ostream             &write(const char *ptr, int n);cN                   inline ostream      &write(const unsigned char *ptr, int n);@                   ostream             &operator<<(const char *);8                   ostream             &operator<<(char);9                   inline ostream      &operator<<(short);e7                   ostream             &operator<<(int);e8                   ostream             &operator<<(long);9                   ostream             &operator<<(float); :                   ostream             &operator<<(double);I                   ostream             &operator<<(const unsigned char *); A                   inline ostream      &operator<<(unsigned char);eB                   inline ostream      &operator<<(unsigned short);@                   ostream             &operator<<(unsigned int);A                   ostream             &operator<<(unsigned long);t:                   ostream             &operator<<(void *);  H                                                    iostream Package 4-69 t                  ostream class     ?                   ostream             &operator<<(streambuf *); L                   inline ostream      &operator<<(ostream &(*f)(ostream &));D                   ostream             &operator<<(ios &(*f)(ios &));                 protected:0                                       ostream();               };           Description   E               Objects of this class perform formatted and unformattede0               insertions into streambuf objects.  $         Constructors and Destructors  #               ostream(streambuf *b)tD               Constructs an istream object. It initializes ios stateD               variables and associates the buffer b with the ostream               object.                   virtual ~ostream()(               Deletes an ostream object.           Overloaded Operators  >               The following operators are all formatted outputH               inserters. Given the expression outs << x, these operators?               insert into outs.rdbuf() a sequence of characters E               representing x. The argument to the operator determines E               the type of x. Insertions are performed after a call to C               outs.opfx() only if that call returns nonzero. ErrorsgE               are indicated by setting the error state of the ostream <               object. The ostream object is always returned.  D               Conversion of x to a sequence of characters depends onE               the type of x and on the values of the ostream object's D               format state flags and variables. Padding occurs afterF               this representation is determined. If width() is greater@               than 0, and the representation contains fewer thanF               width() characters, then the function adds enough fill()C               characters to bring the total number of characters totB               ios::width(). If ios::left() is set, the sequence isC               left-adjusted; that is, the function puts the padding G               after the sequence of characters. If ios::right() is set,sD               the padding is added before the character sequence. If           4-70 iostream Package            H                                                            ostream class    D               ios::internal() is set, the padding is added after anyG               leading sign or base indication and before the characters B               that represent the value. ios::width() is reset to 0D               but all other format variables are unchanged. The fullE               sequence (padding plus representation) is inserted into 2               the ostream object rdbuf() function.  +               ostream &operator << (char x) 4               ostream &operator << (unsigned char x)E               Inserts a character x. No special conversion is needed.   2               ostream &operator << (const char *x);               ostream &operator << (const unsigned char *x) H               Inserts a sequence of characters up to (but not including)B               the terminating null of the string that x points at.  ,               ostream &operator << (short x)*               ostream &operator << (int x)+               ostream &operator << (long x)i5               ostream &operator << (unsigned short x) 3               ostream &operator << (unsigned int x)u4               ostream &operator << (unsigned long x),               Inserts characters as follows:  @               o  If x is positive, the representation contains aC                  sequence of octal digits if ios::oct is set in the D                  ios object format flags, decimal digits if ios::decE                  is set, or hexadecimal digits if ios::hex is set. If_H                  none of these flags are set, the conversion defaults to                  decimal.e  F               o  If x is negative, decimal conversion includes a minus5                  sign (-) followed by decimal digits.   B               o  If x is positive and ios::showpos is set, decimalH                  conversion includes a plus sign (+) followed by decimal                  digits.  C               o  Conversions other than decimal treat all values as                   unsigned.  H               o  If ios::showbase is set, the hexadecimal representation@                  contains 0x before the hexadecimal digits or 0XC                  if ios::uppercase is set; the octal representation &                  contains a leading 0.  H                                                    iostream Package 4-71                    ostream classm    ,               ostream &operator << (float x)-               ostream &operator << (double x)nD               Converts the arguments according to the current values?               of the ostream object's precision() function, the @               ostream object's width() function, and the ostreamE               object's format flags: ios::scientific, ios::fixed, andeH               ios::uppercase. The default value for the ostream object'sG               precision() function is 6. If neither ios::scientific noreF               ios::fixed is set, the value of x determines whether the?               representation uses scientific or fixed notation.   ,               ostream &operator << (void *v)D               Converts pointers to integral values and then convertsF               them to hexadecimal numbers as if ios::showbase was set.  2               ostream &operator << (streambuf *sb)F               Given the expression outs << sb, inserts into sb.rdbuf()E               the sequence of characters that can be fetched from sb. G               When no more characters can be fetched from sb, insertion_E               stops. This function does no padding. It always returnsd!               the ostream object.   5               ostream &operator << (ios &(*f)(ios &)) G               Calls an ios object manipulator function f for an ostream                object.a  =               ostream &operator << (ostream &(*f)(ostream &))eC               Calls an ostream object manipulator function f for ane               ostream object.            Other Member Functions                 ostream &flush()A               Calls the ostream object's rdbuf()->sync() function B               to consume (that is, write to the external file) anyC               characters that may have been stored into a streambufe.               object but are not yet consumed.                 int opfx()G               Performs output prefix actions. If the error state of thejG               ostream object is nonzero, it returns immediately. If theoG               value of the ostream object's tie() function is not null, E               it is flushed. The function returns nonzero except when ?               the error state of the ostream object is nonzero.            4-72 iostream Package            H                                                            ostream class                   void osfx() B               Performs output suffix actions before returning fromF               inserters. If ios::unitbuf is set, this function flushesD               the ostream object. If ios::stdio is set, the functionG               flushes stdout and stderr. It is called by all predefined B               inserters, and should also be called by user-definedF               inserters after any direct manipulation of the streambufF               object. It is not called by the binary output functions.  +               ostream &ostream::put(char c)sF               Inserts c into the ostream object's rdbuf() function. It:               sets the error state if the insertion fails.  '               ostream &seekp(streampos)d1               ostream &seekp(streamoff, seek_dir) A               Repositions the put pointer of the ostream object's                rdbuf() function.e                 streampos tellp() G               Returns the current position of the put pointer belonging 7               to the ostream object's rdbuf() function.   4               ostream &write(const char *ptr, int n)=               ostream &write(const unsigned char *ptr, int n)iG               Inserts the n characters starting at ptr into the ostream E               object's rdbuf() function. These characters may includeaG               zeros; that is, ptr need not be a null-terminated string.f           Example                  char c = 'Z';                cout.put(c);  7               Inserts a single character (Z) into cout.            See Also  &               ostream_withassign class               ostrstream class            H                                                    iostream Package 4-73 t                   ostream_withassign class    H         ________________________________________________________________            ostream_withassign class  C               Adds an assignment operator and a constructor with no ,               operands to the ostream class.           Header Filef  %               #include <iostream.hxx>                   Alternative Header  #               #include <iostream.h>            Declaration   6               class ostream_withassign: public ostream               {                public: ;                                       ostream_withassign();n<                   virtual             ~ostream_withassign();  <                   ostream_withassign  &operator=(ostream &);>                   ostream_withassign  &operator=(streambuf *);               };           Description   F               This class adds an assignment operator and a constructor4               with no operands to the ostream class.  $         Constructors and Destructors  "               ostream_withassign()A               Constructs an ostream_withassign object; it does noe               initialization.   +               virtual ~ostream_withassign()tE               Deletes an ostream_withassign object; no user action is                required.                  4-74 iostream Packagei e  c      H                                                 ostream_withassign class               Overloaded Operators  9               ostream_withassign &operator = (ostream &s)cE               Associates s.rdbuf() with the ostream_withassign objectn>               and initializes the entire state of that object.  <               ostream_withassign &operator = (streambuf *sb)A               Associates sb with an ostream_withassign object andw:               initializes the entire state of that object.                                                                      H                                                    iostream Package 4-75    o               ostrstream class    H         ________________________________________________________________           ostrstream class  G               Supports the insertion of characters into arrays of bytesi               in memory.           Header Filee  &               #include <strstream.hxx>                  Alternative Header  $               #include <strstream.h>           Declarationa  .               class ostrstream: public ostream               {                  public:b1                                     ostrstream(); L                                     ostrstream(char *, int, int = ios::out);2                                     ~ostrstream();  -                    int              pcount();j-                    strstreambuf     *rdbuf();s+                    char             *str();                };           Descriptiona  B               This class specializes the ostream class for in-coreD               operations by providing members that insert characters-               into arrays of bytes in memory.t  $         Constructors and Destructors                 ostrstream()G               Constructs an ostrstream object and dynamically allocatesa.               space to hold stored characters.                 4-76 iostream Packagel h  s      H                                                         ostrstream class    ?               ostrstream::ostrstream(char *cp, int n, int mode)iH               Constructs an ostrstream object and stores characters intoE               the array starting at cp and continuing for n bytes. IfaH               ios::ate or ios::app is set in mode, the function takes cpE               to be a null-terminated string and it begins storing at_E               the null character; otherwise, it begins storing at cp. 6               Seeks are allowed anywhere in the array.                 ~ostrstream()a+               Deletes an ostrstream object.            Member Functions                 int pcount()H               Returns the number of bytes that have been stored into theG               buffer. This function is useful when binary data has beenrF               stored and the ostrstream object str() function does not0               point to a null-terminated string.  #               strstreambuf *rdbuf() E               Returns the strstreambuf associated with the ostrstreamt               object.Y                 char *str() G               Returns a pointer to the array being used and freezes the G               array. After str() has been called, the effect of storingeH               more characters into the strstream object is undefined. IfC               the strstream object was constructed with an explicit A               array, the function returns a pointer to the array;sH               otherwise, it returns a pointer to a dynamically allocatedC               area. Until str() is called, deleting the dynamically C               allocated area is the responsibility of the strstream E               object. After str() returns, dynamic allocation becomes 5               the responsibility of the user program.            Examplei  #               char *bptr = bf.str()   C               Initializes the variable bptr with the address of theeG               array associated with the ostrstream object bf. This letstE               you manipulate the array through bptr just as you woulds"               any character array.    H                                                    iostream Package 4-77                    SAPP(TYPE) class    H         ________________________________________________________________           SAPP(TYPE) class  B               Defines parameterized applicators for an ios object.           Header File   $               #include <iomanip.hxx>                  Alternative Header  "               #include <iomanip.h>           Compile-Time Parameter  H               TYPE-The type of the ios object. It must be an identifier.           Declaration                  class SAPP(TYPE)                 {u               public: 5                   SAPP(TYPE)(ios &(*f)(ios &, TYPE)); 2                   SMANIP(TYPE) operator()(TYPE a);               };           Constructor   0               SAPP(TYPE)(ios &(*f)(ios &, TYPE))$               Creates an applicator.           Operator  /               SMANIP(TYPE) operator () (TYPE a) G               Casts an object of type a into a manipulator function for +               an istream or ostream object.            See Also                  SMANIP(TYPE) class               4-78 iostream Packagec    r      H                                                       SMANIP(TYPE) class    H         ________________________________________________________________           SMANIP(TYPE) class  C               Defines parameterized manipulators for an ios object.a           Header File   $               #include <iomanip.hxx>                  Alternative Header  "               #include <iomanip.h>           Compile-Time Parameter  H               TYPE-The type of the ios object. It must be an identifier.           Declarations                  class SMANIP(TYPE)               {                public:i?                   SMANIP(TYPE)(ios &(*f)(ios &, TYPE), TYPE a);nJ                   friend istream &operator>>(istream &i, SMANIP(TYPE) &m);J                   friend ostream &operator<<(ostream &o, SMANIP(TYPE) &m);               };           Description   A               These manipulators serve the ios class by producing C               some useful effect, such as embedding a function call D               in an expression containing a series of insertions andG               extractions. You also can use manipulators to shorten thesH               long names and sequences of operations required by the ios               class.  ?               In its simplest form, a manipulator takes an ios&sC               argument, operates on it in some way, and returns it.b            H                                                    iostream Package 4-79 e  u               SMANIP(TYPE) class               Constructor   :               SMANIP(TYPE)(ios &(*f)(ios &, TYPE), TYPE a)$               Creates a manipulator.           Operatorse  @               ostream &operator << (ostream &o, SMANIP(TYPE) &m).               Sends data to an ostream object.  @               istream &operator >> (istream &i, SMANIP(TYPE) &m)0               Takes data from an istream object.                                                                         4-80 iostream Package     n      H                                                           stdiobuf class    H         ________________________________________________________________           stdiobuf class  B               Provides input/output facilities through stdio FILE.           Header File   (               #include <stdiostream.hxx>                  Alternative Header  &               #include <stdiostream.h>           Declarationn  .               class stdiobuf: public streambuf               {e               public: 8                                       stdiobuf(FILE *f);  7                   virtual int         overflow(int = );pM                   virtual streampos   seekoff(streamoff, seek_dir, int mode); 3                   FILE                *stdiofile();t-                   virtual int         sync();i2                   virtual int         underflow();               };           Description:  B               This class specializes the streambuf class for stdioH               FILE. It uses unbuffered mode causing all operations to be6               reflected immediately in the stdio FILE.           Constructora                 stdiobuf(FILE *f) H               Constructs an empty stdiobuf object and connects it to the7               stdio FILE that the argument f points to.             H                                                    iostream Package 4-81    n               stdiobuf class               Member Functions  )               virtual int overflow(int c)eA               Called to consume characters. If c is not EOF, this F               function must also either save c or consume it. AlthoughG               it can be called at other times, this function is usually F               called when the put area is full and an attempt is beingD               made to store a new character. The normal action is toE               consume the characters between pbase() and pptr(), call)C               setp() to establish a new put area, and (if c != EOF) D               store c using sputc(). The overflow(c) function shouldC               return EOF to indicate an error; otherwise, it should $               return something else.  H               virtual streampos seekoff(streamoff off, seek_dir dir, int               mode) G               Repositions the abstract get and put pointers (not pptr()aC               and gptr()). mode specifies whether to modify the put(B               pointer (ios::out bit set), the get pointer, or bothE               (ios::in bit set). off is interpreted as a byte offset. A               For the meanings of dir, see the explanation of the 4               enumerated type seek_dir in class ios.  G               A class derived from streambuf is not required to support.@               repositioning. If the derived class does not, thenD               seekoff() should return EOF. If the derived class doesD               support repositioning, seekoff() should return the new'               position or EOF on error.                  FILE *stdiofile()sE               Returns a pointer to the stdio FILE associated with then               stdiobuf object.                  virtual int sync()D               Should consume any characters stored into the put areaF               and, if possible, give back to the source any charactersE               in the get area that have not been fetched. When sync()iG               returns, there should be no unconsumed characters and thetG               get area should be empty. If some kind of failure occurs, -               the function should return EOF.1                 4-82 iostream Package            H                                                           stdiobuf class    %               virtual int underflow()nC               Called to supply characters for fetching; that is, tocD               create a condition in which the get area is not empty.C               If this function is called when characters are in the:D               get area, it should return the first character. If theE               get area is empty, it should create a nonempty get area G               and return the next character (which it should also leavevD               in the get area). If no more characters are available,B               underflow() should return EOF and leave an empty get               area.                                                                       H                                                    iostream Package 4-83 s  a               stdiostream class     H         ________________________________________________________________           stdiostream classe  <               Specializes the iostream class for stdio FILE.           Header Filef  (               #include <stdiostream.hxx>                  Alternative Header  &               #include <stdiostream.h>           Declarations  0               class stdiostream: public iostream               {j               public:n3                               stdiostream(FILE *f); -                               ~stdiostream();a  '                   stdiobuf    *rdbuf();c               };           Description   G               This class specializes the iostream class for stdio FILE,sC               and causes that class to use a stdiobuf object as itsc*               associated streambuf object.  E               In most other existing implementations, the stdiostreamaF               class is derived directly from the ios class rather thanE               from the iostream class. Deriving the stdiostream classfF               from the ios class limits its usefulness and, therefore,G               can be considered a historical mistake. Nevertheless, foreH               maximum portability, you should use only those stdiostreamF               features that originate from the ios class and avoid the6               features supplied by the iostream class.                     4-84 iostream Package            H                                                        stdiostream class      $         Constructors and Destructors  "               stdiostream(FILE *f)F               Constructs a stdiostream object whose stdiobuf object isD               associated with the FILE parameter that the f argument               points to.                 ~stdiostream()D               Deletes a stdiostream object and closes the associated               stdiobuf object.                                                                    H                                                    iostream Package 4-85 :  (               stdiostream class                Member Function(                 stdiobuf *rdbuf()tF               Returns a pointer to the stdiobuf object associated with%               the stdiostream object.p                                                                                       4-86 iostream Packageu    c      H                                                          streambuf class    H         ________________________________________________________________           streambuf class   8               Provides the buffer mechanism for streams.           Header Files  %               #include <iostream.hxx>n                  Alternative Header  #               #include <iostream.h>e           DeclarationT                 class streambuf                {t               public: 2                                       streambuf();B                                       streambuf(char *p, int len);3                   virtual             ~streambuf(); ,                   void                dbp();                 protected:1                   int                 allocate(); .                   char                *base();-                   int                 blen();   ,                   virtual int  doallocate();  /                   char                *eback();h.                   char                *ebuf();/                   char                *egptr(); /                   char                *epptr();r3                   void                gbump(int n); .                   char                *gptr();/                   char                *pbase(); 3                   void                pbump(int n);m.                   char                *pptr();I                   void                setb(char *b, char *eb, int a = 0); H                   void                setg(char *eb, char *g, char *eg);>                   void                setp(char *p, char *ep);3                   int                 unbuffered(); 8                   void                unbuffered(int n);  H                                                    iostream Package 4-87 r                  streambuf classa                   public: +                   int                 fd();r.                   void                fd(int);,                   FILE                *fp();1                   void                fp(FILE *);e1                   int                 in_avail(); 4                   int                 out_waiting();  <                   virtual int         overflow(int c = EOF);7                   virtual int         pbackfail(int c);o  /                   int                 sbumpc();&  F                   virtual streampos   seekpos(streampos, int = ios::in2                                       | ios::out);B                   virtual streampos   seekoff(streamoff, seek_dir,@                                       int = ios::in | ios::out);B                   virtual streambuf   *setbuf(char *ptr, int len);  K                   streambuf           *setbuf(unsigned char *ptr, int len); I                   streambuf           *setbuf(char *ptr, int len, int i); .                   int                 sgetc();>                   int                 sgetn(char *ptr, int n);/                   int                 snextc(); 8                   int                 sputbackc(char c);9                   int                 sputc(int c = EOF);FB                   int                 sputn(const char *s, int n);/                   void                stossc();a  -                   virtual int         sync();s2                   virtual int         underflow();               };           Description   C               This class supports buffers into which you can insertrE               (put) or extract (get) characters. It contains only the B               basic members for manipulating the characters. Also,G               several of its member functions are virtual; to implement G               virtual functions, you typically use a class derived from "               the streambuf class.  B               The protected members of the streambuf class presentB               an interface to derived classes organized around theF               get, put, and reserve areas (arrays of bytes), which areD               managed cooperatively by the base and derived classes.           4-88 iostream Packaget d  a      H                                                          streambuf class    B               The reserve area is a sequence of characters with anE               associated get pointer, put pointer, or both. This areaoD               serves mainly as a resource in which to allocate spaceE               for the put and get areas. As characters enter and exit D               the reserve area, the put and get areas change but theC               reserve area remains fixed. A collection of character D               pointer values defines the three areas. These pointersF               infer a boundary condition; therefore, it may be helpfulC               to consider such pointers as pointing just before thee:               byte, even though they point directly at it.  F               Classes derived from streambuf vary in their handling ofG               the get and put pointers. The simplest are unidirectional C               buffers that permit only get and put operations. Such E               classes serve as producers and consumers of characters.uE               Queue-like buffers (such as strstream and strstreambuf)rE               have a put and a get pointer that move independently of G               each other. In such buffers, stored characters are queued F               until later fetched. File-like buffers (such as filebuf)F               allow both get and put operations but have their get andD               put pointers linked together, so that when one pointer&               moves so does the other.  F               You can call virtual functions to manage the collectionsG               of characters in the get and put areas. Services suppliedhC               by virtual functions include fetching more characters D               from an ultimate producer and flushing a collection of1               characters to an ultimate consumer.o  C               If your program expects a buffer to be allocated whenbG               none was allocated, then the iostream package allocates ao               default buffer.o           Data Membere                 void dbp()A               Writes directly on file descriptor 1 information insA               ASCII about the state of the buffer. It is intended C               for debugging and nothing is specified about the form F               of the output. What it prints out can be understood onlyD               in relation to the protected interface, but dbp() is aF               public domain function so that it can be called anywhere               during debugging.a    H                                                    iostream Package 4-89 >                  streambuf class       $         Constructors and Destructors                 streambuf().B               Constructs an empty buffer corresponding to an empty               sequence.   /               streambuf(char* base, int length)sE               Constructs an empty buffer and then sets up the reserve <               area to be length bytes long starting at base.  "               virtual ~streambuf();               Deletes the reserve area if one is allocated.                                                                          4-90 iostream Packagef t         H                                                          streambuf class               Member Functions                 int allocate()G               Tries to set up a reserve area. If a reserve area alreadyNA               exists or is unbuffered, it returns 0 without doing_B               anything. If the attempt to allocate space succeeds,A               allocate() returns 1; otherwise, it returns EOF. No G               nonvirtual member functions of streambuf call allocate().l                 char *base()F               Returns a pointer to the first byte of the reserve area.F               The space between base() and ebuf() is the reserve area.                 int blen()D               Returns the size, in type char, of the current reserve               area.T  &               virtual int doallocate()E               In streambuf, it tries to allocate a reserve area using;               the new operator.m  A               In classes derived from streambuf, this function is E               called when allocate() determines that space is needed.bC               doallocate() is required to call setb(), to provide auG               reserve area, or to return EOF if it cannot. It is calledt9               only if both unbuffered() and base() are 0.u                 char *eback() E               Returns a pointer to a lower bound on gptr(). The space A               between eback() and gptr() is available for putback                operations.                  char *ebuf()F               Returns a pointer to the byte after the last byte of the               reserve area.a                 char *egptr() F               Returns a pointer to the byte after the last byte of the               get area.Y                 char *epptr()aF               Returns a pointer to the byte after the last byte of the               put area.P  H                                                    iostream Package 4-91 r                  streambuf classP                   int fd()G               Returns the file descriptor associated with the streambuf 7               object, if any; otherwise, it returns -1.                  void fd(int f)D               Sets the file descriptor associated with the streambuf               object to f.                 FILE *fp()D               Returns the file pointer associated with the streambuf6               object, if any; otherwise, it returns 0.                 void fp(FILE *f)H               Sets the file pointer associated with the streambuf object               to f.                  void gbump(int n)sB               Increments gptr() by n, which can be a positive or aD               negative number. No checks are made on whether the new*               value of gptr()is in bounds.                 char *gptr()B               Returns a pointer to the first byte of the get area.C               The characters available are those between gptr() and A               egptr(). The next character fetched will be *gptr()o=               unless egptr() is less than or equal to gptr().                  int in_avail()D               Returns the number of characters immediately availableE               in the get area for fetching. This number is the numberdG               of characters that can be fetched with confidence that an )               error will not be reported.c                 int out_waiting() H               Returns the number of characters in the put area that have;               not been consumed (by the ultimate consumer).   )               virtual int overflow(int c) E               In streambuf, this function should be treated as if its C               behavior is undefined; classes derived from streambuf &               should always define it.                 4-92 iostream Package  c  b      H                                                          streambuf class    H               In classes derived from streambuf, it is called to consumeG               characters. If c is not EOF, overflow(c) also must eitherbF               save c or consume it. Although it can be called at otherA               times, this function is usually called when the put.F               area is full and an attempt is being made to store a newG               character. The normal action is to consume the characters E               between pbase() and pptr(), call setp()  to establish a D               new put area, and (if c != EOF) store c using sputc().A               overflow(c) should return EOF to indicate an error; 9               otherwise, it should return something else.   *               virtual int pbackfail(int c)=               In streambuf, this function always returns EOF.   H               In classes derived from streambuf, this function is calledE               when eback() equals gptr() and an attempt has been madeiB               to put c back. If this situation can be managed (forG               example, by repositioning an external file), pbackfail(c)u?               should return c; otherwise, it should return EOF.e                 char *pbase()eH               Returns a pointer to the put area base. Characters betweenG               pbase() and pptr() are stored into the buffer but are noti               yet consumed.                  void pbump(int n)i>               Increments pptr() by n, which can be positive orC               negative. No checks are made on whether the new valuet%               of pptr() is in bounds.                  char *pptr()F               Returns a pointer to the first byte of the put area. The?               space between pptr() and epptr() is the put area.p                 int sbumpc()E               Moves the get pointer forward one character and returns F               the character it moved past. The function returns EOF ifF               the get pointer is currently at the end of the sequence.  F               virtual streampos seekoff(streamoff off, (ios::)seek_dir               dir, int mode)6               In streambuf, this function returns EOF.      H                                                    iostream Package 4-93 a  t               streambuf classt    C               In classes derived from streambuf, it repositions thegD               abstract get and put pointers (not pptr() and gptr()).H               mode specifies whether to modify the put pointer (ios::outC               bit set) or the get pointer (ios::in bit set) or bothpB               pointers. off is interpreted as a byte offset (it is?               a signed value). For the meanings of dir, see the G               explanation of the enumerated type seek_dir in class ios.   G               A class derived from streambuf is not required to support_@               repositioning. If the derived class does not, thenD               seekoff() should return EOF. If the derived class doesD               support repositioning, seekoff() should return the new'               position or EOF on error.>  @               virtual streampos seekpos(streampos pos, int mode)I               In streambuf, this function returns seekoff(streamoff(pos), D               ios::beg, mode). To define seeking in a derived class,B               you can often define seekoff() and use the inherited!               streambuf::seekpos.   >               In classes derived from streambuf, this functionA               repositions the streambuf get pointer, put pointer,cD               or both, to pos. mode specifies the affected pointers.D               seekpos() returns the argument pos or EOF if the classC               does not support repositioning or if an error occurs.m?               streampos(0) signifies the beginning of the file; 0               streampos(EOF) indicates an error.  1               void setb(char *b, char *eb, int a)l?               Sets base() to b and ebuf() to eb. The a argumentyB               controls whether the reserve area will be subject toA               automatic deletion. If a is nonzero, then b will bepG               deleted when base() is changed by another call to setb(), @               or when the destructor is called for the streambufF               object. If b and eb are both null, then the reserve areaD               effectively does not exist. If b is nonnull, a reserveF               area exists even if eb is less than b (in which case the)               reserve area has 0 length).   ;               virtual streambuf *setbuf(char *ptr, int len)e<               streambuf *setbuf(unsigned char *ptr, int len)B               In streambuf, this function honors the request for a,               reserve area if there is none.             4-94 iostream Package  k         H                                                          streambuf class    E               In classes derived from streambuf, this function offerssH               for use as a reserve area the array at ptr with len bytes.E               Normally, if ptr or len is 0, the action is interpreted C               as a request to make the streambuf object unbuffered. D               The derived class has the choice of using or not usingF               this area by accepting or ignoring the request. setbuf()F               should return a reference to the streambuf object if theD               derived class honors the request; otherwise, it should               return 0.t  :               streambuf *setbuf(char *ptr, int len, int i)A               Offers the len bytes starting at ptr as the reserve E               area. If ptr is null, or len is 0 or negative, then the;H               function requests an unbuffered state. Whether the offeredB               area is used or a request for an unbuffered state isG               honored depends on details of the derived class. setbuf() G               normally returns a reference to the streambuf object, butbE               if the derived class does not accept the offer or honor .               the request, setbuf() returns 0.  4               void setg(char *eb, char *g, char *eg)B               Sets eback() to eb, gptr() to g, and egptr()  to eg.  *               void setp(char *p, char *ep)=               Sets base() and pptr() to p and epptr()  to ep.)                 int sgetc() F               Returns the character after the get pointer; it does notE               move the get pointer. It returns EOF if no character is                available.  )               int sgetn(char *ptr, int n)b@               Fetches n characters following the get pointer andF               copies them to the area starting at ptr. If fewer than nF               characters occur before the end of the sequence, sgetn()D               fetches the characters that remain. It repositions theF               get pointer after the fetched characters and returns the+               number of characters fetched.a                 int snextc()E               Moves the get pointer forward one character and returns E               the character after the new position. If the pointer is G               at the end of the sequence, either before or after moving 0               forward, the function returns EOF.  H                                                    iostream Package 4-95 i  c               streambuf classt    #               int sputbackc(char c) E               Moves the get pointer back one character. c must be theaA               current content of the sequence just before the get C               pointer. The underlying mechanism may back up the get C               pointer or may rearrange its internal data structuresnA               so that c is saved. The effect is undefined if c istD               not the character before the get pointer. The functionE               returns EOF, by calling pbackfail(), when it fails. The F               conditions under which it can fail depend on the details#               of the derived class.                  int sputc(int c)F               Stores c after the put pointer and moves the put pointerA               past the stored character (usually this extends the G               sequence). The function returns EOF when an error occurs. D               Conditions that can cause errors depend on the derived               class.  -               int sputn(const char *s, int n) D               Stores after the put pointer the n characters startingC               at s, and moves the put pointer past them. It returnsuF               the number of characters successfully stored. Normally nF               characters are successfully stored, but fewer characters.               may be stored when errors occur.                 void stossc()nG               Moves the get pointer ahead one character. If the pointeroA               started at the end of the sequence, stossc() has noe               effect.b                  virtual int sync()E               In streambuf this function returns 0 if the get area istH               empty and no unconsumed characters are present; otherwise,               it returns EOF.i  H               In classes derived from streambuf, this function is calledB               to let derived classes examine the state of the put,D               get, and reserve areas, and to synchronize these areasF               with any external representation. Normally sync() shouldE               consume any characters stored into the put area and, if E               possible, give back to the source any characters in the G               get area that have not been fetched. When sync() returns, E               no unconsumed characters should remain and the get area              4-96 iostream Packagee    s      H                                                          streambuf class    E               should be empty. If some kind of failure occurs, sync()                 should return EOF.                 int unbuffered()@               Returns the current buffering state flag, which is?               independent of the actual allocation of a reserveoB               area. This function's primary purpose is to find outC               if a reserve area is being allocated automatically byr               allocate().u  $               void unbuffered(int n)F               Sets the value of the current buffering state flag. If nH               equals 0, then the streambuf object is buffered; otherwiseE               it is unbuffered. This function's primary purpose is tohG               control whether a reserve area is allocated automaticallye               by allocate().  %               virtual int underflow()eE               In streambuf, this function should be treated as if itsaH               behavior is undefined; classes derived from streambuf must               define it.  G               In classes derived from streambuf, it is called to supplynE               characters for fetching; that is, to create a conditiongE               in which the get area is not empty. If this function is C               called when characters are in the get area, it should C               return the first character. If the get area is empty, F               it should create a nonempty get area and return the nextE               character (which it should also leave in the get area).rE               If no more characters are available, underflow() shouldt5               return EOF and leave an empty get area.i           Example                         H                                                    iostream Package 4-97 o  e               streambuf class     .               static const int bufsize = 1024;!               char buf[bufsize] ;                int p, g ;               do {%                       in->sgetc() ; 1a-                       g = in->in_avail() ;  2 7                       if (g > bufsize) g = bufsize ;  3 ,                       g = in->sgetn(buf,g) ;,                       p = out->sput(buf,g) ;&                       out->sync() ;  46                       if (p!=g) error("output error");%                       } while (g > 0)   C               Provides a way to pass characters into the in and outsH               arrays as soon as the characters become available (as when=               someone types them from a terminal) as follows:   H               1  Ensures at least one character is immediately availableF                  in the in array (unless the get pointer is at the end"                  of the sequence).  H               2  Returns the number of characters immediately available.  B               3  Checks that chunks in which the characters becomeC                  available are less than bufsize, and that they fitl!                  into the arrays.   H               4  Sends characters put into the out array to the ultimate                  consumer.                                         4-98 iostream Package     e      H                                                          strstream class    H         ________________________________________________________________           strstream classe  H               Specializes the iostream class for storing in and fetching#               from arrays of bytes.            Header Filei  &               #include <strstream.hxx>                  Alternative Header  $               #include <strstream.h>           Declaration   .               class strstream: public iostream               {d               public:o/                                    strstream(); ?                                    strstream(char *, int, int);c  ,                   strstreambuf     *rdbuf();*                   char             *str();               };           Descriptiono  C               This class specializes the iostream class for storing B               in and fetching from arrays of bytes. It handles allE               predefined data types, and provides an extensive set ofeC               options for performing input and output on these data                types.  $         Constructors and Destructors                 strstream() F               Constructs an strstream object and dynamically allocates.               space to hold stored characters.  2               strstream(char *cp, int n, int mode)G               Constructs an strstream object. It stores characters into E               the array starting at cp and continuing for n bytes. IfhG               ios::ate or ios::app is set in mode, cp is presumed to bef  H                                                    iostream Package 4-99    s               strstream class     E               a null-terminated string and storing begins at the null C               character; otherwise, storing begins at cp. Seeks are .               permitted anywhere in the array.             Member Functions  #               strstreambuf *rdbuf() E               Returns a pointer to the strstreambuf object associated &               with a strstream object.                 char *str() G               Returns a pointer to an explicit array, to be used as theeE               associated strstreambuf object, if the strstream object G               was constructed with such an array; otherwise, it returnsbD               a pointer to a dynamically allocated area. Until str()C               is called, deleting the dynamically allocated area iseE               the responsibility of the strstream object. After str()tG               returns, dynamic allocation becomes the responsibility ofbG               the user program. After str() has been called, the effect E               of storing more characters into the strstream object isc               undefined.                                                       4-100 iostream Package _  t      H                                                       strstreambuf class    H         ________________________________________________________________           strstreambuf class  B               Specializes the streambuf class for input and output5               performed on arrays of bytes in memory.d           Header File   &               #include <strstream.hxx>                  Alternative Header  $               #include <strstream.h>           Declaration   2               class strstreambuf: public streambuf               {,               public:e5                                       strstreambuf();)H                                       strstreambuf(char *, int, char *);8                                       strstreambuf(int);H                                       strstreambuf(unsigned char *, int,7                                       unsigned char *);rD                                       strstreambuf(void *(*a)(long),9                                       void (*f)(void *));e  8                   void                freeze(int n = 1);4                   virtual int         overflow(int);;                   virtual streambuf   *setbuf(char *, int);l-                   char                *str(); 2                   virtual int         underflow();               };           Descriptions  D               Objects of this class let you use an array of bytes (aC               string of characters) in memory as a streambuf objecttD               for stream input/output operations on various kinds ofE               data. Mapping between abstract get and put pointers anddB               char * pointers is direct in the sense that a char *D               is interpreted as logically pointing immediately aheadD               of the char it actually points to. Moving the pointers  H                                                   iostream Package 4-101 n                  strstreambuf class    E               corresponds to incrementing and decrementing the char *                values.   F               To accommodate the need for strings of arbitrary length,E               this class supports a dynamic mode. When a strstreambuf C               object is in dynamic mode, space for the character is D               allocated as needed. When the sequence is extended too/               far, it is copied to a new array.e  C               If your program expects a buffer to be allocated whennE               none was allocated, then the iostream package allocatestD               a default buffer, with a length specified by BUFSIZ asG               defined in stdio.h. The package then issues the following                warning:  L               Warning; a null pointer to streambuf was passed to ios::init()  $         Constructors and Destructors                 strstreambuf()F               Constructs an empty strstreambuf object in dynamic mode.A               This means that space is automatically allocated torE               accommodate characters put into the strstreambuf object D               (using the new and delete operators). Because this mayD               require copying the original characters, programs thatC               have many characters to insert should use setbuf() tosH               inform the strstreambuf object about the needed allocationF               of space, or to use one of the constructors that follow.  !               strstreambuf(int n)tF               Constructs an empty strstreambuf object in dynamic mode.B               The initial allocation of space is at least n bytes.  :               strstreambuf(char *ptr, int n, char *pstart)C               strstreambuf(unsigned char *ptr, int n, unsigned charf               *pstart)H               Constructs a strstreambuf object to use the bytes startingC               at ptr. The strstreambuf object is in static mode; it E               does not grow dynamically. If n is positive, then the nmH               bytes starting at ptr are used as the strstreambuf object.E               If n is 0, ptr is presumed to point to the beginning ofdC               a null-terminated string and the bytes of that stringfG               (not including the terminating null character) constitutecA               the strstreambuf object. If n is negative, then theiG               strstreambuf object is presumed to continue indefinitely.o           4-102 iostream Package           H                                                       strstreambuf class    D               The get pointer is initialized to ptr. The put pointerG               is initialized to pstart. If pstart is not null, then the(F               initial sequence for fetching (the get area) consists ofG               the bytes between ptr and pstart. If pstart is null, then F               storing operations are treated as errors and the initial4               get area consists of the entire array.  D               strstreambuf(void *(*a)(long n), void (*f)(void *ptr))  F               Constructs an empty strstreambuf object in dynamic mode.F               a is used as the allocator function in dynamic mode. TheC               argument passed to a is a long denoting the number of G               bytes to be allocated. If the a argument is null, the newaG               operator is used. f is used to free (or delete) get, put, G               or reserve areas returned by a. The argument to f becomes,F               a pointer to the array allocated by a. If f is null, the&               delete operator is used.                                                        H                                                   iostream Package 4-103                    strstreambuf class               Member Functions                  void freeze(int n)B               Inhibits (freezes) automatic deletion of the currentE               array if n is nonzero, or permits (unfreezes) automaticeD               deletion if n is 0. Deletion normally occurs when moreG               space is needed, or when the strstreambuf object is beingeG               destroyed. Only space obtained through dynamic allocation F               is free. Storing characters into a strstreambuf that wasE               dynamically allocated and is now frozen causes an erroroF               (the effect is undefined). If you want to resume storingC               characters in such a strstreambuf object you can thawr               (unfreeze) it.  )               virtual int overflow(int c)cH               In classes derived from streambuf, it is called to consumeG               characters. If c is not EOF, overflow(c) also must either F               save c or consume it. Although it can be called at otherA               times, this function is usually called when the putnF               area is full and an attempt is being made to store a newG               character. The normal action is to consume the characters E               between pbase() and pptr(), call setp()  to establish a D               new put area, and (if c != EOF) store c using sputc().A               overflow(c) should return EOF to indicate an error; 9               otherwise, it should return something else.n  9               virtual streambuf *setbuf(char *ptr, int n)eB               Causes the strstreambuf object to remember n (if ptrE               is 0); this ensures that at least n bytes are allocateda6               during the next dynamic mode allocation.                 char *str()xE               Returns a pointer to the first character in the currentu?               array and freezes the strstreambuf object. If thepB               strstreambuf object was constructed with an explicitE               array, the function returns a pointer to that array. If G               the strstreambuf object is in dynamic allocation mode butiD               nothing has been restored yet, the returned pointer is               null.                    4-104 iostream Package    t      H                                                       strstreambuf class    %               virtual int underflow()sG               In classes derived from streambuf, it is called to supplyaE               characters for fetching; that is, to create a conditioneE               in which the get area is not empty. If this function is C               called when characters are in the get area, it should C               return the first character. If the get area is empty,nF               it should create a nonempty get area and return the nextE               character (which it should also leave in the get area).sE               If no more characters are available, underflow() should 5               return EOF and leave an empty get area.u                                                                      H                                                   iostream Package 4-105 t  o                  H                                                                        5H         ________________________________________________________________  H                                                         Messages Package      F               The Messages package provides a way to retrieve messagesD               stored in a catalog or file that is separate from yourD               program. It consists of a single class, Messages, that.               retrieves the text of a message.  E               Processing a message file on an OpenVMS system requiresyB               a message set number and a message number. A messageC               set number is an OpenVMS message identification code,tB               including a facility code (bits 16 through 27) and aC               facility-specific bit (bit 15); all other bits shouldoE               be 0. A message number is an integer from 1 to 8191. ToaG               process the message file, use the OpenVMS Message UtilityeF               (see the OpenVMS Message Utility Manual for details) andG               link the resulting object code into one of the following:i                 o  Your programe  F               o  A shareable image that your program is linked against  F               o  A shareable image that is then specified with the set                   message command                            H                                                     Messages Package 5-1                    Messages class    H         ________________________________________________________________           Messages class  :               Retrieves message text for a message number.           Header Filee  %               #include <messages.hxx>v                  Alternative Header                 None.t           Declaration                  class Messages               {l               public:lD                  Messages(const char *filename_arg, int set_arg = 0,T                       const char *default_file_location_arg = (const char *)(NULL));                  ~Messages();o  M                  const char *text(int msg_arg, const char *fallback_text_arg, (                        int set_arg = 0);               };  $         Constructors and Destructors  H               Messages(const char *filename_arg, int set_arg, const char)               *default_file_location_arg) A               Constructs a Messages object. set_arg specifies theuD               message number to set; a value of 0 specifies that theA               default set be used. filename_arg and default_file_t'               location_arg are ignored.                  ~Messages()a(               Deletes a Messages object.           Member Functionr  F               const char *text(int msg_arg, const char *fallback_text_               arg, int set_arg) F               Returns the text of the message specified by the msg_argD               argument. The fallback_text_arg argument indicates the           5-2 Messages Package t         H                                                           Messages class    H               text to return if the message cannot be found. The set_argE               argument specifies the message set number; a value of 0 E               causes the system to use the set number provided to the                constructor.  D               Depending on the process defaults, the facility, errorG               severity, and message identification code may be appended D               to the beginning of the message (for example, %CXXL-W-F               E_ONEXT, prefixed to Can't delete an object that is on a               list.).            Example   <               The following is a sample message source file:  Y               .TITLE      MESSAGES_EXAMPLE_MSG    Example messages -- VMS message catalog                .IDENT      '1.0' 5               .FACILITY   EXAMPLE, 1 /PREFIX=EXAMPLE_                  .BASE 0mK               .SEVERITY WARNING    ! we just want a 0 in the severity fieldc7               SET <>               ! message set numbera                 .SEVERITY ERRORt>               EXAMPLE_ERROR <This is an example error message>                 .END  E               Entering the following OpenVMS Message Utility commands @               set the appropriate options and compile this file:  ,               $ set message/nofac/nosev/noid0               $ message/lis MESSAGES_EXAMPLE_MSG  G               The following program retrieves the sample error message:.  %               #include <iostream.hxx> %               #include <messages.hxx>   C               const char *message_file_name = (const char *)(NULL); G               const char *message_file_location = (const char *)(NULL);_+               #pragma __extern_model __save 2               #pragma __extern_model __globalvalue%               extern int EXAMPLE_SET;b.               #pragma __extern_model __restore4               int message_set_example = EXAMPLE_SET;  H                                                     Messages Package 5-3                    Messages class    I               Messages m_example (message_file_name, message_set_example, )                   message_file_location);                  int main()               {                    cout <<f6                       "text of example message 1: " <<@                       m_example.text(1, "fallback message 1") <<                       "\n";a                     cout << 6                       "text of example message 2: " <<@                       m_example.text(2, "fallback message 2") <<                       "\n";n                     return 0;u               }   B               The following compiler command compiles the program:  (               $ cxx/lis MESSAGES_EXAMPLE  H               Entering the following link and run sequence retrieves theH               text of the error message and displays the second fallback               message:  :               $ link MESSAGES_EXAMPLE,MESSAGES_EXAMPLE_MSG  *               $ run/nodeb messages_exampleI               text of example message 1: This is an example error messagee;               text of example message 2: fallback message 2                                      5-4 Messages Package l                     H                                                                        6H         ________________________________________________________________  H                                                            Mutex Package      D               The Mutex package provides a way to synchronize accessE               to user-defined objects. It consists of a single class, H               Mutex, that manages the creation, locking and unlocking of               Mutex objects.  F               Construction of a Mutex object creates a recursive mutexB               that users can lock and unlock using the appropriate?               member functions or parameterized manipulators. A F               recursive mutex is a mutex that can be locked many timesF               by the same thread without causing the thread to enter aF               deadlock state. To completely unlock this kind of mutex,G               the thread must unlock the mutex the same number of times H               that the thread locked the mutex. For more information see.               the  Guide to DECthreads manual.  F                 ________________________Note  ________________________  A                 User-defined objects are not automatically thread @                 safe. Users must supply synchronization for such;                 objects if they are shared between threads.e  E                 _____________________________________________________r                          H                                                        Mutex Package 6-1                    Mutex class     H         ________________________________________________________________           Mutex classr  F               Provides a means whereby users can synchronize access to#               user-defined objects.            Header File   "               #include <mutex.hxx>                  Alternative Header                  #include <mutex.h>           Declaration                  class Mutexh               {                public: #                            Mutex(); $                            ~Mutex();  "                  void      lock();$                  void      unlock();%                  int       trylock();                };           Description   A               The synchronization process consists of locking andmB               unlocking Mutex objects associated with user-definedC               objects. Digital recommends that users create a Mutex B               object for each user-defined object that needs to beF               synchronized between threads. Users are then responsibleF               for locking and unlocking the Mutex object to coordinate.               access to the associated object.  G               To do the locking and unlocking, you can use the lock andrH               unlock member functions (see Example). Alternatively, if aH               user-defined object is derived from the istream or ostreamD               classes, you can use the lock and unlock parameterizedH               manipulators, where the parameter is the Mutex object (see<               the Global Declarations section in Chapter 4).           6-2 Mutex Package            H                                                              Mutex class      $         Constructors and Destructors                 Mutex()rC               Constructs a Mutex object, in effect creating but nota(               locking a recursive mutex.                 ~Mutex()%               Deletes a Mutex object.c           Member Functions                 void lock()xH               Locks a recursive mutex. If the mutex is locked by anotherC               thread, the current thread is blocked until the mutexi                becomes available.                 void unlock()o(               Unlocks a recursive mutex.                 int trylock() C               Immediately returns to the caller a value of 0 if thetH               mutex is already locked by another thread. Otherwise, this@               function locks the mutex and returns a value of 1.           Example   #               #include <string.hxx>y"               #include <mutex.hxx>                  .                  .                  .               String string1; !               Mutex string1_lock;   "               string1_lock.lock();"               string1 = "Hello, ";(               string1 += "how are you?";               cout << string1;$               string1_lock.unlock();  C               This example synchronizes a sequence of operations ontC               a String object, using the lock() and unlock() member                functions.  H                                                        Mutex Package 6-3 c  s                  H                                                                        7H         ________________________________________________________________  H                                                        Objection Package      F               The Objection package provides a way to implement simpleD               error handling in DEC C++. You can use this package toH               catch run-time errors encountered in using classes, and toD               change or restore actions associated with such errors.                                                              H                                                    Objection Package 7-1 t  t               Global Declaration    H         ________________________________________________________________           Global Declaration  B               This typedef is used by, but is not a member of, the               Objection class.           Header  &               #include <objection.hxx>                  Alternative Header  $               #include <Objection.h>           Declaration,  8               typedef int Objection_action(const char*);           Type                 Objection_actionH               Is the type of an action routine that can be called by the(               function Objection::raise.                                                   7-2 Objection Package  s  a      H                                                          Objection class    H         ________________________________________________________________           Objection classd  B               Provides the capability to handle and report errors.           Header  &               #include <objection.hxx>                  Alternative Header  $               #include <Objection.h>           Declaration                  class Objectione               {e                 public: 0                                     Objection();B                                     Objection(Objection_action *);=                   int               raise(const char * = ""); A                   Objection_action  *appoint(Objection_action *); /                   Objection_action  *appoint();n.                   Objection_action  *ignore();               };           Descriptionl  ?               This class provides ways to handle objections. Ant@               objection is a potential error condition that yourH               program can encounter. The user appoints an error-handlingF               function. An Objection object's raise() function invokesE               the appointed function by passing it a character stringrB               that contains an error message. At any point in yourE               program, you can appoint a new error-handling function,nA               reappoint the original function, or specify that anh#               objection be ignored.             H                                                    Objection Package 7-3    c               Objection classi               Constructors                 Objection() C               Constructs an Objection object with no default actionm               (error handler).  5               Objection(Objection_action *new_action)aB               Constructs an Objection object with a pointer to theC               default error handler. The handler is a function that E               takes one parameter of type const char *msg and returnsa>               an int. See the raise() member function for more               information.           Member Functions  )               Objection_action *appoint() A               Specifies that the handler for the objection is the C               default error handler (if one exists) and returns theaF               previous action associated with the specified objection.:               Specifies that the objection not be ignored.  >               Objection_action *appoint(Objection_action *new_               action) G               Specifies a new handler for the objection and returns the F               previous action associated with the specified objection.:               Specifies that the objection not be ignored.  (               Objection_action *ignore()G               Specifies that the objection be ignored (no error handleraC               is invoked if the objection is raised). This functionrG               returns the previous action associated with the specifiedc               objection.  -               int raise(const char *msg = "")tC               Raises a specified objection, passing a string (error A               message) to an error handler (if one exists). If no H               handler exists, or if the handler returns a 0, the defaultE               handler is called. The raise function returns the value 5               returned by the last handler it called.t                   7-4 Objection Packagec a  r      H                                                          Objection class    E               If no default handler exists, then the function returnsnB               0. A 0 is also returned if the objection is ignored.E               Generally, the return of a nonzero value means that therC               error handling succeeded, and the return of a 0 value .               means the error handling failed.                                                                                H                                                    Objection Package 7-5 _  _               Objection class_      =                     The following example changes the default )                     error handler for thee9                     stack(int)::overflow_error objection:   !               #include <stdlib.h>t#               #include <vector.hxx> &               #include <objection.hxx>                  vectordeclare(int)               stackdeclare(int)   "               vectorimplement(int)!               stackimplement(int)                  stack(int) s(10);m  +               int error(const char *errmsg)b               {mJ                   cerr << "ERROR TRAPPED: " << errmsg << " -- ABORTING\n";                   cerr.flush();                    abort();                   return 0;                }0                 void main()g               {.0                   Objection_action *save_action;J                   save_action = stack(int)::overflow_error.appoint(error);M                   for(int i=0; i<100; i++)  //push too many things onto stack                         s.push(i);B                   stack(int)::overflow_error.appoint(save_action);               }a  =                     When this example executes, the followinge'                     message prints out:c  2         ERROR TRAPPED: Stack underflow -- ABORTINGX         %SYSTEM-F-OPCCUS, opcode reserved to customer fault at PC=00010BE5, PSL=03C000007         %TRACE-F-TRACEBACK, symbolic stack dump follows_T         module name     routine name                     line       rel PC    abs PC  U                                                                    0000012D  00010BE5vU                                                                    0000000E  00009346 U         OBJECTION_EXAMP error                            5984      00000045  00003D29 U         CXXL_OBJECTION  Objection::raise                  779      00000026  00008F5A*U         OBJECTION_EXAMP main                             5993      0000005B  00003D87 U                                                                    00000072  0002DB5E            7-6 Objection Package            H                                                          Objection class    F                 ________________________Note  ________________________  C                 The message printed on your system differs somewhate%                 from that shown here.   E                 _____________________________________________________f                                                                              H                                                    Objection Package 7-7    b                  H                                                                        8H         ________________________________________________________________  H                                                        Stopwatch Package      F               The Stopwatch package provides ways to measure intervals@               of program execution time. The package consists of@               a single class, Stopwatch. Typically, you use thisB               class during the performance-tuning phase of program               development.                                                            H                                                    Stopwatch Package 8-1 t  f               Stopwatch classe    H         ________________________________________________________________           Stopwatch classf  E               Provides the means to measure intervals of time betweeno'               specified program events.            Header  &               #include <stopwatch.hxx>                  Alternative Header  $               #include <Stopwatch.h>           DeclarationM                 class Stopwatch                {                public:T/                                    Stopwatch();   +                  void              start();w*                  void              stop();+                  void              reset();n2                  int               status() const;2                  double            system() const;0                  double            user() const;0                  double            real() const;  0                  static double     resolution();               };           Description/  F               Objects of this class measure program execution time andD               return the result in floating-point seconds. The classG               includes the start, stop, and reset functions familiar tos.               users of a mechanical stopwatch.  H               You can time the entire program or select certain portionsC               of the program to time; for example, a specified loopsE               or program module. You can create a different Stopwatch D               object for each independent program activity, and nameC               each according to the activity you intend to measure.            8-2 Stopwatch Package            H                                                          Stopwatch class               Constructori                 Stopwatch() F               Constructs a Stopwatch object with both time and running&               status initialized to 0.           Member Functions  !               double real() const A               Returns real time (clock time) in double-precision, F               floating-point seconds. You can call this function while'               the stopwatch is running.                  void reset()H               Resets the current time measurement to 0 without affectingF               the value of status(). If status() is initially nonzero,G               time measurement continues uninterrupted after resetting.E  !               double resolution()fH               Returns the (system dependent) resolution of measured time:               in double-precision, floating-point seconds.                 void start()F               Begins measuring program execution time when status() isG               initially 0 (status() becomes nonzero as a consequence oflF               the call). If status()is initially nonzero, the call has               no effect.                  int status() constC               Indicates whether the stopwatch is running (returns a @               value of 1) or not running (returns a value of 0).                 void stop()_G               Halts measurement of program execution time when status()MG               is initially nonzero (status() becomes 0 as a consequencecF               of the call). If status()is initially 0, the call has no               effect.   #               double system() const H               Returns the system CPU time in double-precision, floating-A               point seconds. You can call this function while the #               stopwatch is running.g    H                                                    Stopwatch Package 8-3                    Stopwatch classa    !               double user() const F               Returns the user CPU time in double-precision, floating-A               point seconds. You can call this function while the,#               stopwatch is running.k             System Environment  E               On OpenVMS systems, user time returns the total accumu-nF               lated CPU time, and system time returns 0. Resolution is               1/100 second.            Example_                 Stopwatch w ;f               w.start() ;t               // . . .<               // some computation you want to time goes here               // . . .               w.stop() ;>               cout << "elapsed time was " << w.user() << "\n";  E               Displays the number of seconds the computation takes to :               run. The result is a double-precision value.                                                   8-4 Stopwatch Package_ _  _                  H                                                                        9H         ________________________________________________________________  H                                                           String Package      E               The String package consists of the single class String. B               This class provides ways to assign, concatenate, andA               compare character strings. This class also provides;G               methods for substring creation and for vector access to a(               character string.y                                                            H                                                       String Package 9-1 n  k               String class    H         ________________________________________________________________           String class  E               Provides the capabilities for manipulating sequences ofc               characters.s           Header  #               #include <string.hxx>n                  Alternative Header                 None.s           Declarationc                 class String               {kI                   friend ostream  &operator<<(ostream &, const String &);EC                   friend istream  &operator>>(istream &, String &);rM                   friend int      operator==(const String &, const String &);nK                   friend int      operator==(const String &, const char *);eK                   friend int      operator==(const char *, const String &);4M                   friend int      operator!=(const String &, const String &); K                   friend int      operator!=(const String &, const char *);rK                   friend int      operator!=(const char *, const String &); L                   friend int      operator<(const String &, const String &);J                   friend int      operator<(const String &, const char *);J                   friend int      operator<(const char *, const String &);L                   friend int      operator>(const String &, const String &);J                   friend int      operator>(const String &, const char *);J                   friend int      operator>(const char *, const String &);M                   friend int      operator<=(const String &, const String &); K                   friend int      operator<=(const String &, const char *);sK                   friend int      operator<=(const char *, const String &); M                   friend int      operator>=(const String &, const String &);.K                   friend int      operator>=(const String &, const char *); K                   friend int      operator>=(const char *, const String &);gL                   friend String   operator+(const String &, const String &);J                   friend String   operator+(const String &, const char *);J                   friend String   operator+(const char *, const String &);               9-2 String Package u  g      H                                                             String class                   public: +                                   String(); 9                                   String(const String &); 7                                   String(const char *);_7                                   String(const char &); ,                                   ~String();  =                   String          &operator=(const String &);y;                   String          &operator=(const char *);.;                                   operator char * () const;rA                                   operator const char * () const;e>                   String          &operator+=(const String &);<                   String          &operator+=(const char *);=                   String          operator()(int, int) const; 1                   unsigned int    length() const;_0                   String          upper() const;0                   String          lower() const;>                   int             match(const String &) const;>                   int             index(const String &) const;8                   char            operator[](int) const;3                   char            &operator[](int);l               };           Descriptione  F               This class provides the means for manipulating sequencesC               of characters, each of which is of the type char. For E               some applications, the services provided are like those C               provided by the traditional C string library (strcpy, ?               strcmp, and so forth), but are more efficient andaD               convenient in the context of C++. Overloaded operatorsG               provide ways to assign, concatenate, and compare strings.bB               New operators provide simple notations for substring9               creation and vector access into the string.d  B               All comparisons are lexicographic, with the orderingC               dependent on the character set in which the string isl               encoded.  D               An index value of 0 indicates the first character in a               string object.        H                                                       String Package 9-3 t  _               String class      $         Constructors and Destructors                 String()H               Constructs a String object initialized to an empty string.  #               String(const char *s)iH               Constructs a String object and initializes it to the null-0               terminated sequence of characters.  #               String(const char &c)oC               Constructs a String object with a reference to a charc-               datum to initialize the string.i  %               String(const String &x) D               Constructs a String object with a reference to another4               String to initialize the first String.                 ~String()eB               Deletes a String object; no user action is required.           Overloaded Operators  @               String operator + (const char *s, const String &x)H               Concatenates a null-terminated sequence of characters to a               String object.  @               String operator + (const String &x, const char *s)A               Concatenates a String object with a null-terminatedt%               sequence of characters.   B               String operator + (const String &x, const String &y)F               Concatenates a String object with another String object.  0               String &operator = (const char *s)F               Assigns a String object to a null-terminated sequence of               characters.   2               String &operator = (const String &x)?               Assigns a String object to another String object.j  =               int operator < (const char *s, const String &x)sG               Tests if a null-terminated sequence of characters is lesscF               than a String object; if so, it returns 1. Otherwise, it               returns 0.           9-4 String Package c  n      H                                                             String class    =               int operator < (const String &x, const char *s)wE               Tests if a String object is less than a null-terminatednH               sequence of characters; if so, it returns 1. Otherwise, it               returns 0.  ?               int operator < (const String &x, const String &y) F               Compares two String objects to determine if the first isF               less than the second; if so, it returns 1. Otherwise, it               returns 0.  =               int operator > (const char *s, const String &x)sB               Tests if a null-terminated sequence of characters is@               greater than a String object; if so, it returns 1.&               Otherwise, it returns 0.  =               int operator > (const String &x, const char *s) H               Tests if a String object is greater than a null-terminatedH               sequence of characters; if so, it returns 1. Otherwise, it               returns 0.  ?               int operator > (const String &x, const String &y)nF               Compares two String objects to determine if the first isF               greater than the second; if so, it returns 1. Otherwise,               it returns 0.o  3               String &operator += (const char *st2) H               Concatenates a null-terminated sequence of characters to a               String object.  5               String &operator += (const String &st2) D               Concatenates a String object to another String object.  @               ostream &operator << (ostream &s, const String &x)F               Inserts the sequence of characters represented by x into               the stream s.j  :               istream &operator >> (istream &s, String &x)E               Extracts characters from s using the istream extraction B               operator, then stores characters in x, replacing theC               current contents of x and dynamically allocating x as                necessary.        H                                                       String Package 9-5                    String class    >               int operator == (const char *s, const String &x)H               Tests if a null-terminated sequence of characters is equalD               to a String object; if so, it returns 1. Otherwise, it               returns 0.  >               int operator == (const String &x, const char *s)D               Tests if a String object is equal to a null-terminatedH               sequence of characters; if so, it returns 1. Otherwise, it               returns 0.  @               int operator == (const String &x, const String &y)G               Compares two String objects to determine equality. If onesH               is equal to the other, it returns 1; otherwise, it returns               0.  >               int operator != (const char *s, const String &x)F               Tests if a null-terminated sequence of characters is notG               equal to a String object; if so, it returns 1. Otherwise,                it returns 0.   >               int operator != (const String &x, const char *s)H               Tests if a String object is not equal to a null-terminatedH               sequence of characters; if so, it returns 1. Otherwise, it               returns 0.  @               int operator != (const String &x, const String &y)E               Compares two String objects to determine inequality. If G               they are not equal, the function returns 1; otherwise, it                returns 0.  >               int operator <= (const char *s, const String &x)G               Tests if a null-terminated sequence of characters is less D               than or equal to a String object; if so, it returns 1.&               Otherwise, it returns 0.  >               int operator <= (const String &x, const char *s)G               Tests if a String object is less than or equal to a null-_E               terminated sequence of characters; if so, it returns 1. &               Otherwise, it returns 0.  @               int operator <= (const String &x, const String &y)F               Compares two String objects to determine if the first isD               less than or equal to the second; if so, it returns 1.&               Otherwise, it returns 0.           9-6 String Package t  P      H                                                             String class    >               int operator >= (const char *s, const String &x)H               Tests if a null-terminated sequence of characters is equalF               to or greater than a String object; if so, it returns 1.&               Otherwise, it returns 0.  >               int operator >= (const String &x, const char *s)D               Tests if a String object is equal to or greater than aG               null-terminated sequence of characters; if so, it returns_)               1. Otherwise, it returns 0.l  @               int operator >= (const String &x, const String &y)F               Compares two String objects to determine if the first isG               equal to or greater than the second; if so, it returns 1.d&               Otherwise, it returns 0.  =               String operator () (int index, int count) const G               Creates a new String object defined as a substring of theSF               current String, with index as the starting character and3               count as the length of the substring.i  3               char operator [] (int position) const H               Returns the character at the requested position within theG               string. If the position is past the end of the string, it E               returns 0. If the position is negative, the results areo               undefined.  .               char &operator [] (int position)C               Returns a reference to the character at the requestedeG               position within the string. This reference is potentiallysE               invalid after any subsequent call to a non-const membermF               function for the object. If the position is past the endG               of the string or if the position is negative, the resultsl               are undefined.           Other Member Functions  .               int index(const String &x) constD               Returns the index value of the first position where anG               element of a String object coincides with the value of x.   )               unsigned int length() const C               Returns the length (number of characters) in a Strings               object.     H                                                       String Package 9-7 n  g               String class    "               String lower() constC               Returns a new String object constructed from a StringmH               except that every character is lowercase regardless of its               original case.  .               int match(const String &x) constG               Compares two strings and returns the first index positionm@               at which they differ; it returns -1 if the stringsF               match completely. The String argument can be a character               pointer.  "               String upper() constH               Returns a new String constructed from a String except thatE               every character is uppercase regardless of its original                case.s           Examples  4               1. String x ("The Times of John Doe");+                 char *y = "Pink Triangles";e  G                 if (x != y) cout << "We have two different strings.\n";i                   x = y;                   cout << x;  D                  The first line of this example provides a characterB                  string to the constructor for initialization. TheC                  overloaded operators (!=, <<, and =) accept either D                  two String objects or a String and a null-terminateE                  sequence of characters. The last line prints out the ,                  following character string:                   Pink Triangles  4               2. String x ("The Times of John Doe");  <                 String a (x(18,3));    // Substring is "Doe"=                 String b (x);          // b contains all of xh  E                  In this example, the creation of object a provides a G                  substring of object x to the constructor for object a. H                  The substring begins at position 18 and has a length ofE                  3 characters. The next line creates the object b ando?                  initializes it to contain the same value as x.            9-8 String Package    y      H                                                             String class      $               3. String x ("World");                 String y;s                   y = "Hello";&                 y += ", " + x + ".\n";                   cout << y;  G                  This example shows string concatenation. The last lineo2                  prints out the following message:                   Hello, World.                                                                 H                                                       String Package 9-9                       H                                                                       10H         ________________________________________________________________  H                                                             task Package      G               The task package provides coroutine support. A coroutine, D               or task, is a subroutine that can suspend execution toG               allow other tasks to run. Static data is shared among allsH               tasks; automatic and register data is allocated separatelyF               for each task. Only one task can execute at a time, even)               on a multiprocessor system.(  H               Programming with tasks can be particularly appropriate forF               simulations or other applications that can be reasonably;               represented as sets of concurrent activities.   G               This package includes the object and randint classes, the F               subclasses derived from these classes, and the histogram               class.  E               Figure 10-1 shows the inheritance structure of the task<               package.  B               Figure 10-1 Inheritance Diagram for the task Package          &               Also note the following:  H               o  The sched and task classes are intended for use only as                  base classes.  C               o  The task package makes use of the threads library.           H                                                        task Package 10-1 t  =            G               o  The task package is not thread safe. You cannot createc=                  tasks simultaneously from different threads.r                                                                                               10-2 task Package  r         H                                                      Global Declarations    H         ________________________________________________________________           Global Declarationsp  D               The typedef, enum, and extern declarations are used byF               one or more classes in the task package but they are not.               members of any particular class.           Header  !               #include <task.hxx>i                  Alternative Header                 #include <task.h>            Declaration;  /               typedef int(*PFIO)(int, object*);t#               typedef void(*PFV)();                  enum               {n#                   VERBOSE = 1 << 0, !                   CHAIN = 1 << 1,=!                   STACK = 1 << 2,                };                 enum qmodetype               {r                   EMODE,                   WMODE,                   ZMODEc               };                      H                                                        task Package 10-3 n                  Global Declarationsi                   enum               {                    E_OLINK = 1,                   E_ONEXT = 2,!                   E_GETEMPTY = 3,                    E_PUTOBJ = 4,-                    E_PUTFULL = 5,                    E_BACKOBJ = 6,!                   E_BACKFULL = 7,s!                   E_SETCLOCK = 8, "                   E_CLOCKIDLE = 9,!                   E_RESTERM = 10,                     E_RESRUN = 11,!                   E_NEGTIME = 12,c                    E_RESOBJ = 13,                   E_HISTO = 14,                    E_STACK = 15,                    E_STORE = 16, "                   E_TASKMODE = 17,!                   E_TASKDEL = 18,i!                   E_TASKPRE = 19,)"                   E_TIMERDEL = 20,!                   E_SCHTIME = 21,                     E_SCHOBJ = 22,                   E_QDEL = 23,                    E_RESULT = 24,                   E_WAIT = 25,                   E_FUNCS = 26,a                    E_FRAMES = 27,!                   E_REGMASK = 28,t$                   E_FUDGE_SIZE = 29,"                   E_NO_HNDLR = 30,                    E_BADSIG = 31,#                   E_LOSTHNDLR = 32, (                   E_TASKNAMEOVERRUN = 33               };                 extern int _hwm;                       10-4 task Packagei &  o      H                                                      Global Declarations      
         Typese    +               enum Print Function Argumentsi  G               The verbosity argument to print member functions uses thee               following values:,  H               __________________________________________________________H               Value_____Explanation_____________________________________  /               0         Requests a brief reportc  H               CHAIN     Requests information about tasks on the object'sF                         remember chain, and about other objects on the-                         object's o_next chain   E               STACK     Requests information about the run-time stack   B               VERBOSE   Requests detailed information on the classH               __________object__________________________________________  D               To combine several requests, use the bitwise inclusive(               operator (|). For example:  &               p->print(VERBOSE|CHAIN);                 enum qmodetype  B               The following values are used by the qhead and qtail*               classes for managing queues:  H               __________________________________________________________H               Value_____Explanation_____________________________________  H               EMODE     Generates a run-time error if full on enqueue or(                         empty on dequeue  E               WMODE     Suspends task execution if full on enqueue or (                         empty on dequeue  C               ZMODE     Returns NULL if full on enqueue or empty on H               __________dequeue_________________________________________  "               enum Exception Codes  E               Descriptions of the E_ codes are given in the Exceptionn;               Handling sections of the appropriate classes.s  H                                                        task Package 10-5 c  t               Global Declarations                    PFIOC               Is a pointer to a function returning int, which takes.6               arguments of the types int and object *.                 PFV G               Is a pointer to a function returning void, which takes no                arguments.           Other Data                 extern int _hwmsB               Can be set to a nonzero value before creation of theG               first task to keep track of the maximum stack size ("high H               water mark"). The maximum stack size can be printed by the%               task::print() function.t                                                                     10-6 task Packager    e      H                                                              erand class    H         ________________________________________________________________           erand class   H               Objects of the erand class are generators of exponentially)               distributed random numbers.            Header  !               #include <task.hxx>a                  Alternative Header                 #include <task.h>            Declarationa  )               class erand: public randintn               {e               public:f                   int mean;   #                       erand(int m);                      int draw();g               };           Member Datap                 int mean:               Is the mean of the generated random numbers.           Constructor.                 erand(int m)C               Constructs an erand object with m as the mean for then'               generated random numbers.m           Member Functionr                 int draw()F               Returns the next random integer generated by the object.      H                                                        task Package 10-7                    erand classt               See Also                 randint classn                                                                                           10-8 task Package> o         H                                                          histogram class    H         ________________________________________________________________           histogram class   >               Objects of the histogram class are generators of               histograms.t           Header  !               #include <task.hxx>                   Alternative Header                 #include <task.h>S           Declaration                  class histogramt               {o               public:                    int   l;                   int   r;                    int   binsize;                   int   nbin;o                   int   *h;j                   long  sum;                   long  sqsum;  Q                         histogram(int n_bins = 16, int left = 0, int right = 16); %                         ~histogram();,  (                   void  add(int sample);                    void  print();               };           Description   B               Objects of this class generate histograms. Each suchA               object has nbin bins, spanning a range from l to r.t            H                                                        task Package 10-9    c               histogram class                Exception Handling  G               When a run-time error occurs, the following error code ist:               passed to the object::task_error() function:  H               __________________________________________________________H               Value_________Error_Description___________________________  G               E_HISTO       Cannot construct a histogram with less than H               ______________1_bucket_or_the_left_not_less_than_the_right           Member Datat                 int binsize D               Is the size of the range covered by an individual bin.                 int *hH               Is a pointer to a vector of nbin integers. Each element ofF               the vector is the number of samples placed into that bin$               by the add() function.                 int l!>               Is the lower (left) end of the range of samples.                 int nbin*               Is the total number of bins.                 int r @               Is the higher (right) end of the range of samples.                 long sqsumF               Is the sum of the squares of the integers added to a bin$               by the add() function.                 long sumD               Is the sum of the integers added to a bin by the add()               function.c  $         Constructors and Destructors  B               histogram(int n_bins = 16, int left = 0, int right =               16)qB               Constructs a histogram object. The arguments are allA               optional: n_bins specifies the number of bins, left            10-10 task Package t  f      H                                                          histogram class    C               specifies the initial left end of the range and righte>               specifies the initial right end of the range. AtH               instantiation, the member data are initialized as follows:  3                  The count in each bin is set to 0.o'                  The value of l is leftt(                  the value of r is right&                  nbin is set to n_bins3                  The values of sqsum and sum are 0.c                 ~histogram())               Deletes a histogram object.            Member Functions  "               void add(int sample)C               Adds one to the bin specified by sample. If sample iseF               outside the range of l to r, the range expands by eitherA               decreasing l or increasing r; however, nbin remainsaE               constant. Thus, the range covered by one bin doubles ifa*               the total histogram doubles.                 void print()D               Prints on cout the number of entries for each nonempty               bin.                                        H                                                       task Package 10-11 ;                  Interrupt_handler classw    H         ________________________________________________________________           Interrupt_handler class   C               Interrupt handlers let tasks wait for external eventsiD               (system signals), and allow the declaration of handler)               functions for these events.            Header  !               #include <task.hxx>                   Alternative Header                 #include <task.h>            Declarationo  4               class Interrupt_handler: public object               {i               public:e:                                    Interrupt_handler(int);8                                    ~Interrupt_handler();  N                   virtual void     print(int verbosity, int internal_use = 0);-                   virtual int      pending();n,                   virtual objtype  o_type();                 private:+                   virtual void interrupt();t               };           Descriptioni  A               Interrupt handlers allow tasks to wait for signals..D               You can use classes derived from the Interrupt_handlerB               class to overload the interrupt() function. When theF               signal is raised, the task package immediately calls theG               interrupt() function. The task package then schedules its H               own internal interrupt alerter task for execution. ControlD               returns to the task (if any) that was running when theG               signal was raised. When control returns to the scheduler, D               the interrupt alerter runs and schedules for executionF               those tasks that were waiting for the interrupt handler.           10-12 task Package           H                                                  Interrupt_handler class    B               If the run chain (see the sched class) is empty, theC               scheduler does not cause the program to exit if thereaG               are any interrupt handlers that have been created but notn               yet destroyed.  G               If an interrupt() function is not needed, you can use theeD               Interrupt_handler class without deriving another class               from it.  A               For more information on signals, see the C Run-Timee'               Library Reference Manual.            Exception Handling  F               When a run-time error occurs, the appropriate error codeE               from the following table is passed to the object::task_e               error() function:d  H               __________________________________________________________H               Value_________Error_Description___________________________  H               E_NO_HNDLR    Cannot handle a signal for which there is no#                             handler.  B               E_BADSIG      Cannot handle a signal with an invalid)                             signal number   C               E_LOSTHNDLR   Cannot delete an Interrupt_handler that E                             is not on the stack of them for the given(H               ______________signal______________________________________  $         Constructors and Destructors  4               Interrupt_handler(int signal_to_catch)H               Constructs a new Interrupt_handler object that waits for a               specified signal.3  "               ~Interrupt_handler()2               Deletes an Interrupt_handler object.           Member Functions  &               virtual void interrupt()G               Does nothing but lets classes derived from the Interrupt_aF               handler class overload this function to specify actions.A               Because it is private, you cannot call it directly.   H                                                       task Package 10-13 i  c               Interrupt_handler class     &               virtual objtype o_type())               Returns object::INTHANDLER.   #               virtual int pending() E               Returns 0 on the first call after the signal is raised;g4               otherwise, it returns a nonzero value.  B               virtual void print(int verbosity, int internal_use =               0)A               Prints information about the interrupt handler. The @               verbosity argument specifies the information to beH               printed. For more information, see the enum Print FunctionA               Arguments section under Global Declarations for the C               task package. Do not supply a value for the internal_                use parameter.           System Environment  ?               The thread system exception handling uses OpenVMSeE               conditions and does not interact directly with signals.            Examplei             extern "C" {         #include <stdlib.h> 	         }i         #include <signal.h>t         #include <task.hxx>          #include <iostream.hxx>r  :         class floating_exception: public Interrupt_handler	         {n%             virtual void interrupt();a         public: ?             floating_exception(): Interrupt_handler(SIGFPE) {}; 
         };  ,         void floating_exception::interrupt()	         { 8             cout << "In floating_exception::interrupt --*             Floating exception caught!\n";             cout.flush();w	         }            10-14 task Package l  e      H                                                  Interrupt_handler class             int main()	         {e.             floating_exception sigfpe_handler;             raise(SIGFPE);              return EXIT_SUCCESS;	         }   <               This example prints out the following message:  L               In floating_exception::interrupt -- Floating exception caught!                                                                      H                                                       task Package 10-15                    object class    H         ________________________________________________________________           object class  F               Base class for other classes in the task package and forD               user-defined classes of objects to be placed in queues0               (see the qhead and qtail classes).           Header  !               #include <task.hxx>                   Alternative Header                 #include <task.h>            Declaration                  class object               {                public:)                   enum objtype                   { 5                       OBJECT,         // class object 4                       TIMER,          // class timer3                       TASK,           // class task 4                       QHEAD,          // class qhead4                       QTAIL,          // class qtail@                       INTHANDLER      // class Interrupt_handler                   };  "                   object  *o_next;  )                   static  PFIO error_fct;   #                           object(); $                           ~object();  "                   void    alert();9                   void    forget(task *p_task_to_forget); 1                   void    remember(task *p_task);_5                   int     task_error(int error_code);   +                   virtual objtype o_type(); (                   virtual int pending();J                   virtual void print(int verbosity, int internal_use = 0);           10-16 task Package =  ,      H                                                             object class    V                   static  int task_error(int error_code, object *object_with_problem);,                   static  task *this_task();               };             Description   F               This class is a base class for many other classes withinB               the task package. You also can use it to derive userC               classes to be placed in the task package's queues andME               so forth. All objects derived from the object class can_G               declare the virtual function object::pending(), which theGF               scheduler uses to determine if an object is ready or notE               ready. You can provide each kind of object with its own H               method of determining its state of readiness. Each pendingH               object contains a list (the remember chain) of the waiting               task objects.F           Exception Handling  F               When a run-time error occurs, the appropriate error codeE               from the following table is passed to the object::task__               error() function:   H               __________________________________________________________H               Value_________Error_Description___________________________  E               E_OLINK       Cannot delete an object with a rememberede                              task  E               E_ONEXT       Cannot delete an object that is on a list   H               E_STORE_______Cannot_allocate_more_memory_________________           Member Datai                 PFIO error_fctA               Points to a function to be called by the task_error_@               function. For more information, see the task_error               function.p                 object *o_nextB               Points to the next object in the queue or run chain.    H                                                       task Package 10-17    l               object class      $         Constructors and Destructors                 object()*               Constructs an object object.                 ~object()_'               Deletes an object object.e           Member Functions                 void alert()E               Changes the state of all task objects remembered by thetG               object from IDLE to RUNNING, puts the task objects on the F               scheduler's run chain, and removes the task objects fromH               the remembering object's remember chain. You must call theH               object::alert function for the object when the state of an3               object changes from pending to ready.i  1               void forget(task *p_task_to_forget) D               Removes, from the remembering object object's rememberH               chain, all occurrences of the task, denoted by the p_task_!               to_forget argument.i  &               virtual objtype o_type()%               Returns object::OBJECT.   #               virtual int pending()i-               Always returns a nonzero value.n  ?               In classes derived from object, pending() returns B               the ready status of an object: 0 if an object objectB               is ready and a nonzero value if the object object isA               pending. Classes derived from the object class mustcD               define pending() if waiting is instituted. By default,6               object::pending returns a nonzero value.  B               virtual void print(int verbosity, int internal_use =               0)H               Prints an object on cout. The verbosity argument specifiesF               the information to be printed. For more information, seeD               the enum Print Function Arguments section under GlobalF               Declarations for the task package. Do not supply a value-               for the internal_use parameter.v           10-18 task Package e  a      H                                                             object class    )               void remember(task *p_task) H               Puts a task for a pending object on the remember chain andH               suspends the task, when that task attempts an operation onE               the pending object. Remembered task objects are alertedr?               when an object of the object class becomes ready.   ,               int task_error(int error_code)D               Is obsolete. Calling p->task_error(e) is equivalent to               calling &               object::task_error(e,p).  H               static int task_error(int error_code, object *object_with_               problem)A               Called when a run-time error occurs. The error_code G               argument represents the error number and the object_with_ F               problem argument represents a pointer to the object thatD               called task_error(). The object::task_error() functionH               examines the variable error_fct and calls this function ifE               it is not NULL. If the function returns 0, task_error() C               returns to its caller, which may retry the operation. E               (An infinite loop may result if no appropriate recoveryxF               is made.) If the function returns a nonzero value, task_E               error() calls exit(error_code). Otherwise, task_error() E               gives the error number as an argument to print_error(), D               which prints an error message on cout and task_error()%               calls exit(error_code).j  @               The object_with_problem argument may be NULL if noA               particular object can be associated with the error.r  &               static task *this_task()E               Returns a pointer to the task object currently running.                           H                                                       task Package 10-19 a  h               qhead class     H         ________________________________________________________________           qhead class   G               Abstraction for the head of a list of items arranged in aa5               first-in, first-out singly linked list.            Header  !               #include <task.hxx>o                  Alternative Header                 #include <task.h>            Declaration_  (               class qhead: public object               {                public:cP                             qhead(qmodetype modetype = WMODE, int size = 10000);%                             ~qhead();   #                   qhead     *cut();n#                   object    *get();b?                   int       putback(object *new_queue_element); &                   int       rdcount();$                   int       rdmax();%                   qmodetype rdmode();t8                   void      setmode(qmodetype modetype);-                   void      setmax(int size); 7                   void      splice(qtail *delete_tail); $                   qtail     *tail();  &                   int       pending();G                   void      print(int verbosity, int internal_use = 0); %                   objtype   o_type();f               };                       10-20 task Package    s      H                                                              qhead class               Description   C               This class provides facilities for taking objects offtE               a queue. A queue is a data structure with an associatedoE               list of objects of the object class, or a class derived=E               from the object class in first-in, first-out order. AllaD               access to a queue is through either the attached qheadF               or attached qtail object. You create a queue by creatingD               either a qhead or a qtail object. The other end of theC               queue is created automatically. You can then obtain a @               pointer to the tail with the qhead::tail function.  B               Objects have definitions for when they are ready andG               pending (not ready). The qhead objects are ready when theeE               queue is not empty and pending when the queue is empty.            Exception Handling  F               When a run-time error occurs, the appropriate error codeE               from the following table is passed to the object::task_r               error() function:a  H               __________________________________________________________H               Value_________Error_Description___________________________  F               E_BACKFULL    Cannot putback an object into a full queue  H               E_BACKOBJ     Cannot putback an object into a queue if the6                             object is on another queue  D               E_GETEMPTY    Cannot get an object from an empty queue  G               E_QDEL        Cannot delete a queue that has an object in %                             the queue   H               E_STORE_______Cannot_allocate_more_memory_________________  $         Constructors and Destructors  A               qhead(qmodetype modetype = WMODE, int size = 10000) >               Constructs a qhead object. The modetype argumentG               determines what happens when an object of the qhead class B               is pending. The choices are WMODE (wait mode), EMODEC               (error mode), or ZMODE (0 mode); the default is WMODEvE               (see the get() function for more information). The size G               argument sets the maximum length of the queue attached to 4               a qhead object; the default is 10,000.  H                                                       task Package 10-21 e  ;               qhead classa    F               The maximum size of the queue does not affect the amountF               of memory occupied by the queue when the queue is empty.                 ~qhead()%               Deletes a qhead object.u                                                                                         10-22 task Package g  s      H                                                              qhead class               Member Functions                 qhead *cut()G               Splits a queue into two queues. One queue has a new qhead H               object, which the return value points to, and the originalE               qtail object; it contains the objects from the original B               queue. The other queue has the original qhead objectF               and a new qtail object; this queue is empty. You can useE               this function to insert a filter into an existing queuenG               without changing the queue's appearance to functions that H               access the ends of the queue, and without halting the flow+               through the queue of objects.                  object *get()nF               Returns a pointer to the object at the head of the queueE               when the queue is not empty. The object is removed fromdG               the queue. If the queue is empty, behavior depends on the F               mode of the qhead object. In WMODE, a task that executesF               qhead::get() on an empty queue suspends until that queueB               is not empty. In EMODE, executing qhead::get() on anF               empty queue causes a run-time error. In WMODE, executingE               qhead::get() on an empty queue returns the NULL pointer 0               instead of a pointer to an object.  &               virtual objtype o_type()$               Returns object::QHEAD.                 int pending()_F               Specifies that get operations on a queue must wait untilA               an object is put in the queue. It returns a nonzeroHE               value if the queue attached to a qhead object is empty; &               otherwise, it returns 0.  >               void print (int verbosity, int internal_use = 0)C               Prints a qhead object on cout. The verbosity argumentt?               specifies the information to be printed. For moreoH               information, see the enum Print Function Arguments sectionD               under Global Declarations for the task package. Do not<               supply a value for the internal_use parameter.          H                                                       task Package 10-23    c               qhead class     4               int putback(object *new_queue_element)G               Inserts at the head of the queue the object that the new_oH               queue_element argument points to, and returns a value of 1G               on success. This lets the qhead object operate as a stackcG               (hence, the name putback). Space must be available in theeE               queue for it to succeed. Calling qhead::putback() for acH               full queue causes a run-time error in both EMODE and WMODE(               and returns NULL in ZMODE.                 int rdcount() @               Returns the current number of objects in the queue)               attached to a qhead object.g                 int rdmax() 6               Returns the maximum length of the queue.                  qmodetype rdmode()F               Returns the current mode of a qhead object, which can be%               EMODE, WMODE, or ZMODE.t  .               void setmode(qmodetype modetype)G               Sets the mode of a qhead object to modetype, which can be %               EMODE, WMODE, or ZMODE.D  #               void setmax(int size)kF               Sets size as the maximum length of the queue attached toD               a qhead object. You can set size to a number less thanD               the current number of objects of the object class, butF               that means you cannot put any more objects of the objectG               class on the queue until the length of the queue has been<.               reduced below the limit you set.  -               void splice(qtail *delete_tail)iE               Forms a single queue by appending a queue attached to a E               qhead object onto the queue referenced in the argument. ?               Typically, this reverses the action of a previousnF               qhead::cut() function. The extra qhead and qtail objectsH               are deleted. Waiting tasks resume execution if merging theE               two creates a nonempty queue (if the task was trying to E               get) or an empty queue (if the task was trying to put).r                   10-24 task Package e         H                                                              qhead class                   qtail *tail() F               Creates a qtail object for the queue attached to a qheadF               object (if none exists) and returns a pointer to the new               qtail object.                                                                                   H                                                       task Package 10-25                    qtail class_    H         ________________________________________________________________           qtail classr  H               Abstraction for the tail of a list of items in a first-in,+               first-out singly linked list.            Header  !               #include <task.hxx>                   Alternative Header                 #include <task.h>            Declaratione  (               class qtail: public object               {e%                   friend class qhead;l                 public:nP                             qtail(qmodetype modetype = WMODE, int size = 10000);%                             ~qtail();   #                   qtail     *cut(); $                   qhead     *head();;                   int       put(object *new_queue_element); &                   int       rdspace();$                   int       rdmax();%                   qmodetype rdmode(); 8                   void      setmode(qmodetype modetype);-                   void      setmax(int size); 7                   void      splice(qhead *delete_head);   &                   int       pending();G                   void      print(int verbosity, int internal_use = 0); %                   objtype   o_type();s               };                     10-26 task Package           H                                                              qtail class               Descriptiont  E               This class provides facilities for putting objects intokE               a queue. A queue is a data structure with an associated E               list of objects of the object class, or a class derivediE               from the object class in first-in, first-out order. All D               access to a queue is through either the attached qheadD               or qtail object. You create a queue by creating eitherF               a qhead or a qtail object. The other end of the queue isE               created automatically. You can then obtain a pointer to 5               the head with the qtail::head function.s  B               Objects have definitions for when they are ready andC               pending (not ready). The qtail objects are ready when G               the queue is not full and pending when the queue is full.t           Exception Handling  F               When a run-time error occurs, the appropriate error codeE               from the following table is passed to the object::task_a               error() function:   H               __________________________________________________________H               Value_________Error_Description___________________________  B               E_PUTFULL     Cannot put an object into a full queue  B               E_PUTOBJ      Cannot put an object into queue if the6                             object is on another queue  G               E_QDEL        Cannot delete a queue that has an object in %                             the queue   H               E_STORE_______Cannot_allocate_more_memory_________________  $         Constructors and Destructors  A               qtail(qmodetype modetype = WMODE, int size = 10000)rH               Constructs a qtail object. The modetype argument specifiesB               the mode (set by the constructor) that controls whatC               happens when an object of the qtail class is pending. D               The choices are WMODE (wait mode), EMODE (error mode),?               or ZMODE (0 mode); WMODE is the default. (See the E               put() function for more information.) The size argumentoE               specifies the maximum length of the queue attached to a.2               qhead object; the default is 10,000.  H                                                       task Package 10-27                    qtail classf    F               The maximum size of the queue does not affect the amountF               of memory occupied by the queue when the queue is empty.                 ~qtail()%               Deletes a qtail object.                                                                                          10-28 task Package o  n      H                                                              qtail class               Member Functions                 qtail *cut()G               Splits a queue into two queues. One queue has a new qtailsH               object (to which the return value points) and the originalE               qhead object; it contains the objects from the original:B               queue. The other queue has the original qtail objectF               and a new qhead object; this queue is empty. You can useF               this function to insert a filter into an existing queue,G               without changing the queue's appearance to functions thatbH               access the ends of the queue, and without halting the flow+               through the queue of objects.a                 qhead *head(),F               Creates a qhead object for the queue attached to a qtailF               object (if none exists) and returns a pointer to the new               qhead object.e  &               virtual objtype o_type()$               Returns object::QTAIL.                 int pending(),F               Specifies that get operations on a queue must wait untilG               an object is put in the queue. It returns a nonzero valuee=               if the queue is empty; otherwise, it returns 0.1  B               virtual void print(int verbosity, int internal_use =               0)C               Prints a qtail object on cout. The verbosity argument ?               specifies the information to be printed. For moredH               information, see the enum Print Function Arguments sectionD               under Global Declarations for the task package. Do not<               supply a value for the internal_use parameter.  0               int put(object *new_queue_element)G               Adds the object denoted by the new_queue_element argument B               to the tail of the queue attached to a qtail object;D               returns a value of 1 on success. If the queue is full,F               the behavior depends on the mode of the qtail object. InG               WMODE, an object of class task that executes qhead::put()aD               on a full queue suspends until that queue is not full.E               Calling qhead::put() for a full queue causes a run-timet7               error in EMODE and returns NULL in ZMODE.   H                                                       task Package 10-29 t                  qtail class                    int rdspace(),G               Returns the number of object objects that can be insertedu4               into the queue before it becomes full.                 int rdmax()o6               Returns the maximum length of the queue.                  qmodetype rdmode()F               Returns the current mode of a qtail object, which can be%               EMODE, WMODE, or ZMODE.s  .               void setmode(qmodetype modetype)G               Sets the mode of a qtail object to modetype, which can beb%               EMODE, WMODE, or ZMODE.o  #               void setmax(int size)rG               Sets size as the maximum length of the queue. You can seteF               size to a number less than the current number of objectsD               of the object class, but that means you cannot put anyE               more objects of the object class on the queue until the_F               length of the queue has been reduced below the limit you               set.  -               void splice(qhead *delete_head) C               Forms a single queue by appending a queue attached tod@               a qtail onto the queue referenced in the argument.?               Typically, this reverses the action of a previoustA               qtail::cut(). The extra qhead and qtail objects are H               deleted. Waiting tasks resume execution if merging the twoH               queues creates a nonempty queue (if the task was trying toE               get) or an empty queue (if the task was trying to put).)                                     10-30 task Package l  n      H                                                            randint class    H         ________________________________________________________________           randint class   B               Objects of the randint class generate uniformly dis-&               tributed random numbers.           Header  !               #include <task.hxx>                   Alternative Header                 #include <task.h>i           Declaration                  class randint)               {                public: .                          randint(long seed=0);                    int    draw();!                   float  fdraw(); )                   void   seed(long seed);a               };           Description   B               Objects of this class generate uniformly distributedA               random numbers. Each random-number generator objectsF               produces a sequence that is independent of other random-'               number generator objects.u           Constructor                   randint(long seed)A               Constructs an object of the randint class. The seediE               argument is used as the seed and is optional. DifferentuE               seeds produce different sequences of generated numbers;e5               not all seeds produce useful sequences.           H                                                       task Package 10-31 r  y               randint classy               Member Functions                 float fdraw()hE               Returns the next random number generated by the object.aG               The number is a floating-point value in the range 0 to 1.e                 int draw()E               Returns the next random number generated by the object. C               The number is an integer value in the range from 0 to H               RAND_MAX, which is defined in the ANSI C header, stdlib.h.  "               void seed(long seed):               Reinitializes the object with the seed seed.           Examplet                   extern "C" {!               #include <stdlib.h>h               } !               #include <task.hxx> %               #include <iostream.hxx>                main()                {                    randint gen;                     int i=0;                     float sum;a)                    for (i=0; i<1000; i++) +                         sum += gen.fdraw(); <                    cout<<"Average is " << sum/1000. << "\n";'                    return EXIT_SUCCESS;.                }  D               This example prints the average of 1000 floating-point               random numbers.g                           10-32 task Package           H                                                              sched class    H         ________________________________________________________________           sched class   B               Responsible for scheduling and for the functionality/               common to task and timer objects.            Header  !               #include <task.hxx>                   Alternative Header                 #include <task.h>a           Declaration   (               class sched: public object               {t               public:e                    enum statetype                   {                        IDLE = 1, "                       RUNNING = 2,$                       TERMINATED = 4                   };                 protected:'                                sched();                  public: +                   static task  *clock_task;q(                   static PFV   exit_fct;  2                   void         cancel(int result);+                   int          dont_wait();i5                   sched        *get_priority_sched(); .                   int          keep_waiting();)                   statetype    rdstate();t(                   long         rdtime();(                   int          result();  )                   int          pending(); J                   virtual void print(int verbosity, int internal_use = 0);7                   virtual void setwho(object *alerter);w  H                                                       task Package 10-33                    sched class     +                   static long  get_clock(); 0                   static sched *get_run_chain();1                   static int   get_exit_status();s4                   static void  set_exit_status(int);.                   static void  setclock(long);               };  &               #ifdef CXXL_DEFINE_CLOCK0               #define clock (sched::get_clock())               #endif8               #define run_chain (sched::get_run_chain())           Descriptiong  F               This class provides facilities for checking on the stateF               of a task, manipulating the simulated clock, canceling a9               task, and checking on the result of a task.   H               You can create instances of classes derived from the schedG               class, but you cannot create instances of the sched class                itself.            Exception Handling  F               When a run-time error occurs, the appropriate error codeE               from the following table is passed to the object::task_                error() function:   H               __________________________________________________________H               Value_________Error_Description___________________________  H               E_CLOCKIDLE   Cannot advance the clock when the clock_task4                             is RUNNING or TERMINATED  B               E_NEGTIME     Cannot delay a negative amount of time  B               E_RESOBJ      Cannot resume a task or timer if it is4                             already on another queue  8               E_RESRUN      Cannot resume a RUNNING task  ;               E_RESTERM     Cannot resume a TERMINATED taski  G               E_SCHOBJ      Cannot use class sched other than as a baseh!                             class   G               E_SCHTIME     Cannot execute something at a time that has *                             already passed           10-34 task Package    u      H                                                              sched class  H               __________________________________________________________H               Value_________Error_Description___________________________  F               E_SETCLOCK    Cannot set the clock after it has advancedH               ______________past_0______________________________________                                                                                  H                                                       task Package 10-35    e               sched classc               Member Data   %               static task *clock_task 5               Points to the task clock if one exists.e  !               static PFV exit_fctq8               Points to the exit function if one exists.           Constructor                  sched()uE               Constructs a sched object initialized to the IDLE statea               and delay 0.           Member Functions  %               void cancel(int result)t>               Puts an object into the TERMINATED state withoutB               suspending the caller (that is, without invoking theB               scheduler); sets the result of the object to result.                 int dont_wait()uF               Returns the number of calls to keep_waiting(), minus theD               number of calls to the dont_wait() function, excludingH               the current call. The return value of this function shouldE               equal the number of objects of the object class waitingeF               for external events before the current dont_wait() call.                 long get_clock()E               Returns the value of the clock in simulated time units.   #               int get_exit_status()eF               Returns the exit status of the task program. When a taskD               program terminates successfully (without calling task_D               error), the program calls exit(i) where i is the valueD               passed by the last caller of sched::set_exit_status().  )               sched *get_priority_sched() G               Returns a pointer to a system task's interrupt_alerter if H               the system gets an awaited signal. If no interrupt occurs,&               this function returns 0.               10-36 task Package o         H                                                              sched class    $               sched *get_run_chain()D               Returns a pointer to the run chain, the linked list ofG               ready objects belonging to classes derived from the schedb-               class (task and timer objects).d                  int keep_waiting()G               Keeps the scheduler from exiting when no tasks exist thatiH               can be run (an external event could enable an IDLE task toC               be run). This function should be called when the user B               program creates an object that waits for an externalE               event. Afterward, when such an object destructs, a call G               should go to the dont_wait() function. The keep_waiting() D               function returns the number of calls (not counting theB               current call) minus the number of calls to the dont_               wait() function.                 int pending()bA               Returns 0 if the object is in the TERMINATED state;)4               otherwise, it returns a nonzero value.  B               virtual void print(int verbosity, int internal_use =               0)C               Prints a sched object on cout. The verbosity argumente?               specifies the information to be printed. For moreqH               information, see the enum Print Function Arguments sectionD               under Global Declarations for the task package. Do not<               supply a value for the internal_use parameter.  !               statetype rdstate() @               Returns the state of the object: RUNNING, IDLE, or               TERMINATED.                  long rdtime().B               Returns the simulated clock time at which to run the               object.p                 int result()A               Returns the result of a sched object (as set by thedB               task::resultis(), task::cancel(), or sched::cancel()A               function). If the object is not yet TERMINATED, thes?               calling task suspends and waits for the object tooD               terminate. A task calling result() for itself causes a               run-time error.r    H                                                       task Package 10-37 c  n               sched class_    +               void setclock(long new_clock)_D               Initializes the simulated clock to a time specified byD               the new_clock argument. You can use this function onceE               before the simulated clock has advanced without causingtF               a run-time error. To advance the clock after the initial5               setting, call the task::delay function.e  7               void set_exit_status(int new_exit_status) C               Sets the exit status of the task program. When a task D               program terminates successfully (without calling task_E               error), the program calls exit(i), where i is the valuecD               passed by the last caller of sched::set_exit_status().  2               virtual void setwho(object *alerter)B               Records which object alerted the object. The alerterD               argument should represent a pointer to the object that9               caused the task package to alert the sched.            Macros  >               The DEC C++ Class Library supplies the followingC               macros for compatibility with older C++ class libraryb               implementations:                 clock E               Calls sched::get_clock(). For this macro to be defined, C               you must define CXXL_DEFINE_CLOCK on the command linetG               when invoking the compiler, or in your source code beforee0               including the task package header.                 run_chaine+               Calls sched::get_run_chain().                                    10-38 task Package k  c      H                                                               task class    H         ________________________________________________________________           task class  1               Serves as the basis for coroutines.            Header  !               #include <task.hxx>                   Alternative Header                 #include <task.h>t           Declaration   &               class task: public sched               {                public:h                   enum modetypeY                   { $                       DEDICATED = 1,                        SHARED = 2                   };               protected:A                                   task(char *name = (char *)NULL,hV                                      modetype mode = DEFAULT_MODE, int stacksize = 0);               public: *                   task            *t_next;*                   char            *t_name;  *                                   ~task();  .                   void            cancel(int);.                   void            delay(long);,                   long            preempt();0                   void            resultis(int);3                   void            setwho(object *);hU                   void            sleep(object *object_waiting_for = (object *)NULL);t1                   void            wait(object *);t9                   int             waitlist(object * ...); 5                   int             waitvec(object **);n4                   object          *who_alerted_me();    H                                                       task Package 10-39 s  i               task class    M                   virtual void    print(int verbosity, int internal_use = 0);e+                   virtual objtype o_type();   7                   static        task *get_task_chain();c               };           Descriptionn  D               This class is used only as a base class; all coroutineD               classes are derived from it. All work for an object ofB               a given coroutine type occurs within the constructor@               for that type. The coroutine class must be exactlyC               one level of derivation from the task class. When thesG               object is created, the constructor takes control and runsrE               until halted by one of the following functions: wait(), =               waitlist(), waitvec(), sleep(),  or resultis().e  C               When a task executes a blocking function on an objectcC               that is ready, the operation succeeds immediately andiG               the task continues running; if the object is pending, the F               task waits. Control then returns to the scheduler, whichE               selects the next task from the ready list or run chain.nF               When a pending object becomes ready, the system puts anyA               task waiting for that object back on the run chain.   ;               A task can be in one of the following states:   1               RUNNING     Running or ready to run   6               IDLE        Waiting for a pending object  H               TERMINATED  Completed; not able to resume running (but you2                           can retrieve the result)           Exception Handling  F               When a run-time error occurs, the appropriate error codeE               from the following table is passed to the object::task_c               error() function:   H               __________________________________________________________H               Value____________Error_Description________________________  ?               E_RESULT         Cannot call result() on thistaskl  2               E_STACK          Cannot extend stack           10-40 task Package           H                                                               task class  H               __________________________________________________________H               Value____________Error_Description________________________  :               E_STORE          Cannot allocate more memory  C               E_TASKDEL        Cannot delete a task that is IDLE or &                                RUNNING  E               E_TASKMODE       Cannot create a task with a mode othern7                                than DEDICATED or SHAREDn  @               E_TASKNAMEOVERRUNInternal error: data overrun when9                                building default task name   D               E_TASKPRE        Cannot preempt a task that is IDLE or)                                TERMINATED)  H               E_WAIT___________Cannot_call_wait()_on_thistask___________           Member Data                  task *t_nextG               Points to the text task on the chain of all task objects;a=               it is equal to NULL if there are no more tasks.e                 char *t_nameC               Points to the null-terminated task name passed to thegD               constructor. If no name was passed to the constructor,D               then the constructor creates a unique name (and t_nameF               points to it). If the constructor created the name, then.               the destructor deletes the name.  $         Constructors and Destructors  F               task(char *name = (char *)NULL, modetype mode = DEFAULT_               MODE,m                int stacksize = 0)H               Constructs a task object. All three arguments are optional@               and have default values. If you supply a characterB               pointer, name is used as the task object's name. TheH               argument mode must be DEDICATED or SHARED (or omitted) butH               only DEDICATED is implemented; thus, the mode argument hasE               no effect. The argument stacksize specifies the minimum D               size of the task object's stack. By default, the stackG               size is the same as the default for the underlying threadd               system.s  H                                                       task Package 10-41    e               task class    F                 ________________________Note  ________________________  B                 With DEDICATED stacks, the addresses of parametersD                 to a constructor derived from the task class change.A                 This change occurs between the time when the base A                 class (task) constructor is called by the derived;A                 class constructor and when the first statement in ?                 the derived class constructor begins executing.   ?                 Constructors for the task class and the classesp>                 derived from the task class cannot be inlined.C                 These classes perform actions that start up a child @                 task (in a new thread) and then resume execution?                 of the parent task. On OpenVMS systems, the DEC_?                 C++ compiler automatically prevents inlining ofeD                 constructors for classes derived from task; that is,C                 functions that (implicitly) call task::task (char *c9                 = 0, modetype = DEFAULTMODE, int = SIZE).   E                 _____________________________________________________s                 ~task() F               Deletes an object of the task class. It deletes the task7               name if the constructor created the name.            Member Functions  %               void cancel(int result)=B               Puts a task object into the TERMINATED state withoutD               suspending the calling task (that is, without invokingF               the scheduler); sets the result of the object to result.  $               void delay(long delay)E               Suspends a task object for the time specified by delay. E               A delayed task is in the RUNNING state. The task object G               resumes at the current time on the system clock, plus the G               time specified by delay. Only calling delay(), or waiting .               for a timer, advances the clock.  $               task *get_task_chain()D               Returns a pointer to the first task on the list of all5               task objects linked by next_t pointers.   &               virtual objtype o_type()#               Returns object::TASK.            10-42 task Package g  c      H                                                               task class                   long preempt()C               Suspends a RUNNING object of the task class making it G               IDLE. Returns the number of time units left in the task'sXD               delay. Calling this function for an IDLE or TERMINATED+               task causes a run-time error.h  B               virtual void print(int verbosity, int internal_use =               0)B               Prints a task object on cout. The verbosity argument?               specifies the information to be printed. For morenH               information, see the enum Print Function Arguments sectionD               under Global Declarations for the task package. Do not<               supply a value for the internal_use parameter.  '               void resultis(int result) G               Sets the return value of a task object to be the value of F               result; it puts the task object in the TERMINATED state.G               To examine the result, call the sched::result() function._D               The constructor for a class derived from task must not5               return by any of the following actions:I  -               o  Executing a return statementk  &               o  Throwing an exception  A               o  Not catching an exception thrown by a subroutinem  C               The end of a constructor for a class derived from theeG               task class and the main function must call the resultis() D               function. A task is pending until its stage changes toE               TERMINATED. For more information, see sched::pending().   *               void setwho(object *alerter)A               Keeps track of which object alerted the object. The G               alerter argument should represent a pointer to the object =               that caused the task package to alert the task.   4               void sleep(object *object_waiting_for)F               Suspends a task object unconditionally (that is, it putsF               the task object in the IDLE state). The argument object_E               waiting_for is optional; if it is pointing to a pendingkG               object, the object remembers the task. When the object is_G               no longer pending, the task is rescheduled. If you do not G               supply an argument, the event that causes the task object ,               to resume remains unspecified.  H                                                       task Package 10-43 c  k               task class    3               void wait(object *object_waiting_for)tD               Suspends a task object (it puts the task object in the@               IDLE state) until that object is ready, if object_A               waiting_for points to an object that is pending. If B               object_waiting_for points to an object that is readyF               (not pending), then task::wait does not suspend the task               object.   @               int waitlist(object *first_object_waiting_for ...)A               Suspends a task object to wait for one of a list of D               objects to become ready. The waitlist() function takesG               a list of object pointers linked by o_next and terminatedtD               by a NULL argument. If any of the arguments point to aG               ready object, then the task object is not suspended. WhentC               one of the objects pointed to in the argument list iseG               ready, waitlist() returns the position in the list of the F               object that caused the return; position numbering starts               at 0.u  =               int waitvec(object **object_waiting_for_vector)WE               Differs from waitlist() only in that waitvec() takes asiC               an argument the address of a vector holding a list oftC               pointers to objects and terminating NULL. When one ofsE               the objects pointed to in the argument vector is ready,eF               waitvec() returns the position in a vector of the objectE               that caused the return; position numbering starts at 0.   &               object *who_alerted_me()F               Returns a pointer to the object whose state change, fromG               pending to ready, caused a task to be put back on the runn/               chain (put in the RUNNING state).a           Example   (               long t = sched::get_clock;               delay(10000);e  E               Delays a task so that it resumes executing at t+10,000.e                       10-44 task Package e  r      H                                                              timer class    H         ________________________________________________________________           timer class   F               A timer delays for a specified amount of simulated time.           Header  !               #include <task.hxx>,                  Alternative Header                 #include <task.h>_           Declaration   '               class timer: public sched                {                public: 4                                   timer(long delay);+                                   ~timer();(  4                   void            reset(long delay);:                   void            setwho(object *alerter);  M                   virtual void    print(int verbosity, int internal_use = 0); +                   virtual objtype o_type();o               };           Description   G               Objects of this class are timers. When a timer is created E               its state is RUNNING, and it is scheduled to change its B               state to TERMINATED after a specified number of timeE               units. When the timer becomes TERMINATED, tasks waitingt7               for it are scheduled to resume execution.e                  H                                                       task Package 10-45                    timer classc               Exception Handling  G               When a run-time error occurs, the following error code ise:               passed to the object::task_error() function:  H               __________________________________________________________H               Value_________Error_Description___________________________  A               E_TIMERDEL    Cannot delete a timer that is IDLE ornH               ______________RUNNING_____________________________________  $         Constructors and Destructors                 timer(long delay) F               Constructs an object of the timer class and schedules it@               for delay time units after the current clock time.                 ~timer()E               Deletes an object of the timer class; the timer's stateo!               must be TERMINATED.            Member Functions  &               virtual objtype o_type()$               Returns object::TIMER.  B               virtual void print(int verbosity, int internal_use =               0)C               Prints a timer object on cout. The verbosity argumentn?               specifies the information to be printed. For morecH               information, see the enum Print Function Arguments sectionD               under Global Declarations for the task package. Do not<               supply a value for the internal_use parameter.  $               void reset(long delay)D               Sets the state of the timer to RUNNING (even if it wasC               TERMINATED) and reschedules it to terminate after the >               specified delay from the current simulated time.  *               void setwho(object *alerter)               Returns NULL.i               10-46 task Package           H                                                              timer class               Exampleo               extern "C" {         #include <stdlib.h>N	         }t         #include <task.hxx>          #include <iostream.hxx>i  $         class DelayTask: public task	         {          public:h$             DelayTask(char *, long);
         };  :         // This task just does a delay, much like a timer.A         DelayTask::DelayTask(char *task_name, long delay_length): "                    task(task_name)	         { :             cout << "at beginning of DelayTask, clock is "/                  << sched::get_clock() << "\n";               delay(delay_length);4             cout << "at end of DelayTask, clock is "/                  << sched::get_clock() << "\n"; "             thistask->resultis(0);	         }t           int main()	         { -             cout << "at beginning of main\n";u  &             cout << "creating task\n";6             DelayTask delay_task1("delay_task1", 100);  '             cout << "creating timer\n"; '             timer *pt1 = new timer(10); *             cout << "waiting for timer\n";              thistask->wait(pt1);>             cout << "clock is " << sched::get_clock() << "\n";        H                                                       task Package 10-47                    timer classt    (             cout << "resetting timer\n";             pt1->reset(1000);d*             cout << "waiting for timer\n";              thistask->wait(pt1);>             cout << "clock is " << sched::get_clock() << "\n";  '             cout << "at end of main\n"; "             thistask->resultis(0);              return EXIT_SUCCESS;	         }e  7               This code generates the following output:   "               at beginning of main               creating task 3               at beginning of DelayTask, clock is 0                creating timer               waiting for timer                clock is 10                resetting timer                waiting for timer-/               at end of DelayTask, clock is 100                clock is 1010n               at end of main                                                   10-48 task Package           H                                                              urand class    H         ________________________________________________________________           urand classe  G               Objects of the urand class generate uniformly distributedyG               random integers within a given range from a low to a highi               value.           Header  !               #include <task.hxx>                   Alternative Header                 #include <task.h>s           Declaration   )               class urand: public randintg               {)                 public:t                   int  low;e                   int  high;  8                        urand(int arg_low, int arg_high);                     int  draw();               };           Data Members                 int lowiA               Is the lower bound of the range of generated randomo               numbers.                 int highA               Is the upper bound of the range of generated random                numbers.            H                                                       task Package 10-49    t               urand class                Constructor   .               urand(int arg_low, int arg_high)G               Constructs an object of the urand class. Generated randomdD               numbers are uniformly distributed from arg_low to arg_               high.            Member Functione                 int draw()F               Returns the next random integer generated by the object.           See Also                 randint classo                                                                   10-50 task Package                       H                                                                       11H         ________________________________________________________________  H                                                           vector Package      C               The vector package provides ways to define vectors or H               stacks of objects of any type by using the macro expansion5               capability of the DEC C++ preprocessor._  *               To declare a generic vector:  D               1. Include the header <vector.hxx> in your program and5                  declare the vector class as follows:n  &                  declare(vector, TYPE)  C                  TYPE may be any valid C++ type name. Make sure youoG                  define the declare macro in every file that referencesE+                  this new vector data type.E  D               2. Expand the implementation of all function bodies as                  follows:   (                  implement(vector, TYPE)  D                  This implement macro must appear once in a program.  @               3. Declare objects of type vector and TYPE and useC                  the index operator to reference these objects. The H                  following is an example of declaration and referencing:  ,                  class MyType {/* . . . */};'                  declare(vector,MyType) )                  implement(vector,MyType)a3                  vector(MyType) vec1(100), vec2(5);                   MyType x,y;                  // . . .n/                  if(vec2[4] == y) vec1[98] = x;e    H                                                      vector Package 11-1                 F               The TYPE parameter must be an identifier. If it is not aD               class name, a fundamental type, or a type name, createB               a name for the type using a typedef declaration. For               example:  "               typedef char *PCHAR;$               declare(vector, PCHAR)&               implement(vector, PCHAR)&               implement(vector, PCHAR)                 void f()               {t+                   vector(PCHAR) ptrvec(10); #                   char *p = "Text";e                      ptrvec[0] = p;                   // ...               }                  Thread Safety   H               The generation of error messages within the vector packageF               is not thread safe; the package relies on static membersA               to handle the current error message and there is no G               synchonization between threads. If this creates a problem H               for your application, Digital recommends that you define aF               single Mutex object to synchronize all use of the vectorF               package. For more information on synchronizing access to2               user-defined objects, see Chapter 6.                                         11-2 vector Package            H                                                        stack(TYPE) class    H         ________________________________________________________________           stack(TYPE) classs  G               Provides a generic (parameterized) data abstraction for a >               fixed-sized stack of objects of some given type.           Header  #               #include <vector.hxx>e                  Alternative Header  !               #include <vector.h>            Compile-Time Parameter  F               TYPE-The type of the objects in the stack. It must be an               identifier.            Declarationn  5               class stack(TYPE): private vector(TYPE)                {                public:ZL                                    stack(TYPE)(int); // objection size_error>                                    stack(TYPE)(stack(TYPE) &);  P                   void             push(TYPE);       // objection overflow_errorQ                   TYPE             pop();            // objection underflow_error N                   TYPE             &top();           // objection no_top_error*                   int              full();+                   int              empty();t*                   int              size();/                   int              size_used();p  2                   static Objection overflow_error;3                   static Objection underflow_error; 0                   static Objection no_top_error;               };          H                                                      vector Package 11-3    t               stack(TYPE) classa               Description   @               This class provides a generic (parameterized) dataD               abstraction for a fixed-sized stack of objects of some               given type.   G               Before a stack object can be declared or implemented, the G               base class, a vector object with the same type parameter, G               must also be declared and implemented. To declare a stack D               object you need to both declare and implement the base/               vector class and the stack class.i           Exception Handling  H               Exceptions are implemented with the Objection package. TheH               initial action function for all objections prints an error0               message on cerr and calls abort().           Constructors  #               stack(TYPE)(int size)tC               Constructs a stack object with room for size elements C               in the stack. If size is less than or equal to 0, then;               objection vector(TYPE)::size_error is raised.e  +               stack(TYPE)(stack(TYPE) &src)iH               Constructs a stack object that takes the initial values ofE               the elements from another stack object of the same type                and size.            Member DataT  F               The following objections are raised for the stack errors               described.  +               static Objection no_top_errort?               Attempted to reference the top of an empty stack.s  -               static Objection overflow_errornA               Attempted to push too many elements onto the stack.t  .               static Objection underflow_error.               Attempted to pop an empty stack.           11-4 vector Package     k      H                                                        stack(TYPE) class               Member Functions                 int empty()EG               Returns TRUE if the stack is empty; otherwise, it returnso               FALSE.                 int full()F               Returns TRUE if the stack is full; otherwise, it returns               FALSE.                 TYPE pop()D               Pops an element off the top of the stack. If the stackG               underflows, the objection stack(TYPE)::underflow_error ist               raised.l  &               void push(TYPE new_elem)G               Pushes an element onto the stack. If the stack overflows,_B               the objection stack(TYPE)::overflow_error is raised.                 int size()B               Returns the maximum number of elements in the stack.                 int size_used() H               Returns the number of elements currently used in a generic               stack.                 TYPE &top() B               Returns a reference to the element on the top of theJ               stack. If the stack is empty, the objection stack(TYPE)::no_"               top_error is raised.           Example(  "               declare(vector, int)$               implement(vector, int)!               declare(stack, int) #               implement(stack, int)i              H                                                      vector Package 11-5                    stack(TYPE) classd                   void f()               {t$                   stack(int) st(20);                   st.push(17);                   // ...               }a  C               This example shows the four steps required to declareiD               and implement the base vector class and to declare and(               implement the stack class.           See Also  /               Objection Package (see Chapter 7)e-               generic Package (see Chapter 3)e                vector(TYPE) class                                                                   11-6 vector Packageh o  i      H                                                       vector(TYPE) class    H         ________________________________________________________________           vector(TYPE) class  H               Provides the (parameterized) data abstraction for a fixed-9               sized vector of objects of some given type.t           Header  #               #include <vector.hxx>                   Alternative Header  !               #include <vector.h>            Compile-Time Parameter  G               TYPE-The type of the objects in the vector. It must be an                identifier.i           Declaration                   class vector(TYPE)               {u               public:j:                                    // objection size_error5                                    vector(TYPE)(int); @                                    vector(TYPE)(vector(TYPE) &);3                                    ~vector(TYPE)();a?                                    // objection copy_size_erroru>                   vector(TYPE)     &operator=(vector(TYPE) &);.                   TYPE             &elem(int);;                                    // objection index_error_4                   TYPE             &operator[](int);*                   int              size();1                   void             set_size(int);.  .                   static Objection size_error;3                   static Objection copy_size_error; /                   static Objection index_error;                };        H                                                      vector Package 11-7                    vector(TYPE) class               Description   F               This class provides the (parameterized) data abstractionE               for a fixed-sized vector of objects of some given type.            Exception Handling  H               Exceptions are implemented with the Objection package. TheH               initial action function for all objections prints an error0               message on cerr and calls abort().  $         Constructors and Destructors  (               vector(TYPE)(int new_size)B               Constructs a vector object with the integer argumentC               representing the number of elements in the vector. If D               the number of elements is less than or equal to 0, the;               objection vector(TYPE)::size_error is raised.a  -               vector(TYPE)(vector(TYPE) &src) E               Constructs a vector object that takes initial values ofuF               the elements from another vector object of the same type               and size.                  ~vector(TYPE)()_&               Deletes a vector object.           Member Data_  G               The following objections are raised for the vector errors                described.  .               static Objection copy_size_errorG               Attempted to assign a vector to another vector that has ac+               different number of elements.   *               static Objection index_errorF               Attempted to reference a vector element with a subscript               out of range.   )               static Objection size_errorfH               Attempted to create a vector with less than one element in               it.n           11-8 vector Package  t         H                                                       vector(TYPE) class               Overloaded Operators  :               vector(TYPE) &operator = (vector(TYPE) &src)E               Assigns a vector to another vector. If the sizes of thebF               vectors are different, the objection vector(TYPE)::copy_#               size_error is raised.   '               TYPE &operator [] (int i)a@               Returns a reference to the ith element in the vec-?               tor. The value of i has a range from 0 to size()-sA               1. If the subscript is out of bounds, the objectionE2               vector(TYPE)::index_error is raised.           Other Member Functions                 TYPE &elem(int i) C               Behaves like operator [] but without bounds checking.i  )               void set_size(int new_size) -               Changes the size of the vector.                  int size();               Returns the number of elements in the vector.            See Also                 Objection Packagek               generic Packagee                                H                                                      vector Package 11-9    g                          E      ________________________________________________________________D  E                                                                 Indexa    @      A                                    cin stream object, 4-1/      ___________________________          Class)@      abs,  2-8                             complex,  2-4 to 2-10E      add,  10-11                           c_exception,  2-11 to 2-13)?      adjustfield,  4-37                    erand,  10-7 to 10-8 A      alert,  10-18                         filebuf,  4-14 to 4-18iA      allocate,  4-91                       fstream,  4-19 to 4-21TD      appoint,  7-4                         histogram,  10-9 to 10-11<      arg,  2-8                             IAPP(TYPE),  4-22B      arg1,  2-8                            ifstream,  4-24 to 4-26A      attach                                IMANIP(TYPE),  4-27 to 2        filebuf class, 4-16                    4-28D        fstream class, 4-20                 Interrupt_handler,  10-126        ifstream class, 4-25                   to 10-15=        ofstream class, 4-65                IOAPP(TYPE),  4-29   B                                            IOMANIP(TYPE),  4-31 to2      B__________________________              4-32  =      bad,  4-39                            ios,  4-33 to 4-45eB      base,  4-91                           iostream,  4-46 to 4-47E      basefield,  4-37                      iostream_withassign,  4-48 5      binsize,  10-10                          to 4-49TA      bitalloc,  4-39                       istream,  4-50 to 4-57nD      blen,  4-91                           istream_withassign,  4-585                                               to 4-59eD      C__________________________           istrstream,  4-60 to 4-61@      callerror macro,  3-4                 Messages,  5-2 to 5-4=      cancel                                Mutex,  6-2 to 6-3 <        sched class, 10-36                  OAPP(TYPE),  4-62B        task class, 10-42                   object,  10-16 to 10-19A      cerr stream object,  4-1              Objection,  7-3 to 7-7nB                                            ofstream,  4-64 to 4-66A                                            OMANIP(TYPE),  4-67 to 2                                               4-68  E                                                               Index-1  e  r            C         Class (cont'd)                      Consumer classes,  4-89 B          ostream,  4-69 to 4-73             copy_size_error,  11-8E          ostream_withassign,  4-74          Coroutine, definition of, 3             to 4-75                            10-1 5          ostrstream,  4-76 to 4-77          cos,  2-8 6          qhead,  10-20 to 10-25             cosh,  2-8D          qtail,  10-26 to 10-30             cout stream object,  4-1/          randint,  10-31 to 10-32           cut A          SAPP(TYPE),  4-78                    qhead class,  10-23 A          sched,  10-33 to 10-38               qtail class,  10-29 G          SMANIP(TYPE),  4-79 to             c_exception class,  2-11 tot3             4-80                               2-13   #          stack(TYPE),  11-3 to 11-6 G          stdiobuf,  4-81 to 4-83            D__________________________ @          stdiostream,  4-84 to 4-86         declare2 macro,  3-4?          Stopwatch,  8-2 to 8-4             declare macro,  3-4jA          streambuf,  4-87 to 4-98           dec manipulator,  4-6 9          String,  9-2 to 9-9                delay,  10-425F          strstream,  4-99 to 4-100          Deriving a user class from7          strstreambuf,  4-101 to               ios, 4-3_=             4-105                           doallocate,  4-91 =          task,  10-39 to 10-44              dont_wait,  10-36P0          timer,  10-45 to 10-48             draw@          urand,  10-49 to 10-50               erand class,  10-7C          vector(TYPE),  11-7 to               randint class,  10-32 A             11-9                              urand class,  10-50c         clear, 4-39 G         clog stream object, 4-1             E__________________________d8         close                               eback,  4-917          filebuf class,  4-16               ebuf,  4-91v8          fstream class,  4-20               egptr,  4-917          ifstream class,  4-25              elem,  11-9 8          ofstream class,  4-65              empty,  11-5B         complex class                       endl manipulator,  4-6B          exception handling,  2-5           ends manipulator,  4-60         complex class, 2-4 to 2-10          enumD         complex package, 2-1 to               Exception codes,  10-5G           2-13                                print function arguments, 5          global declarations,  2-2               10-5r>             to 2-3                            qmodetype,  10-56         complex_error, 2-12                 eof,  4-398         conj, 2-8                           epptr,  4-91             Index-2, c  )            C         erand class, 10-7 to 10-8           Generic macros (cont'd)(9         errorhandler macro, 3-4               name2,  3-5 9         error_fct, 10-17                      name3,  3-5 9         Exception codes, 10-5                 name4,  3-5i?         Exception handling                    set_handler,  3-5 D          complex class,  2-5                generic package,  3-1 to2         exp, 2-8                               3-8G         Extraction manipulators,              global declarations,  3-3 7           4-6 to 4-13                            to 3-8nA         Extraction operator                   macros,  3-3 to 3-5 /          used with cin,  4-2                get   B                                               istream class,  4-54A         F__________________________           qhead class,  10-23   ;         fail, 4-39                          get area,  4-88e:         fd                                  getline,  4-55=          filebuf class,  4-16               get_clock,  10-36rC          streambuf class,  4-92             get_exit_status,  10-36rF         fdraw, 10-32                        get_priority_sched,  10-36A         filebuf class, 4-14 to              get_run_chain,  10-37cB           4-18                              get_task_chain,  10-42?         fill, 4-39                          Global declarationsfF         flags, 4-40                           complex package,  2-2 to4         floatfield, 4-37                         2-3F         flush, 4-72                           generic package,  3-3 to4         flush manipulator, 4-6                   3-8G         forget, 10-18                         iostream package,  4-5 toa5         fp, 4-92                                 4-13eE         freeze, 4-104                         Objection package,  7-2 D         fstream class, 4-19 to                task package,  10-3 to5           4-21                                   10-6i7         full, 11-5                          good,  4-41s7         Functions                           gptr,  4-92           pointers to,  10-5 G                                             H__________________________ 5         G__________________________         h,  10-10s  8         gbump, 4-92                         head,  10-29A         gcount, 4-54                        hex manipulator,  4-6o8         Generic macros, 3-3 to 3-5          high,  10-49E          callerror,  3-4                    histogram class,  10-9 ton4          declare,  3-4                         10-117          declare2,  3-4                     _hwm,  10-6           errorhandler,  3-4           implement,  3-4          implement2,  3-5   H                                                                  Index-3 )               ;                                             io_state,  4-35t7         I__________________________         ipfx,  4-55c7         IAPP(TYPE) class, 4-22              isfx,  4-55 C         Identifiers                         istream class,  4-50 to 3          beginning with cxxl_ or               4-57 E             CXXL_,  1-1                     istream_withassign class,r;         ifstream class, 4-24 to                4-58 to 4-59 F           4-26                              istrstream class,  4-60 to3         ignore                                 4-61 :          istream class,  4-55               is_open,  4-168          Objection class,  7-4              iword,  4-42           imag, 2-8tG         IMANIP(TYPE) class, 4-27            K__________________________e  @           to 4-28                           keep_waiting,  10-37         implement2 macro, 3-5xG         implement macro, 3-4                L__________________________n5         index, 9-7                          l,  10-10r8         index_error, 11-8                   length,  9-76         init, 4-41                          lock,  6-35         Insertion manipulators,             log,  2-8 7           4-6 to 4-13                       low,  10-49s7         Insertion operator                  lower,  9-8r          used with cout,  4-1 -         interrupt, 10-13                    M G         Interrupt_handler class,            ___________________________ 2           10-12 to 10-15                    Macros=         in_avail, 4-92                        callerror,  3-4D;         IOAPP(TYPE) class, 4-29               declare,  3-4 <         IOMANIP(TYPE) class, 4-31             declare2,  3-4@           to 4-32                             errorhandler,  3-4B         IOMANIPdeclare macro, 4-32            generic,  3-3 to 3-5=         ios class, 4-33 to 4-45               implement,  3-4n>          deriving user class from,            implement2,  3-59             4-3                               name2,  3-5 9         iostream class, 4-46 to               name3,  3-5 9           4-47                                name4,  3-5 ?         iostream package, 4-1 to              set_handler,  3-5 >           4-105                             Manipulator macrosA          global declarations,  4-5            IMANIP(TYPE),  4-28 B             to 4-13                           IOMANIP(TYPE),  4-32A         iostream_withassign class,            OMANIP(TYPE),  4-67hA           4-48 to 4-49                        SMANIP(TYPE),  4-79e           Index-4u r  w            0         Manipulators                        openB          dec,  4-6                            filebuf class,  4-16B          endl,  4-6                           fstream class,  4-21C          ends,  4-6                           ifstream class,  4-26nC          extraction,  4-6 to 4-13             ofstream class,  4-66i<          flush,  4-6                        open_mode,  4-356          hex,  4-6                          operator -A          insertion,  4-6 to 4-13              complex class,  2-6t7          oct,  4-6                          operator !=eA          ws,  4-6                             complex class,  2-7i@         match, 9-8                            String class,  9-66         mean, 10-7                          operator *A         Messages class, 5-2 to 5-4            complex class,  2-6 7         Messages package, 5-1 to            operator *=oA           5-4                                 complex class,  2-7 6         Mutex class, 6-2 to 6-3             operator +A         Mutex package, 6-1 to 6-3             complex class,  2-6 @                                               String class,  9-47         N__________________________         operator +=nA         name2 macro, 3-5                      complex class,  2-6 @         name3 macro, 3-5                      String class,  9-56         name4 macro, 3-5                    operator /A         nbin, 10-10                           complex class,  2-6 7         norm, 2-9                           operator /=oA         no_top_error, 11-4                    complex class,  2-7 7                                             operator ()_G         O                                     IMANIP(TYPE) class,  4-22)H         ___________________________           IOMANIP(TYPE) class,  4-29G         OAPP(TYPE) class, 4-62                OMANIP(TYPE) class,  4-62 G         object class, 10-16 to                SMANIP(TYPE) class,  4-78e@           10-19                               String class,  9-77         Objection class, 7-3 to             operator ==eA           7-7                                 complex class,  2-7 @         Objection package, 7-1 to             String class,  9-67           7-7                               operator [] G          global declarations,  7-2            vector(TYPE) class,  11-9v6         Objection_action, 7-2               operator <@         oct manipulator, 4-6                  String class,  9-47         ofstream class, 4-64 to             operator <<bA           4-66                                complex class,  2-7tH         OMANIP(TYPE) class, 4-67              IOMANIP(TYPE) class,  4-32G           to 4-68                             OMANIP(TYPE) class,  4-68 B                                               ostream class,  4-71G                                               SMANIP(TYPE) class,  4-80 @                                               String class,  9-5  H                                                                  Index-5                 ;         operator <=                         o_type (cont'd) A          String class,  9-6                   qhead class,  10-23 A         operator =                            qtail class,  10-29r@          iostream_withassign class            task class,  10-42A             ,  4-49                           timer class,  10-46 "          istream_withassign class,G             4-59                            P__________________________oC          ostream_withassign class,          Package, definition of,n2             4-75                               1-1<          String class,  9-4                 pbackfail,  4-938          vector(TYPE) class,  11-9          pbase,  4-938         operator -=                         pbump,  4-939          complex class,  2-6                pcount,  4-77 7         operator >                          peek,  4-56:3          String class,  9-5                 pendingvF         operator >=                           Interrupt_handler class,6          String class,  9-7                      10-14B         operator >>                           object class,  10-18A          complex class,  2-7                  qhead class,  10-23 A          IMANIP(TYPE) class,  4-28            qtail class,  10-29eA          IOMANIP(TYPE) class,  4-32           sched class,  10-37 7          istream class,  4-52               PFIO,  10-6e6          SMANIP(TYPE) class,  4-80          PFV,  10-6B          String class,  9-5                 Pointers to functions,3         opfx, 4-72                             10-5f7         osfx, 4-73                          polar,  2-9u6         ostream class, 4-69 to              pop,  11-55           4-73                              pow,  2-9s7         ostream_withassign class,           pptr,  4-93v<           4-74 to 4-75                      precision,  4-42E         ostrstream class, 4-76 to           Predefined stream objectsa8           4-77                                cerr,  4-17         out_waiting, 4-92                     cin,  4-1r8         overflow                              clog,  4-18          filebuf class,  4-17                 cout,  4-1;          stdiobuf class,  4-82              preempt,  10-43 1          streambuf class,  4-92             printtE          strstreambuf class,  4-104           histogram class,  10-11iF         overflow_error, 11-4                  Interrupt_handler class,6         o_next, 10-17                            10-14B         o_type                                object class,  10-18A          Interrupt_handler class,             qhead class,  10-23gA             10-14                             qtail class,  10-29nA          object class,  10-18                 sched class,  10-37            Index-6b o  l            2         print (cont'd)                      rdmodeA          task class,  10-43                   qhead class,  10-24 A          timer class,  10-46                  qtail class,  10-30c;         Print function arguments,           rdspace,  10-30_3           10-5                              rdstate_>         Producer classes, 4-89                ios class,  4-42A         push, 11-5                            sched class,  10-37 :         put                                 rdtime,  10-377          ostream class,  4-73               read,  4-56l0          qtail class,  10-29                realA         put area, 4-88                        complex class,  2-9 C         putback                               Stopwatch class,  8-3 <          ostream class,  4-56               remember,  10-19?          qhead class,  10-24                reserve area,  4-88 1         pword, 4-42                         resetaC                                               Stopwatch class,  8-3-A         Q                                     timer class,  10-46 @         ___________________________         resetiosflags,  4-10<         qhead class, 10-20 to               resolution,  8-3:           10-25                             result,  10-37<         qmodetype, 10-5                     resultis,  10-439         qtail class, 10-26 to               retval,  2-12            10-30   G                                             S__________________________ C         R__________________________         SAPP(TYPE) class,  4-78   9         r, 10-10                            sbumpc,  4-93,B         raise, 7-4                          sched class,  10-33 to4         randint class, 10-31 to                10-388           10-32                             seed,  10-328         rdbuf                               seekg,  4-563          fstream class,  4-21               seekoff B          ifstream class,  4-26                filebuf class,  4-17C          ios class,  4-42                     stdiobuf class,  4-82 D          istrstreambuf class,  4-61           streambuf class,  4-938          ofstream class,  4-66              seekp,  4-733          ostrstream class,  4-77            seekpos B          stdiostream class,  4-86             filebuf class,  4-17D          strstream class,  4-100              streambuf class,  4-94;         rdcount, 10-24                      seek_dir,  4-37 7         rdmax                               setb,  4-94 2          qhead class,  10-24                setbufB          qtail class,  10-30                  filebuf class,  4-17B                                               fstream class,  4-21C                                               ifstream class,  4-26   H                                                                  Index-7 n  d            2         setbuf (cont'd)                     spliceA          ofstream class,  4-66                qhead class,  10-24 A          streambuf class,  4-94               qtail class,  10-301<          strstreambuf class,  4-104         sputbackc,  4-968         setclock, 10-38                     sputc,  4-968         setf, 4-37, 4-43                    sputn,  4-965         setfill, 4-10                       sqr,  2-926         setg, 4-95                          sqrt,  2-99         setiosflags, 4-10, 4-37             sqsum,  10-10 G         setmax                              stack(TYPE) class,  11-3 to,3          qhead class,  10-24                   11-6 7          qtail class,  10-30                start,  8-3c8         setmode                             status,  8-3D          qhead class,  10-24                stdiobuf class,  4-81 to3          qtail class,  10-30                   4-83 <         setp, 4-95                          stdiofile,  4-82G         setprecision, 4-11                  stdiostream class,  4-84 to 3         setstate, 4-43                         4-86 6         setw, 4-11                          stop,  8-3D         setwho                              Stopwatch class,  8-2 to2          sched class,  10-38                   8-4F          task class,  10-43                 Stopwatch package,  8-1 to2          timer class,  10-46                   8-49         set_complex_error, 2-2              stossc,  4-963/         set_exit_status, 10-38              str_E         set_handler macro, 3-5                ostrstream class,  4-77 H         set_size, 11-9                        strstreambuf class,  4-104E         sgetc, 4-95                           strstream class,  4-100aE         sgetn, 4-95                         streambuf class,  4-87 to53         sin, 2-9                               4-98 F         sinh, 2-9                           Stream objects, predefined8         sizestack(TYPE) class,                cerr,  4-17           11-5                                cin,  4-118         sizevector(TYPE) class,               clog,  4-18           11-9                                cout,  4-1;         size_error, 11-8                    Stream objects, B         size_used, 11-5                        sychronizing access>         skipwhite, 4-56                       predefined,  4-6A         sleep, 10-43                          user-defined,  4-11)E         SMANIP(TYPE) class, 4-79            String class,  9-2 to 9-9sG           to 4-80                           String package,  9-1 to 9-9          snextc, 4-95               Index-8a ,  -            !         strstreambuf class, 4-101 G           to 4-105                          U__________________________,=         strstream class, 4-99 to            unbuffered,  4-97k5           4-100                             underflow B         sum, 10-10                            filebuf class,  4-18C         sync                                  stdiobuf class,  4-83-D          filebuf class,  4-18                 streambuf class,  4-97H          istream class,  4-56                 strstreambuf class,  4-105B          stdiobuf class,  4-82              underflow_error,  11-48          streambuf class,  4-96             unlock,  6-39         Synchronizing access                unsetf,  4-44 7          to predefined stream               upper,  9-8 B             objects,  4-6                   urand class,  10-49 to4          to user-defined stream                10-506             objects,  4-11                  user,  8-4         sync_with_stdio, 4-43 G         system, 8-3                         V__________________________8  2         T                                   VectorE         ___________________________           how to declare generic, 5         tail, 10-25                              11-1,E         tan, 2-9                            vector(TYPE) class,  11-7 6         tanh, 2-10                             to 11-9D         Task, definition of, 10-1           vector package,  11-1 to3         task class, 10-39 to 10-44             11-9e         task package, 10-1 to -           10-50                             WeG         task_error, 10-19                   ___________________________a8         tellg, 4-57                         wait,  10-44<         tellp, 4-73                         waitlist,  10-44;         text, 5-2                           waitvec,  10-44cB         this_task, 10-19                    who_alerted_me,  10-448         Thread safety, 1-1, 4-3,            width,  4-448           11-2                              write,  4-73@         tie, 4-43                           ws manipulator,  4-6           timer class, 10-45 to-G           10-48                             X__________________________   9         top, 11-5                           xalloc,  4-44          trylock, 6-3        H                                                                  Index-9