______________________________________________________________________

  27   Input/output library                 [lib.input.output]

  ______________________________________________________________________

1 This clause describes components that C++ programs may use to  perform
  input/output operations.

2 The   following  subclauses  describe  components  for  all  iostreams
  (_lib.iostreams_),   base   stream   buffer   and   streams    classes
  (_lib.default.iostreams_),  stream  manipulators (_lib.manipulators_),
  string    streams    (_lib.string.streams_),    and    file    streams
  (_lib.file.streams_).

  27.1  Iostreams                                        [lib.iostreams]

1 Headers:

  --<ios>

  --<iostream>

2 Table 1:

                      Table 1--Header <ios> synopsis

  +--------------------------------------------------------------------+
  |     Type                            Name(s)                        |
  +--------------------------------------------------------------------+
  |Template       basic_ios                                            |
  |class:                                                              |
  +--------------------------------------------------------------------+
  |Template       ios_baggage       ios_char_baggage   ios_pos_baggage |
  |structs:                                                            |
  +--------------------------------------------------------------------+
  |Template functions:                                                 |
  |basic_dec      basic_noshowbase  basic_oct          basic_showpos   |
  |basic_fixed    basic_noshowpoint basic_right        basic_skipws    |
  |basic_hex      basic_noskipws    basic_scientific   basic_uppercase |
  |basic_internal basic_nouppercase basic_showbase                     |
  |basic_left     basic_nowshowpos  basic_showpoint                    |
  +--------------------------------------------------------------------+
  |Classes:       basic_ios<char>   basic_ios<wchar_t> ios             |
  +--------------------------------------------------------------------+
  |Structs:                                                            |
  |ios_baggage<char>                ios_pos_baggage<streampos>         |
  |ios_baggage<wchar_t>             ios_pos_baggage<wstreampos>        |
  |ios_char_baggage<char>                                              |
  |ios_char_baggage<wchar_t>                                           |
  +--------------------------------------------------------------------+
  |Functions:                                                          |
  |dec            noshowbase        oct                showpos         |
  |fixed          noshowpoint       right              skipws          |
  |hex            noshowpos         scientific         uppercase       |
  |internal       noskipws          showbase                           |
  |left           nouppercase       showpoint                          |
  +--------------------------------------------------------------------+

3 Table 2:

                   Table 2--Header <iostream> synopsis

                  +------------------------------------+
                  |  Type             Name(s)          |
                  +------------------------------------+
                  |Objects:   cerr   cin   clog   cout |
                  +------------------------------------+

  +-------                 BEGIN BOX 1                -------+
  Is  it clear that these can be declared using incomplete types?  I'm a
  little unhappy about this name because people are going to assume that
  iostream is essentially the same as iostream.h.
  +-------                  END BOX 1                 -------+

4 Additional definitions:

  --Character  In this clause, the term ``character'' means the general­
    ized element of text data.  Each text data consist of a sequence  of
    character.   So  the  term does not only means the char type object,
    and the wchar_t type object, but also any sort of classes which pro­
    vides the definitions specified in (_lib.TBD_).

  --Character  container  type  Character container type is a class or a
    type which represent a character.  It is used for one  of  the  tem­
    plate parameter of the template IOStream classes.

  --The  template IOStream classes The template IOStream classes are the
    template classes which takes two template parameters: charT and bag­
    gage.   The  class,  charT, represents the character container class
    and the class, baggage, represents the baggage structure which  pro­
    vides the definition of the functionality necessary to implement the
    template IOStream classes.

  --Narrow-oriented  IOStream  classes  The   narrow-oriented   IOStream
    classes  are  the versions of the template IOStream classes special­
    ized with the character  container  class,  char.   The  traditional
    IOStream  classes  aree  regarded  as  the  narrow-oriented IOStream
    classes.

  --Wide-oriented IOStream classes The  wide-oriented  IOStream  classes
    are  the  versions of the template IOStream classes specialized with
    the character container class, wchar_t.

  27.1.1  Iostream character traits                [lib.iostream.traits]

  27.1.1.1  Template struct ios_baggage                [lib.ios.baggage]

  +-------                 BEGIN BOX 2                -------+
  At the Kitchener meeting, the Library WG decided to change  the  names
  used  from  ``baggage''  to ``traits''.  However, Tom Plum objected to
  doing this without a formal proposal and vote.  These names are there­
  fore unresolved, and subject to change.
  +-------                  END BOX 2                 -------+

  +-------                 BEGIN BOX 3                -------+
  I don't find the two level approach of ios_baggage useful.  I think it
  will simplify everyone's (i.e. both our  and  programmer's)  life  and
  shorten  the  working paper if we combine all the baggages (or traits)
  needed by any class in the standard into  a  single  template.   Using
  multiple  inheritance  we  can  arrange for everything to be specified
  exactly once, and only the wchar_t version needs  to  be  specialized.
  The char version is generic.

1 Proposal: Combine the following two into one

  template <class charT> struct char_traits<charT> {

      typedef char char_type;
      typedef int  int_type;

      static char_type to_char_type(int_type c) { return c; }
  // etc.
  +-------                  END BOX 3                 -------+

  template <class charT> struct ios_baggage {};
  struct ios_baggage<char> {
      typedef ios_char_baggage<char> char_bag;
      typedef ios_pos_baggage<streampos> pos_bag;
  };
  struct ios_baggage<wchar_t> {
      typedef ios_char_baggage<wchar_t> char_bag;
      typedef ios_pos_baggage<wstreampos> pos_bag;
  };

2 The template struct ios_baggage<charT> is an baggage class which main­
  tains the definitions of the types and functions necessary  to  imple­
  ment the template IOStream classes.  The template parameter charT rep­
  resents the character container type and each specialized version pro­
  vides the default definitions corresponding to the specialized charac­
  ter container type.

3 All of the types and functions provided in this struct can be  classi­
  fied  into  two categories, character-container-type-related and posi­
  tional-information-related.    Each   of   the   specialized   struct,
  ios_baggage<CHAR_T>,  in  which CHAR_T represents the specialized type
  of the character container type,  typedefs  two  specialized  template
  structs, ios_char_baggage<CHAR_T> and ios_pos_baggage<POS_T>, in which
  POS_T represents a specialized version of the  repositioning  informa­
  tion class.

  27.1.1.2  Template struct ios_char_baggage      [lib.ios.char.baggage]
    template <class charT> struct ios_char_baggage :
        public string_char_baggage<charT> {};

1 Every implementation shall provide the  following  two  specialization
  versions of the ios_char_baggage1):
  struct ios_char_baggage<char> {
      typedef char char_type;
      typedef int  int_type;

  _________________________
  1) The two types wchar_t and wint_t are declared in <cwchar>.

      static char_type to_char_type(int_type c) { return c; }
      static int_type  to_int_type (char_type c)  { return c; }
      static bool      eq_char_type(char_type c1, char_type c2) { return c1 == c2; }
      static bool      eq_int_type (int_type c1, int_type c2) { return c1 == c2; }
      static int_type  eof()     { return EOF; }
      static int_type  not_eof() { return  ~EOF; }
      static bool      is_eof(int_type c) { return c == EOF; }
      static char_type newline() { return '\n'; }
      static bool      is_whitespace(char_type c, locale::ctype<char> ctype) {
           return ctype.isspace<char>(c); }
      static char_type  eos() { return 0; }
      static size_t     length(const char_type* s) { return strlen(s); }
      static char_type* copy(char_type* dst, const char_type* src, size_t n)
                        { return strcpy(dst,src,size); }
  };
  struct ios_char_baggage<wchar_t> {
      typedef wchar_t char_type;
      typedef wint_t  int_type;
      static char_type to_char_type(int_type c) { return c; }
      static int_type  to_int_type (char_type c)  { return c; }
      static bool      eq_char_type(char_type c1, char_type c2) { return c1 == c2; }
      static bool      eq_int_type (int_type c1, int_type c2) { return c1 == c2; }
      static int_type  eof()     { return WEOF; }
      static int_type  not_eof() { return ~WEOF; }
      static bool      is_eof(int_type c) { return c == WEOF; }
      static char_type newline() { return L'\n'; }
      static bool      is_whitespace(char_type c, locale::ctype<char_type> ctype) {
           return ctype.isspace<char_type>(c); }
      static char_type  eos() { return 0; }

  +-------                 BEGIN BOX 4                -------+
  The  following  two  functions were not defined in the proposal.  They
  should be give the generic definitions.  Is that clear?
  +-------                  END BOX 4                 -------+

      static size_t     length(const char_type* s);
      static char_type* copy(char_type* dst, const char_type* src, size_t n);
    };

  +-------                 BEGIN BOX 5                -------+
  There are several types and functions needed for implementing the tem­
  plate  IOStream  classes.  Some of these types and functions depend on
  the definition of the character container  type.   The  collection  of
  these functions describes the behavior which the implementation of the
  template IOStream class expects to the character container class.

  Those who provide a character container class as the template  parame­
  ter  have  to  provide all of these functions as well as the container
  class itself.  The collection of these functions can  be  regarded  as
  the collection of the common definitions for the implementation of the
  character container class.

  No special definition/declaration is provided here.   The  base  class
  (or  struct),  string_char_baggage  provides  the  common  definitions

  common between the template string classes and the  template  IOStream
  classes.
  +-------                  END BOX 5                 -------+

2 The  template  struct ios_char_baggage<charT> is a struct derived from
  the class string_char_baggage<charT>.  For each of the character  con­
  tainer   classes,   CHAR_T,   the   corresponding  specialized  struct
  ios_char_baggage<CHAR_T> prepares the definitions related to the char­
  acter  container type so that it provides all the functionality neces­
  sary to implement the template IOStream classes.

3 Each of the specialization of the struct ios_char_baggage  shall  have
  the following definitions:
  struct ios_char_baggage<CHAR_T> {
      typedef CHAR_T char_type;
      typedef INT_T  int_type;
      static char_type to_char_type (int_type);
      static int_type  to_int_type (char_type);
      static bool      eq_char_type (char_type, char_type);
      static bool      eq_int_type (int_type, int_type);
      static int_type  eof();
      static int_type  not_eof();

  +-------                 BEGIN BOX 6                -------+
  Jerry Schwarz proposal: Change the declaration of not_eof to
     static int_type  not_eof(char_type c);
  with a generic description that it returns a value other than eof().

4 This  is  the  way the function is used by implementations.  It can be
  implemented efficiently in many cases and it provides an easy way  for
  me to specify return values in the working paper.
  +-------                  END BOX 6                 -------+

      static bool      is_eof(int_type);
      static char_type newline();
      static bool      is_whitespace(locale::ctype<char_type> ctype, char_type c);
      static char_type  eos();
      static size_t     length(const char_type* s);
      static char_type* copy(char_type* dst, const char_type* src, size_t n) ;
  };

  +-------                 BEGIN BOX 7                -------+
  If  the proposal for flattening the baggage classes is accepted, these
  classes will also need to be flattened.  A reasonable structure  would
  be
  class std_pos_traits {
      // note that this is not a template
      typedef streampos pos_t;
      typedef streamoff off_t;
  }
  template <class charT>
  struct std_traits<charT>
      : public std_char_traits<charT>, public std_pos_traits { }

  struct std_traits<wchar_t> : public std_char_traits<wchar_t> {
      typedef wstreampos pos_t;
      typedef wstreamoff off_t;
      // implementations are free to replace any other function provided
      // it satisfies the generic constraints for the given trait.
  }
  +-------                  END BOX 7                 -------+

  27.1.1.2.1  Type                         [lib.ios.char.baggage::int.t]
       ios_char_baggage::INT_T
      INT_T

1 Another character container type which can also  hold  an  end-of-file
  value.   It  is  used as the return type of some of the IOStream class
  member functions.  If CHAR_T is either char or wchar_t, INT_T shall be
  int or wint_t, respectively.

  27.1.1.2.2  Type                     [lib.ios.char.baggage::char.type]
       ios_char_baggage::char_type
      char_type

1 A synonym of the character container type, CHAR_T.

  27.1.1.2.3  Type                      [lib.ios.char.baggage::int.type]
       ios_char_baggage::int_type
      int_type

1 A synonym of the character container type, INT_T.

  27.1.1.2.4                        [lib.ios.char.baggage::to.char.type]
       ios_char_baggage::to_char_type
      char_type to_char_type(int_type c);

1 Converts a valid character value represented in the  int_type  to  the
  corresponding  char_type  value.   If  c is the end-of-file value, the
  return value is unspecified.

  27.1.1.2.5                         [lib.ios.char.baggage::to.int.type]
       ios_char_baggage::to_int_type
      int_type to_int_type(char_type c);

1 Converts a valid character value represented in the char_type  to  the
  corresponding int_type value.

  27.1.1.2.6                        [lib.ios.char.baggage::eq.char.type]
       ios_char_baggage::eq_char_type
      bool eq_char_type(char_type c1, char_type c2);

1 Returns true if c1 and c2 represent the same character.

  27.1.1.2.7                         [lib.ios.char.baggage::eq.int.type]
       ios_char_baggage::eq_int_type
      bool eq_int_type(int_type c1, int_type c2);

1 Returns true if c1 and c2 represent the same character.

  27.1.1.2.8  ios_char_baggage::eof          [lib.ios.char.baggage::eof]
      int_type eof();

1 Returns  an  int_type  value  which represents the end-of-file.  It is
  returned by several functions to indicate end-of-file state  (no  more
  input  from an input sequence or no more output permitted to an output
  sequence), or to indicate an invalid return value.

  27.1.1.2.9                             [lib.ios.char.baggage::not.eof]
       ios_char_baggage::not_eof
      int_type not_eof();

1 Returns  a  certain  int_type value other than the end-of-file.  It is
  used in basic_streambuf<charT,baggage>::overflow().

  27.1.1.2.10                             [lib.ios.char.baggage::is.eof]
       ios_char_baggage::is_eof
      bool is_eof(int_type c);

1 Returns true if c represent the end-of-file.

  27.1.1.2.11                            [lib.ios.char.baggage::newline]
       ios_char_baggage::newline
      char_type newline();

1 Returns a character value which represent the newline character of the
  basic   character  set.   It  appears  as  the  default  parameter  of
  basic_istream<charT,baggage>::getline().

  27.1.1.2.12                      [lib.ios.char.baggage::is.whitespace]
       ios_char_baggage::is_whitespace
      bool is_whitespace(char_type c, locale::ctype<char_type> ctype);

1 Returns true if c represents one of the white space  characters.   The
  default definition is as if it returns ctype.isspace(c).

2 An  implementation of the template IOStream classes may use all of the
  above static member functions in addition to the following three func­
  tions provided from the base struct string_char_baggage<CHAR_T>.

  27.1.1.2.13  ios_char_baggage::eos         [lib.ios.char.baggage::eos]
      char_type eos();

1 Returns  the  null  character which is used for the terminator of null
  terminated character strings.  The default constructor for the charac­
  ter container type provides the value.

  27.1.1.2.14                             [lib.ios.char.baggage::length]
       ios_char_baggage::length
      size_t length(const char_type* s);

1 Determines the length of a null terminated character string pointed to
  by s.

  27.1.1.2.15  ios_char_baggage::copy       [lib.ios.char.baggage::copy]
      char_type* copy(char_type* dest, const char_type* src, size_t n);

1 Copies  n characters from the object pointed to by src into the object
  pointed to by dest.  If copying takes place between objects that over­
  lap, the behavior is undefined.

  +-------                 BEGIN BOX 8                -------+
  The  reason that these two member functions, length and copy, are pre­
  pared is to achive efficiency for char and  wchar_t  specialized  ver­
  sions.   If  the character container type require no special construc­
  tion/destruction operations (or it is a immutable class),  the  memory
  copy  operation  leads us to avoid inefficiency which an explicit copy
  loop in the implementation of the template IOStream classes give  rise
  to.
  +-------                  END BOX 8                 -------+

  27.1.2  Positional information                        [lib.positional]

  +-------                 BEGIN BOX 9                -------+
  The  description of the following member functions is incomplete.  The
  behavior and specification of the streampos/streamoff should need more
  discussion.
  +-------                  END BOX 9                 -------+

  27.1.2.1  Template struct ios_pos_baggage        [lib.ios.pos.baggage]
  template <class posT> struct ios_pos_baggage {};
  struct ios_pos_baggage<streampos> {
      typedef streampos pos_type;
      typedef streamoff off_type;
  };
  struct ios_pos_baggage<wstreampos> {
      typedef wstreampos pos_type;
      typedef wstreamoff off_type;
  };

1 The  template  struct  ios_pos_baggage<posT> is a struct.  For each of
  the repositional information class, POS_T, the corresponding  special­
  ized  struct  ios_pos_baggage<POS_T>  prepares the typedefs related to
  the POS_T.

2
  +-------                BEGIN BOX 10                -------+
  Jerry Schwarz proposal: Rewrite the following sections to clarify that
  we  are  talking  about  generic  requirements  for  members of a user

  supplied baggage::pos_bag and not  only  ios_char_baggage  specializa­
  tions.
  +-------                 END BOX 10                 -------+

  Each  of  the  specialization of the struct ios_pos_baggage shall have
  the following definitions:
    struct ios_pos_baggage<POS_T> {
        typedef POS_T pos_type;
        typedef OFF_T off_type;
  };

  27.1.2.1.1  Type                          [lib.ios.pos.baggage::off.t]
       ios_pos_baggage::OFF_T
      OFF_T;

1 A  synonym  for  one of the signed integral types whose representation
  has at least as many bits as type long.

  27.1.2.1.2  Type                       [lib.ios.pos.baggage::off.type]
       ios_pos_baggage::off_type
     off_type;

1 A synonym of the OFF_T and is used for declaring/implementing the tem­
  plate IOStream class.

  27.1.2.1.3  Type                          [lib.ios.pos.baggage::pos.t]
       ios_pos_baggage::POS_T
      POS_T;

1 An implementation-defined class for seek operations which describes an
  object that can store all the information necessary to restore to  the
  position.

  27.1.2.1.4  Type                       [lib.ios.pos.baggage::pos.type]
       ios_pos_baggage::pos_type
      pos_type;

1 A synonym for the class POS_T which is used for declaring/implementing
  the template IOStream classes.

  27.1.2.2  Type OFF_T requirements                   [lib.off.t.reqmts]

1 The type OFF_T is a synonym for one if the signed basic integral types
  T1 whose representation at least as many bits as  type  long.   It  is
  used to represent:

  --a  signed  displacement,  measured  in  characters, from a specified
    position within a sequence.

  --an absolute position within a sequence.

  +-------                BEGIN BOX 11                -------+
  Jerry Schwarz proposal: Revrite the following so that it is clear that
  certain  operations  are  possible  on baggage::char_bag::pos_type but

  that  it need not be a class.  One of the advantages of the templatiz­
  ing     approach     is     that     implementations     can      make
  ios_pos_baggage<char>::pos_type the same as their current streampos.
  +-------                 END BOX 11                 -------+

  27.1.2.3  Type POS_T requirements                   [lib.pos.t.reqmts]

1 Every  class that can apply to the template parameter posT in the tem­
  plate struct ios_pos_baggage shall have following definitions:
      typedef T1 OFF_T;

  +-------                BEGIN BOX 12                -------+
  Jerry Schwarz  proposal:  Replace  POS_T::offset  by  fPOS_T::operator
  OFF_T.  The point is to allow POS_T to be a non-class.
  +-------                 END BOX 12                 -------+

  class POS_T {
  public:
      POS_T(int off);
      POS_T(OFF_T off = 0);
      OFF_T  offset() const;
      OFF_T  operator- (POS_T& rhs);
      POS_T& operator+=(OFF_T off);
      POS_T& operator-=(OFF_T off);
      POS_T  operator+ (OFF_T off);
      POS_T  operator- (OFF_T off);
      bool   operator==(POS_T& rhs) const;
      bool   operator!=(POS_T& rhs) const;
  };

  +-------                BEGIN BOX 13                -------+
  The  asymmetries  implied  by making operator+, operator-,  operator==
  and operator!= members rather than global operators are unpleasant.
  +-------                 END BOX 13                 -------+

  +-------                BEGIN BOX 14                -------+
  This subclause need more discussion.  How do we treat the case if  the
  external  source/sink  stream  does  not ensure to accept POS_T, OFF_T
  object to which some arithmetic operations performed?
  +-------                 END BOX 14                 -------+

2 The class POS_T describes an object that can store all the information
  necessary  to  restore  one  or  more types of sequences to a previous
  stream position.  Every POS_T class has the corresponding  OFF_T  type
  and the set of applicable stream classes.

  --Repositional  Streams and Arbitrary-positional Streams There are two
    types of stream:  repositional and arbitrary-positional.

  +-------                BEGIN BOX 15                -------+
  There are also non-positional streams in which no seeking is possible.

  +-------                 END BOX 15                 -------+

3 With  a repositional stream, we can seek to only the position where we
  previously  encountered.   On  the  other  hand,  with  an  arbitrary-
  positional  stream,  we  can  seek to any integral position within the
  length of the stream.

4 For a stream buffer which is corresponding to  a  repositional  stream
  (but  not  a  arbitrary-positional stream), all we can do is either to
  fetch the current position of the stream buffer or to specify the pre­
  vious position which we have already fetched from the stream buffer.

5 Every arbitrary-positional stream is a repositional.

6 If  a  repositional stream returns a POS_T object, and some arithmetic
  operations  (operator+=,  operator-,   operator+=,   operator-=)   are
  applied,  the behavior of the stream after restoring the position with
  the modified POS_T object is undefined.  It means that a POS_T  object
  whose  parent  stream  is  repositional shall not apply any arithmetic
  operations.

7 It is not ensured that in case the validity of a certain POS_T  object
  is  broken,  the error shall be informed.  Or there is no way to check
  the validity of a certain POS_T object.

  --Invalid POS_T value The stream operations whose return type is POS_T
    may  return POS_T((OFF_T)(-1)) as signal to some error occurs.  This
    return value is called the invalid  POS_T  value.   The  constructor
    POS_T::POS_T((OFF_T)(-1))  constructs the invalid POS_T value, which
    is available only for comparing to the return value of  such  member
    functions.

  27.1.2.3.1  POS_T constructors                        [lib.pos.t.cons]
      POS_T(int off);
      POS_T(OFF_T off = 0);

1 [Almost same as _lib.streampos.cons_]

2 Constructs an object of type POS_T, initializing pos to zero and fp to
  the stream position at the beginning of the sequence, with the conver­
  sion state at the beginning of a new multibyte sequence in the initial
  shift  state.2) The constructor then evaluates the expression *this +=
  off.

  27.1.2.3.2  POS_T::offset                       [lib.ios.pos.t.offset]
      OFF_T  offset() const;

1 [Almost same as _lib.streampos.offset_]

  _________________________
  2) The next character to read or write is the first character  in  the
  sequence.

2 Determines the value of type OFF_T that represents the stream position
  stored in pos and fp, if possible, and returns that value.  Otherwise,
  returns (OFF_T)(-1).  For a sequence  requiring  a  conversion  state,
  even  a  representable  value of type OFF_T need not supply sufficient
  information to restore the stored stream position.

  27.1.2.3.3  POS_T::operator-                 [lib.ios.pos.t.op-.pos.t]
      OFF_T  operator- (POS_T& rhs);

1 [Almost same as _lib.streampos.op-_]

2 Determines the value of type POS_T that represents the  difference  in
  stream  positions between *this and rhs, if possible, and returns that
  value.  (If *this is a stream position nearer  the  beginning  of  the
  sequence  than  rhs,  the difference is negative.)  Otherwise, returns
  (streamoff)(-1).  For a sequence that does not represent stream  posi­
  tions  in  uniform units, even a representable value need not be mean­
  ingful.

3 If the parent stream is not arbitrary-positional,  the  value  of  the
  operation becomes invalid so it may not apply the parent stream.

  27.1.2.3.4  POS_T::operator+=                     [lib.ios.pos.t.op+=]
      POS_T& operator+=(OFF_T off);

1 [Almost same as _lib.streampos.op+=_]

2 Adds off to the stream position stored in pos and fp, if possible, and
  replaces the stored values.  Otherwise, the function stores an invalid
  stream position in pos and fp.  For a sequence that does not represent
  stream positions in uniform units, the resulting stream position  need
  not be meaningful.

3 Returns *this.

4 If  the  parent  stream  is not arbitrary-positional, the value of the
  operation becomes invalid so it may not apply the parent stream.

  27.1.2.3.5  POS_T::operator-=                     [lib.ios.pos.t.op-=]
      POS_T& operator-=(OFF_T off);

1 [Almost same as _lib.streampos.op-=_]

2 Subtracts off from the stream position stored in pos and fp, if possi­
  ble, and replaces the stored value.  Otherwise, the function stores an
  invalid stream position in pos and fp.  For a sequence that  does  not
  represent  stream  positions  in  uniform  units, the resulting stream
  position need not be meaningful.

3 Returns *this.

4 If the parent stream is not arbitrary-positional,  the  value  of  the
  operation becomes invalid so it may not apply the parent stream.

  27.1.2.3.6  POS_T::operator+                       [lib.ios.pos.t.op+]
      POS_T  operator+ (OFF_T off);

1 [Almost same as _lib.streampos.op+_]

2 Returns POS_T(*this) += off.

  27.1.2.3.7  POS_T::operator-                 [lib.ios.pos.t.op-.off.t]
      POS_T  operator- (OFF_T off);

1 [Almost same as _lib.streampos.op-_]

2 Returns POS_T(*this) -= off.

  27.1.2.3.8  POS_T::operator==                     [lib.ios.pos.t.op==]
      bool   operator==(POS_T& rhs) const;

1 [Almost same as _lib.streampos.op==_]

2 Compares  the  stream  position stored in *this to the stream position
  stored in rhs, and returns true if the  two  correspond  to  the  same
  position within a file or if both store an invalid stream position.

  27.1.2.3.9  POS_T::operator!=                     [lib.ios.pos.t.op!=]
      bool   operator!=(POS_T& rhs) const;

1 [Almost same as _lib.streampos.op!=_]

2 Returns true if !(*this == rhs).

  27.1.2.4  Type streamoff                               [lib.streamoff]
          typedef T2 streamoff;

1 The  type  streamoff is a synonym for one of the signed basic integral
  types T1 whose representation has at least as many bits as type  long.
  The  corresponding POS_T class is the class, streampos.  It is used to
  represent:

  --a signed displacement, measured in bytes, from a specified  position
    within a sequence;

2 If a streamoff object has a value other than the parent stream returns
  (for example, assigned an arbitrary integer), the value may not  apply
  any streams.

3 Any  streamoff  object  can  be  converted  to  a  streampos object is
  ensured.  But no validity of the result streampos object  is  ensured,
  whether the streamoff object is valid or else.

  27.1.2.5  Type streamsize                             [lib.streamsize]
          typedef T3 streamsize;

1 The  type streamsize is a synonym for one of the signed basic integral
  types.  It is used to represent the number of  characters  transferred

  in an I/O operation, or the size of I/O buffers.3)

  27.1.2.6  Class wstreamoff                            [lib.wstreamoff]

1 [Almost the same description as in streamoff]

  27.1.2.7  Class streampos                              [lib.streampos]

1 In this subclause, the type name fpos_t is  a  synonym  for  the  type
  fpos_t defined in <cstdio> (_lib.file.streams_).
  class streampos {
  public:
      streampos(streamoff off = 0);
      streamoff  offset() const;
      streamoff  operator-(streampos& rhs) const;
      streampos& operator+=(streamoff off);
      streampos& operator-=(streamoff off);
      streampos  operator+(streamoff off) const;
      streampos  operator-(streamoff off) const;
      bool       operator==(const streampos& rhs) const;
      bool       operator!=(const streampos& rhs) const;
  private:
  //  streamoff pos;      exposition only
  //  fpos_t fp;          exposition only
  };

  27.1.2.8   Class wstreampos                           [lib.wstreampos]

1 [Almost the same description as in streampos]

2 The  class streampos describes an object that can store all the infor­
  mation necessary to restore an arbitrary sequence, controlled  by  the
  Standard  C++  library,  to  a previous stream position and conversion
  state.4) For the sake of exposition, the data it stores  is  presented
  here as:

  --streamoff pos, specifies the absolute position within the sequence;

  --fpos_t fp, specifies the stream position and conversion state in the
    implementation-dependent form  required  by  functions  declared  in
    <cstdio>.

  _________________________
  3)  streamsize  is  used  in most places where ISO C would use size_t.
  Most of the uses of  streamsize  could  use  size_t,  except  for  the
  strstreambuf constructors, which require negative values.

  The  streamsize  type should probably be the signed type corresponding
  to size_t (which is what Posix.2 calls ssize_t).
  4) The conversion state is used for sequences that  translate  between
  wide-character  and  generalized  multibyte  encoding, as described in
  Amendment 1 to the C Standard.

3 It  is unspecified how these two member objects combine to represent a
  stream position.

  27.1.2.8.1  streampos constructor                 [lib.streampos.cons]

  +-------                BEGIN BOX 16                -------+
  One of the advantages of the template approach is that  streampos  can
  does not have to hold the state information required for wide oriented
  streams.

1 Jerry Schwarz proposal: Replace this section with:  streaampos  satis­
  fies the generic constraints on a POS_T.
  +-------                 END BOX 16                 -------+

      streampos(streamoff off = 0);

2 Constructs  an object of class streampos, initializing pos to zero and
  fp to the stream position at the beginning of the sequence,  with  the
  conversion  state  at the beginning of a new multibyte sequence in the
  initial  shift  state.5) The constructor then evaluates the expression
  *this += off.

  27.1.2.8.2  streampos::offset                  [lib.streampos::offset]
      streamoff offset() const;

1 Determines the value of type  streamoff  that  represents  the  stream
  position  stored  in  pos and fp, if possible, and returns that value.
  Otherwise, returns (streamoff)(-1).

2 For a sequence requiring a  conversion  state,  even  a  representable
  value  of  type  streamoff  need  not supply sufficient information to
  restore the stored stream position.

  27.1.2.8.3  streampos::operator-               [lib.streampos::op-.sp]
      streamoff operator-(streampos& rhs) const;

1 Determines the value of type streamoff that represents the  difference
  in  stream  positions  between *this and rhs, if possible, and returns
  that value.  (If *this is a stream position nearer  the  beginning  of
  the  sequence  than  rhs,  the  difference  is  negative.)  Otherwise,
  returns (streamoff)(-1).

2 For a sequence that does not represent  stream  positions  in  uniform
  units, even a representable value need not be meaningful.

  27.1.2.8.4  streampos::operator+=                [lib.streampos::op+=]
      streampos& operator+=(streamoff off);

1 Adds off to the stream position stored in pos and fp, if possible, and
  replaces the stored values.  Otherwise, the function stores an invalid
  _________________________
  5) The next character to read or write is the first character  in  the
  sequence.

  stream position in pos and fp.

2 For  a  sequence  that  does not represent stream positions in uniform
  units, the resulting stream position need not be meaningful.

3 Returns *this.

  27.1.2.8.5  streampos::operator-=                 [lib.streamos::op-=]
      streampos& operator-=(streamoff off);

1 Subtracts off from the stream position stored in pos and fp, if possi­
  ble, and replaces the stored value.  Otherwise, the function stores an
  invalid stream position in pos and fp.

2 For a sequence that does not represent  stream  positions  in  uniform
  units, the resulting stream position need not be meaningful.

3 Returns *this.

  27.1.2.8.6  streampos::operator+                  [lib.streampos::op+]
      streampos operator+(streamoff off) const;

1 Returns streampos(*this) += off.

  27.1.2.8.7  streampos::operator-              [lib.streampos::op-.off]
      streampos operator-(streamoff off) const;

1 Returns streampos(*this) -= off.

  27.1.2.8.8  streampos::operator==                [lib.streampos::op==]
      bool operator==(const streampos& rhs) const;

1 Compares  the  stream  position stored in *this to the stream position
  stored in rhs, and returns true if the  two  correspond  to  the  same
  position within a file or if both store an invalid stream position.

  27.1.2.8.9  streampos::operator!=                 [lib.op!=.streampos]
      bool operator!=(const streampos& rhs) const;

1 Returns true if !(*this == rhs).

  27.1.3  Base class ios and manipulators                 [lib.ios.base]

1 The header <ios> defines three types that controls input from and out­
  put to character sequence.

  27.1.3.1  Template class basic_ios                           [lib.ios]

  template<class charT, class baggage = ios_baggage<charT> >
  class basic_ios {
      typedef basic_ios<charT,baggage> ios_type;
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;
      int_type  eof()     { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }

  +-------                BEGIN BOX 17                -------+
  Note: An idea to declare eof as a constant, that is,
    static const IEOF = baggage::char_bag::eof(),
  is  rejected  because  it  cause  a constraint that charT and int_type
  should be integral types.
  +-------                 END BOX 17                 -------+

      class failure : public exception {
      public:
          failure(const string& what_arg);
          virtual ~failure();
  //    virtual string what() const;    inherited
      protected:
      };
      typedef T1 fmtflags;
      static const fmtflags boolalpha;
      static const fmtflags dec;
      static const fmtflags fixed;
      static const fmtflags hex;
      static const fmtflags internal;
      static const fmtflags left;
      static const fmtflags oct;
      static const fmtflags right;
      static const fmtflags scientific;
      static const fmtflags showbase;
      static const fmtflags showpoint;
      static const fmtflags showpos;
      static const fmtflags skipws;
      static const fmtflags unitbuf;
      static const fmtflags uppercase;
      static const fmtflags adjustfield;
      static const fmtflags basefield;
      static const fmtflags floatfield;
      typedef T2 iostate;
      static const iostate badbit;
      static const iostate eofbit;
      static const iostate failbit;
      static const iostate goodbit;

      typedef T3 openmode;
      static const openmode app;
      static const openmode ate;
      static const openmode binary;
      static const openmode in;
      static const openmode out;
      static const openmode trunc;
      typedef T4 seekdir;
      static const seekdir beg;
      static const seekdir cur;
      static const seekdir end;
      class Init {
      public:
          Init();
         ~Init();
      private:
  //  static int init_cnt;        exposition only
      };
      basic_ios(basic_streambuf<charT,baggage>* sb_arg);
      virtual ~basic_ios();
      operator bool() const
      bool operator!() const
      ios_type& copyfmt(const ios_type& rhs);
      basic_ostream<charT,baggage>* tie() const;
      basic_ostream<charT,baggage>* tie(basic_ostream<charT,baggage>* tiestr_arg);
      basic_streambuf<charT,baggage>* rdbuf() const;
      basic_streambuf<charT,baggage>* rdbuf(basic_streambuf<charT,baggage>* sb_arg);

  +-------                BEGIN BOX 18                -------+
  Note:   template   parameter   coupling    between    basic_ios    and
  basic_streambuf:  Both  basic_ios and basic_streambuf corresponding to
  it should take the same template parameter <charT,baggage>.   We  need
  not    allow    to   make   a   couple   of   basic_ios<wchar_t>   and
  basic_streambuf<char>.
  +-------                 END BOX 18                 -------+

      iostate rdstate() const;
      void clear(iostate state_arg = goodbit);
      void setstate(iostate state_arg);
      bool good() const;
      bool eof()  const;
      bool fail() const;
      bool bad()  const;
      iostate exceptions() const;
      void exceptions(iostate except_arg);
      fmtflags flags() const;
      fmtflags flags(fmtflags fmtfl_arg);
      fmtflags setf(fmtflags fmtfl_arg);
      fmtflags setf(fmtflags fmtfl_arg, fmtflags mask);
      void unsetf(fmtflags mask);

  +-------                BEGIN BOX 19                -------+
  Specifying fill character.  It is represented as int_type.
  +-------                 END BOX 19                 -------+

      int_type fill() const;
      int_type fill(int_type ch);
      int precision() const;
      int precision(int prec_arg);
      int width() const;
      int width(int wide_arg);
      locale imbue(const locale& loc_arg);
      locale getloc() const;
      static int xalloc();
      long&  iword(int index_arg);
      void*& pword(int index_arg);
  protected:
      basic_ios();
      void init(basic_streambuf<charT,baggage>* sb_arg);
  private:
  //  basic_streambuf<charT,baggage>* sb;         exposition only
  //  basic_ostream<charT,baggage>* tiestr;       exposition only
  //  iostate state;      exposition only
  //  iostate except;     exposition only
  //  fmtflags fmtfl;     exposition only
  //  int prec;           exposition only
  //  int wide;           exposition only
  //  char fillch;        exposition only
  //  locale loc;         exposition only
  //  static int index;   exposition only
  //  int* iarray;        exposition only
  //  void** parray;      exposition only
  };

  +-------                BEGIN BOX 20                -------+
  Lots of things that should  be  the  same  in  all  instantiations  of
  basic_ios are made members.  In particular it seems that failure, fmt­
  flags, iostate, openmode, seekdir, and  all  the  constants  of  these
  types should be the same in different instances.

  Jerry Schwarz proposal:
  class ios_constants {
      class failure .... ;
      typedef T1 fmtflags;
      ....; // bits of fmtflags;
      typedef T2 iostate;
      ....; // bits of iostate
      typedef T3 openmode;
      ....; // bits of openmode
      typedef T4 seekdir;
      ....; // bits of seekdir
  };
  template<class charT, class traits = std_traits<charT> >
  class basic_ios : public ios_constants {
      ....
  };
  +-------                 END BOX 20                 -------+

      class ios : public basic_ios<char> {}

    class wios : public basic_ios<wchar_t> {}

  +-------                BEGIN BOX 21                -------+
  Jerry Schwarz proposal: Replace with
      typedef basic_ios<char>    ios ;
      typedef basic_ios<wchar_t> wios;
  +-------                 END BOX 21                 -------+

1 The template class basic_ios<charT,baggage> serves as a base class for
  the         classes          basic_istream<charT,baggage>          and
  basic_ostream<charT,baggage>.

2 The class ios is an instance of the template class basic_ios, special­
  ized by the type char.

3 The class wios is a version of the template class  basic_ios  special­
  ized by the type wchar_t.

4 basic_ios defines several member types:

  --a class failure derived from exception;

  --a class Init;

  +-------                BEGIN BOX 22                -------+
  Jerry  Schwarz proposal: Eliminate basic_ios::Init and replace it by a
  requirement (in _lib.iostreams_) that the standard streams  should  be
  initialized  before startup.  We had a discussion of this in San Diego
  and I think this was the consensus.  The "nifty counter" trick is gen­
  erally  regarded  as a bad way to cause initialization of the standard
  streams because of the overheads.
  +-------                 END BOX 22                 -------+

  --three bitmask types, fmtflags, iostate, and openmode;

  --an enumerated type, seekdir.

5 It maintains several kinds of data:

  --a   pointer   to   a   stream   buffer,   an   object    of    class
    basic_streambuf<charT,baggage>,  that  controls  sources (input) and
    sinks (output) of character sequences; the parameter charT specifies
    the type of character;

  --state information that reflects the integrity of the stream buffer;

  --control  information that influences how to interpret (format) input
    sequences and how to generate (format) output sequences;

  --additional information that is stored by the program for its private
    use.

6 For the sake of exposition, the maintained data is presented here as:

  --basic_streambuf<charT,baggage>* sb, points to the stream buffer;

  --basic_ostream<charT,baggage>*  tiestr,  points to an output sequence
    that is tied to (synchronized with) an input sequence controlled  by
    the stream buffer;

  --iostate state, holds the control state of the stream buffer;

  --iostate  except,  holds  a mask that determines what elements set in
    state cause exceptions to be thrown;

  --fmtflags fmtfl, holds format control information for both input  and
    output;

  --int wide, specifies the field width (number of characters) to gener­
    ate on certain output conversions;

  --int prec, specifies the precision (number of digits after the  deci­
    mal point) to generate on certain output conversions;

  --char  fillch, specifies the character to use to pad (fill) an output
    conversion to the specified field width;

  --locale loc,  specifies  the  locale  in  which  to  perform  locale-
    dependent input and output operations;

  --static  int index, specifies the next available unique index for the
    integer or pointer arrays maintained for the private use of the pro­
    gram, initialized to an unspecified value;

  --int*  iarray,  points  to  the  first element of an arbitrary-length
    integer array maintained for the private use of the program;

  --void** parray, points to the first element  of  an  arbitrary-length
    pointer array maintained for the private use of the program.

  27.1.3.1.1  Class basic_ios::failure                [lib.ios::failure]
  class failure : public exception {
  public:
      failure(const string& what_arg);
      virtual ~failure();
  //  virtual string what() const;        inherited
  };

1 The  class failure defines the base class for the types of all objects
  thrown as exceptions, by functions in the iostreams library, to report
  errors detected during stream buffer operations.

  27.1.3.1.1.1  basic_ios::failure         [lib.basic.ios::failure.cons]
       constructor
      failure(const char* what_arg = 0);

1 Constructs an object of class failure,  initializing  the  base  class
  with exception(what_arg).

  +-------                BEGIN BOX 23                -------+
  Jerry Schwarz proposal: Allow an implementation defined default value.
  +-------                 END BOX 23                 -------+

  27.1.3.1.1.2                              [lib.basic.ios::failure.des]
       basic_ios::failure::~failure
       destructor
      virtual ~failure();

1 Destroys an object of class failure.

  27.1.3.1.1.3  basic_ios::failure::what        [lib.ios::failure::what]
  //  virtual string what() const;    inherited

1 Behaves the same as exception::what().

  27.1.3.1.2  Type basic_ios::fmtflags               [lib.ios::fmtflags]
      typedef T1 fmtflags;

1 The type fmtflags is a bitmask type (indicated here as  T1).   Setting
  its elements has the effects indicated in Table 3:

                        Table 3--fmtflags effects

  -----------------------------------------------------------------------
          Element                           Effect(s) if set
  -----------------------------------------------------------------------
         boolalpha                       insert and extract bool
                                         type in alphabetic for­
                                         mat
         dec                             converts  integer input
                                         or  generates   integer
                                         output in decimal base
         fixed                           generate floating-point
                                         output  in  fixed-point
                                         notation;
         hex                             converts  integer input
                                         or  generates   integer
                                         output  in  hexadecimal
                                         base;
         internal                        adds fill characters at
                                         a  designated  internal
                                         point in certain gener­
                                         ated output;
         left                            adds fill characters on
                                         the left (initial posi­
                                         tions)  of certain gen­
                                         erated output;
         oct                             converts integer  input
                                         or   generates  integer
                                         output in octal base;
         right                           adds fill characters on
                                         the  right (final posi­
                                         tions) of certain  gen­
                                         erated output;
         scientific                      generates     floating-
                                         point output in  scien­
                                         tific notation;
         showbase                        generates  a prefix in­
                                         dicating  the   numeric
                                         base of generated inte­
                                         ger output;
         showpoint                       generates  a   decimal-
                                         point  character uncon­
                                         ditionally in generated
                                         floating-point output;
         showpos                         generates  a  + sign in
                                         non-negative  generated
                                         numeric output;
         skipws                          skips   leading   white
                                         space  before   certain
                                         input operations;

  |                                                                     |
  |                                                                     |
  |                                                                     |
  |                                                                     |
  |      unitbuf                         flushes   output  after        |
  |                                      each output operation;         |
  |      uppercase                       replaces certain lower­        |
  |                                      case letters with their        |
  |                                      uppercase   equivalents        |
  |                                      in generated output.           |
  +---------------------------------------------------------------------+

2 Type fmtflags also defines the constants indicated in Table 4:

                       Table 4--fmtflags constants

                 +--------------------------------------+
                 | Constant        Allowable values     |
                 +--------------------------------------+
                 |adjustfield   left | right | internal |
                 |basefield     dec | oct | hex         |
                 |floatfield    scientific | fixed      |
                 +--------------------------------------+

  27.1.3.1.3  Type basic_ios::iostate                 [lib.ios::iostate]
      typedef T2 iostate;

1 The  type  iostate  is a bitmask type (indicated here as T2).  It con­
  tains the elements indicated in Table 5:

                         Table 5--iostate effects

  +---------------------------------------------------------------------+
  |       Element                           Effect(s) if set            |
  +---------------------------------------------------------------------+
  |       badbit                         indicates a loss of in­        |
  |                                      tegrity  in an input or        |
  |                                      output  sequence  (such        |
  |                                      as   an   irrecoverable        |
  |                                      read   error   from   a        |
  |                                      file);                         |
  |       eofbit                         indicates that an input        |
  |                                      operation  reached  the        |
  |                                      end  of  an  input  se­        |
  |                                      quence;                        |
  |       failbit                        indicates that an input        |
  |                                      operation   failed   to        |
  |                                      read the expected char­        |
  |                                      acters, or that an out­        |
  |                                      put operation failed to        |
  |                                      generate   the  desired        |
  |                                      characters.                    |
  +---------------------------------------------------------------------+

2 Type iostate also defines the constant:

  --goodbit, the value zero.

  27.1.3.1.4  Type basic_ios::openmode               [lib.ios::openmode]
      typedef T3 openmode;

1 The type openmode is a bitmask type (indicated here as T3).   It  con­
  tains the elements indicated in Table 6:

                        Table 6--openmode effects

  +---------------------------------------------------------------------+
  |       Element                           Effect(s) if set            |
  +---------------------------------------------------------------------+
  |       app                            seek to end-of-file be­        |
  |                                      fore each write to the         |
  |                                      file                           |
  |       ate                            open a file and seek to        |
  |                                      end-of-file immediately        |
  |                                      after opening the file         |
  |       binary                         perform input and out­         |
  |                                      put in binary mode (as         |
  |                                      opposed to text mode)          |
  |       in                             open a file for input          |
  |       out                            open a file for output         |
  |       trunc                          truncate an existing           |
  |                                      file when opening it           |
  +---------------------------------------------------------------------+

  27.1.3.1.5  Type basic_ios::seekdir                 [lib.ios::seekdir]
      typedef T4 seekdir;

1 The type seekdir is an enumerated type (indicated  here  as  T4).   It
  contains the elements indicated in Table 7:

                         Table 7--seekdir effects

  +---------------------------------------------------------------------+
  |       Element                                Meaning                |
  +---------------------------------------------------------------------+
  |       beg                            request a seek (posi­          |
  |                                      tioning for subsequent         |
  |                                      input or output within         |
  |                                      a sequence) relative to        |
  |                                      the beginning of the           |
  |                                      stream                         |
  |       cur                            request a seek relative        |
  |                                      to the current position        |
  |                                      within the sequence            |
  |       end                            request a seek relative        |
  |                                      to the current end of          |
  |                                      the sequence                   |
  +---------------------------------------------------------------------+

  27.1.3.1.6  Class basic_ios::Init                      [lib.ios::Init]

  +-------                BEGIN BOX 24                -------+
  Jerry Schwarz proposal: Eliminate basic_ios::Init and replace it by  a
  requirement  (in  _lib.iostreams_) that the standard streams should be
  initialized before startup.  We had a discussion of this in San  Diego
  and I think this was the consensus.  The "nifty counter" trick is gen­
  erally regarded as a bad way to cause initialization of  the  standard
  streams because of the overheads.
  +-------                 END BOX 24                 -------+

  class Init {
  public:
      Init();
     ~Init();
  private:
  //  static int init_cnt;        exposition only
  };

1 The class Init describes an object whose construction ensures the con­
  struction of the four objects declared in  <iostream>  that  associate
  file  stream  buffers  with the standard C streams provided for by the
  functions declared in <cstdio> (_lib.file.streams_).

2 For the sake of exposition, the maintained data is presented here as:

  --static int init_cnt, counts the number of constructor and destructor
    calls for class Init, initialized to zero.

  27.1.3.1.6.1  basic_ios::Init               [lib.basic.ios::init.cons]
       constructor
      Init();

1 Constructs an object of class Init.  If init_cnt is zero, the function
  stores  the value one in init_cnt, then constructs and initializes the
  four objects cin (_lib.cin_), cout  (_lib.cout_),  cerr  (_lib.cerr_),
  and clog (_lib.clog_).  In any case, the function then adds one to the
  value stored in init_cnt.

  27.1.3.1.6.2  basic_ios::Init                [lib.basic.ios::init.des]
       destructor
      ~Init();

1 Destroys an object of class Init.  The function subtracts one from the
  value stored in init_cnt and, if the resulting stored  value  is  one,
  calls cout.flush(), cerr.flush(), and clog.flush().

  27.1.3.1.7  basic_ios::basic_ios               [lib.basic.ios.sb.cons]
       constructor
      basic_ios(basic_streambuf<charT,baggage>* sb_arg);

1 Constructs an object of class basic_ios, assigning initial  values  to
  its member objects by calling init(sb_arg).

  27.1.3.1.8  basic_ios destructor                   [lib.basic.ios.des]
      virtual ~basic_ios();

1 Destroys an object of class basic_ios.

  27.1.3.1.9  basic_ios::operator bool          [lib.ios::operator.bool]
      operator bool() const

1 Returns  a  non-null pointer (whose value is otherwise unspecified) if
  failbit | badbit is set in state.

  27.1.3.1.10  basic_ios::operator!                 [lib.ios::operator!]
      bool operator!() const

1 Returns true if failbit | badbit is set in state.

  27.1.3.1.11  basic_ios::copyfmt                     [lib.ios::copyfmt]
      basic_ios<charT,baggage>& copyfmt(const basic_ios<charT,baggage>& rhs);

1 Assigns to the  member  objects  of  *this  the  corresponding  member
  objects of rhs, except that:

  --sb and state are left unchanged;

  --except is altered last by calling exception(rhs.except).

  --The  contents of arrays pointed at by pword and iword are copied not
    the pointers themselves.6)
  _________________________

2 If any newly stored pointer values in *this point  at  objects  stored
  outside  the  object  rhs, and those objects are destroyed when rhs is
  destroyed, the newly stored pointer values are  altered  to  point  at
  newly constructed copies of the objects.

3 Returns *this.

  27.1.3.1.12  basic_ios::tie                             [lib.ios::tie]
      basic_ostream<charT,baggage>* tie() const;

1 Returns tiestr.
      basic_ostream<charT,baggage>* tie(basic_ostream<charT,baggage>* tiestr_arg);

2 Assigns  tiestr_arg  to  tiestr  and  then  returns the previous value
  stored in tiestr.

  27.1.3.1.13  basic_ios::rdbuf                         [lib.ios::rdbuf]
      basic_streambuf<charT,baggage>* rdbuf() const;

1 Returns sb.
      basic_streambuf<charT,baggage>* rdbuf(basic_streambuf<charT,baggage>* sb_arg);

2 Assigns sb_arg to sb, then calls clear().

  +-------                BEGIN BOX 25                -------+
  Note: need to modify so as  to  describe  the  occurence  of  imbueing
  loc::codecnv into the argument stream buffer.
  +-------                 END BOX 25                 -------+

3 Returns the previous value stored in sb.

  27.1.3.1.14  basic_ios::rdstate                     [lib.ios::rdstate]
      iostate rdstate() const;

1 Returns state.

  27.1.3.1.15  basic_ios::clear(iostate)      [lib.ios::clear.basic.ios]
      void clear(iostate state_arg = goodbit);

1 Assigns state_arg to state.  If sb is a  null  pointer,  the  function
  then  sets badbit in state.  If state & except is zero, returns.  Oth­
  erwise, the function throws an object  fail  of  class  failure,  con­
  structed with argument values that are implementation-defined.

  27.1.3.1.16                              [lib.ios::setstate.basic.ios]
       basic_ios::setstate(iostate)
      void setstate(iostate state_arg);

  _________________________
  6) This suggests an infinite amount of copying, but the implementation
  can  keep track of the maximum element of the arrays that is non-zero.

1 Calls clear(state | state_arg).

  27.1.3.1.17  basic_ios::good                           [lib.ios::good]
      bool good() const;

1 Returns true if state is zero.

  27.1.3.1.18  basic_ios::eof                             [lib.ios::eof]
      bool eof() const;

1 Returns true if eofbit is set in state.

  27.1.3.1.19  basic_ios::fail                           [lib.ios::fail]
      bool fail() const;

1 Returns true if failbit or badbit is set in state.7)

  27.1.3.1.20  basic_ios::bad                             [lib.ios::bad]
      bool bad() const;

1 Returns true if badbit is set in state.

  27.1.3.1.21  basic_ios::exceptions               [lib.ios::exceptions]
      iostate exceptions() const;

1 Returns except.
      void exceptions(iostate except_arg);

2 Assigns except_arg to except, then calls clear(state).

  27.1.3.1.22  basic_ios::flags                         [lib.ios::flags]
      fmtflags flags() const;

1 Returns fmtfl.
      fmtflags flags(fmtflags fmtfl_arg);

2 Assigns fmtfl_arg to fmtfl and then returns the previous value  stored
  in fmtfl.

  27.1.3.1.23  basic_ios::setf(fmtflags)                 [lib.ios::setf]
      fmtflags setf(fmtflags fmtfl_arg);

1 Sets  fmtfl_arg in fmtfl and then returns the previous value stored in
  fmtfl.
      fmtflags setf(fmtflags fmtfl_arg, fmtflags mask);

2 Clears mask in fmtfl, sets fmtfl_arg & mask in fmtfl, and then returns
  the previous value stored in fmtfl.

  _________________________
  7) Checking badbit also for fail() is historical practice.

  27.1.3.1.24  basic_ios::unsetf(fmtflags)             [lib.ios::unsetf]
      void unsetf(fmtflags mask);

1 Clears mask in fmtfl.

  27.1.3.1.25  basic_ios::fill                           [lib.ios::fill]
      int_type fill() const;

1 Returns fillch.
      int_type fill(int_type fillch_arg);

2 Assigns  fillch_arg  to  fillch  and  then  returns the previous value
  stored in fillch.

  27.1.3.1.26  basic_ios::precision                 [lib.ios::precision]
      int precision() const;

1 Returns prec.
      int precision(int prec_arg);

2 Assigns prec_arg to prec and then returns the previous value stored in
  prec.

  27.1.3.1.27  basic_ios::width                         [lib.ios::width]
      int width() const;

1 Returns wide.
      int width(int wide_arg);

2 Assigns wide_arg to wide and then returns the previous value stored in
  wide.

  27.1.3.1.28  basic_ios::imbue                         [lib.ios::imbue]
      locale imbue(const locale loc_arg);

1 Imbues the basic_ios with the locale object, loc.  In case the  member
  pointer  sb of the basic_streambuf<charT,ICB> has already initialized,
  the function also imbues the object pointed to by sb.

2 Assigns loc_arg to loc and then returns the previous value  stored  in
  loc.

  27.1.3.1.29  basic_ios::getloc                       [lib.ios::getloc]
      locale getloc() const;

1 Returns  the  classic "C" locale if no locale has been imbued.  Other­
  wise, returns loc.

  27.1.3.1.30  basic_ios::xalloc                       [lib.ios::xalloc]
      static int xalloc();

1 Returns index++.

  27.1.3.1.31  basic_ios::iword                         [lib.ios::iword]
      long& iword(int idx);

1 If  iarray is a null pointer, allocates an array of int of unspecified
  size and stores a pointer to its first element in iarray.   The  func­
  tion  then  extends  the  array  pointed  at by iarray as necessary to
  include the element iarray[idx].  Each newly allocated element of  the
  array is initialized to zero.

2 Returns  iarray[idx].   After  a subsequent call to iword(int) for the
  same object, the earlier return value may no longer be valid.8)

  27.1.3.1.32  basic_ios::pword                         [lib.ios::pword]
      void* & pword(int idx);

1 If parray is a null pointer, allocates an array of pointers to void of
  unspecified  size and stores a pointer to its first element in parray.
  The function then extends the array pointed at by parray as  necessary
  to  include  the element parray[idx].  Each newly allocated element of
  the array is initialized to a null pointer.

2 Returns parray[idx].  After a subsequent call to  pword(int)  for  the
  same object, the earlier return value may no longer be valid.

  27.1.3.1.33  basic_ios constructor                [lib.basic.ios.cons]
      basic_ios();

1 Constructs  an  object of class basic_ios, assigning initial values to
  its member objects by calling init(0).

  27.1.3.1.34  basic_ios::init                     [lib.basic.ios::init]
      void init(basic_streambuf<charT,baggage>* sb_arg);

1 The postconditions of this function are indicated in Table 8:

  _________________________
  8) An implementation is free  to  implement  both  the  integer  array
  pointed  at  by  iarray  and the pointer array pointed at by parray as
  sparse data structures, possibly with a one-element cache for each.

                          Table 8--init effects

                   +----------------------------------+
                   |Element            Value          |
                   +----------------------------------+
                   |sb        sb_arg                  |
                   |tiestr    a null pointer          |
                   |state     goodbit  if  sb_arg  is |
                   |          not   a  null  pointer, |
                   |          otherwise badbit.       |
                   |except    goodbit                 |
                   |fmtfl     skipws | dec            |
                   |wide      zero                    |
                   |prec      6                       |
                   |fillch    the space character     |
                   |loc       new   locale(),   which |
                   |          means the default value |
                   |          is the  current  global |
                   |          locale;9)               |
                   |iarray    a null pointer          |
                   |parray    a null pointer          |
                   +----------------------------------+

  +-------                BEGIN BOX 26                -------+
  Note:  the  default  locale  value shall be global but not transparent
  because the locality of the stream buffer will  be  unchanged  between
  its lifetime.
  +-------                 END BOX 26                 -------+

  27.1.3.2  Standard basic_ios manipulators          [lib.std.ios.manip]

  27.1.3.2.1  fmtflags manipulators                 [lib.fmtflags.manip]
      template<class charT, class baggage>
          basic_boolalpha<charT,baggage>& boolalpha(basic_ios<charT,baggage>& str);

1 Calls str.setf(basic_ios::boolalpha) and then returns str.10)
      template<class charT, class baggage>
          basic_ios<charT,baggage>& noboolalpha(basic_ios<charT,baggage>& str);

2 Calls str.unsetf(basic_ios::boolalpha) and then returns str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& showbase(basic_ios<charT,baggage>& str);

3 Calls str.setf(basic_ios::showbase) and then returns str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& noshowbase(basic_ios<charT,baggage>& str);
  _________________________
  9) Usually, locale::classic().

4 Calls str.unsetf(basic_ios::showbase) and then returns str.

  27.1.3.2.2  basic_showpoint                      [lib.basic.showpoint]
      template<class charT, class baggage>
          basic_ios<charT,baggage>& showpoint(basic_ios<charT,baggage>& str);

1 Calls str.setf(basic_ios::showpoint) and then returns str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& noshowpoint(basic_ios<charT,baggage>& str);

2 Calls str.unsetf(basic_ios::showpoint) and then returns str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& showpos(basic_ios<charT,baggage>& str);

3 Calls str.setf(basic_ios::showpos) and then returns str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& noshowpos(basic_ios<charT,baggage>& str);

4 Calls str.unsetf(basic_ios::showpos) and then returns str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& skipws(basic_ios<charT,baggage>& str);

5 Calls str.setf(basic_ios::skipws) and then returns str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& noskipws(basic_ios<charT,baggage>& str);

6 Calls str.unsetf(basic_ios::skipws) and then returns str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& uppercase(basic_ios<charT,baggage>& str);

7 Calls str.setf(basic_ios::uppercase) and then returns str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& nouppercase(basic_ios<charT,baggage>& str);

8 Calls str.unsetf(basic_ios::uppercase) and then returns str.

  27.1.3.2.3  adjustfield manipulators           [lib.adjustfield.manip]
      template<class charT, class baggage>
          basic_ios<charT,baggage>& internal(basic_ios<charT,baggage>& str);

1 Calls  str.setf(basic_ios::internal,  basic_ios::adjustfield) and then
  returns str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& left(basic_ios<charT,baggage>& str);

2 Calls  str.setf(basic_ios::left,  basic_ios::adjustfield)   and   then
  returns str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& right(basic_ios<charT,baggage>& str);

3 Calls   str.setf(basic_ios::right,  basic_ios::adjustfield)  and  then
  returns str.

  27.1.3.2.4  basefield manipulators               [lib.basefield.manip]
      template<class charT, class baggage>
          basic_ios<charT,baggage>& dec(basic_ios<charT,baggage>& str);

1 Calls str.setf(basic_ios::dec, basic_ios::basefield) and then  returns
  str.10)
      template<class charT, class baggage>
          basic_ios<charT,baggage>& hex(basic_ios<charT,baggage>& str);

2 Calls  str.setf(basic_ios::hex, basic_ios::basefield) and then returns
  str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& oct(basic_ios<charT,baggage>& str);

3 Calls str.setf(basic_ios::oct, basic_ios::basefield) and then  returns
  str.

  27.1.3.2.5  floatfield manipulators             [lib.floatfield.manip]
      template<class charT, class baggage>
          basic_ios<charT,baggage>& fixed(basic_ios<charT,baggage>& str);

1 Calls   str.setf(basic_ios::fixed,   basic_ios::floatfield)  and  then
  returns str.
      template<class charT, class baggage>
          basic_ios<charT,baggage>& scientific(basic_ios<charT,baggage>& str);

2 Calls str.setf(basic_ios::scientific, basic_ios::floatfield) and  then
  returns str.

  27.1.4  Standard iostream objects               [lib.iostream.objects]

1 The  header <iostream> declares four objects that associate objects of
  class basic_stdiobuf with the standard C streams provided for  by  the
  functions declared in <cstdio> (_lib.file.streams_).

  +-------                BEGIN BOX 27                -------+
  Jerry  Schwarz  proposal: Replace the following paragraph by: The four
  objects  are  constructed  and  associations  are  established  before
  dynamic initialization of file scope variables is begun.
  +-------                 END BOX 27                 -------+

  The  four  objects  are  constructed,  and the associations are estab­
  lished,     the     first     time     an     object     of      class
  basic_ios<charT,baggage>::Init  is  constructed.  The four objects are
  not destroyed during program execution.11)
  _________________________
  10)  The  function  signature  dec(basic_ios<charT,baggage>&)  can  be
  called     by     the      function      signature      basic_ostream&
  stream::operator<<(basic_ostream&  (*)(basic_ostream&))  to permit ex­
  pressions of the form cout << dec to change the format flags stored in
  cout.
  11) Constructors and destructors for static objects can  access  these
  objects  to read input from stdin or write output to stdout or stderr.

  +-------                BEGIN BOX 28                -------+
  Note: Need to determine whether we treat cin, cout, cerr, and clog  as
  wide-oriented  or  not.  We can allow to change narrow-wide if only no
  I/O operations occurs.  So the default  is  wide-oriented  and  easily
  modify narrow-oriented?  -- mjv
  +-------                 END BOX 28                 -------+

  +-------                BEGIN BOX 29                -------+
  They can't be wide-oriented.  They have the wrong type. -- jss
  +-------                 END BOX 29                 -------+

  +-------                BEGIN BOX 30                -------+
  Jerry Schwarz proposal: Add wcin, wcout, werr and wclog.
  +-------                 END BOX 30                 -------+

  +-------                BEGIN BOX 31                -------+
  Jerry  Schwarz proposal: Except as noted below the state of the format
  state of the iostream objects  after  initialization  is  the  default
  state established by ios::init().
  +-------                 END BOX 31                 -------+

  27.1.4.1  Object cin                                         [lib.cin]
      istream cin;

1 The object cin controls input from an unbuffered stream buffer associ­
  ated with the object stdin, declared in <cstdio>.

2 After the object cin is initialized, cin.tie() returns cout.

  27.1.4.2  Object cout                                       [lib.cout]
      ostream cout;

1 The object cout controls output to an unbuffered stream buffer associ­
  ated    with    the    object    stdout,    declared    in    <cstdio>
  (_lib.file.streams_).

  27.1.4.3  Object cerr                                       [lib.cerr]
      ostream cerr;

1 The object cerr controls output to an unbuffered stream buffer associ­
  ated    with    the    object    stderr,    declared    in    <cstdio>
  (_lib.file.streams_).

2 After the object  cerr  is  initialized,  cerr.flags()  &  unitbuf  is
  nonzero.

  27.1.4.4  Object clog                                       [lib.clog]
      ostream clog;

1 The object clog controls output to a stream buffer associated with the
  object stderr, declared in <cstdio> (_lib.file.streams_).

  +-------                BEGIN BOX 32                -------+
  I think this is overspecification.  The destination of clog  ought  to
  be implementation defined.  --jss
  +-------                 END BOX 32                 -------+

  27.2  Default stream buffers and streams       [lib.default.iostreams]

1 Headers:

  --<streambuf>

  --<istream>

  --<ostream>

2 Table 9:

                   Table 9--Header <streambuf> synopsis

        +--------------------------------------------------------+
        |          Type                       Name(s)            |
        +--------------------------------------------------------+
        |Type:                      streamoff                    |
        +--------------------------------------------------------+
        |Template class:            basic_streambuf              |
        +--------------------------------------------------------+
        |Classes:                                                |
        |basic_streambuf<char>      streambuf         wstreambuf |
        |basic_streambuf<wchar_t>   streampos         wstreampos |
        +--------------------------------------------------------+

3 Table 10:

                   Table 10--Header <istream> synopsis

  +-----------------------------------------------------------------------+
  |       Type                               Name(s)                      |
  +-----------------------------------------------------------------------+
  |Template classes:                                                      |
  |basic_istream                         istreambuf_iterator              |
  +-----------------------------------------------------------------------+
  |Template operators:                                                    |
  |operator!= (istreambuf_iterator)      operator== (istreambuf_iterator) |
  +-----------------------------------------------------------------------+
  |Template functions:                                                    |
  |basic_ws                              value_type (istreambuf_iterator) |
  |distance_type (istreambuf_iterator)                                    |
  |iterator_category (istreambuf_iter)                                    |
  +-----------------------------------------------------------------------+
  |Classes:                                                               |
  |basic_istream<char>                                 istream            |
  |basic_istream<wchar_t>                              wistream           |
  +-----------------------------------------------------------------------+
  |Function:             ws                                               |
  +-----------------------------------------------------------------------+

4 Table 11:

                   Table 11--Header <ostream> synopsis

  +-----------------------------------------------------------------------+
  |      Type                               Name(s)                       |
  +-----------------------------------------------------------------------+
  |Template classes:                                                      |
  |basic_ostream                      ostreambuf_iterator                 |
  +-----------------------------------------------------------------------+
  |Template operators:                                                    |
  |operator!= (ostreambuf_iterator)   operator== (ostreambuf_iterator)    |
  +-----------------------------------------------------------------------+
  |Template functions:                                                    |
  |basic_ends                         value_type (ostreambuf_iterator)    |
  |basic_flush                        iterator_category (ostreambuf_iter) |
  +-----------------------------------------------------------------------+
  |Classes:                                                               |
  |basic_ostream<char>                ostream                             |
  |basic_ostream<wchar_t>             wostream                            |
  +-----------------------------------------------------------------------+
  |Functions:          endl           ends              flush             |
  +-----------------------------------------------------------------------+

  27.2.1  Stream buffers                            [lib.stream.buffers]

1 The  header <streambuf> defines types that control input from and out­
  put to character sequences.

  27.2.1.1  Stream buffer requirements             [lib.streambuf.reqts]

1 The following templates defined in the header <streambuf> have already
  been specified in subclause _lib.ios.baggage_:
      template class ios_baggage,
      template class ios_char_baggage,
      template class ios_pos_baggage;

2 The  following  defined  in  the  header <streambuf> have already been
  specified      in      subclauses      _lib.ios.char.baggage_      and
  _lib.ios.pos.baggage_:
      class ios_char_baggage<char>,
      class ios_char_baggage<wchar_t>,
      class ios_pos_baggage<streampos>,
      class ios_pos_baggage<wstreampos>,
      Type streamoff,
      Type streampos,
      Type wstreamoff,
      Class wstreampos.

  27.2.1.2  Template class                               [lib.streambuf]
       basic_streambuf<charT,baggage>
  template<class charT, class baggage = ios_baggage<charT> >
  class basic_streambuf {
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;

  +-------                BEGIN BOX 33                -------+
  In order to simplify descriptions and as a  convenience  for  program­
  mers.

1 Jerry Schwarz proposal:
      typedef basic_ios<char> ios;
  and  use  of  the defined type as appropriate elsewhere in the working
  paper.
  +-------                 END BOX 33                 -------+

      int_type  eof()     { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }

  public:
      virtual ~basic_streambuf();
      pos_type pubseekoff(off_type off,
                          basic_ios<charT,baggage>::seekdir way,
                          basic_ios<charT,baggage>::openmode which
                              = basic_ios<charT,baggage>::in
                              | basic_ios<charT,baggage>::out);
      pos_type pubseekpos(pos_type sp,
                          basic_ios<charT,baggage>::openmode which
                              = basic_ios<charT,baggage>::in
                              | basic_ios<charT,baggage>::out);
      basic_streambuf<char_type,baggage>*
               pubsetbuf(char_type* s, streamsize n);

  +-------                BEGIN BOX 34                -------+
  The following was not part of the proposal.  Should we keep it? -- mjv
  +-------                 END BOX 34                 -------+

  +-------                BEGIN BOX 35                -------+
  Yes.   I  believe this was an inadvertant omission due to the proposal
  being based on a draft that did not contain in_avail. -- jss.
  +-------                 END BOX 35                 -------+

      int      in_avail();
      int      pubsync();
      int_type sbumpc();
      int_type sgetc();
      int      sgetn(char_type* s, streamsize n);
      int_type snextc();
      int_type sputbackc(char_type c);

  +-------                BEGIN BOX 36                -------+
  The following two were not part of the proposal.  Should we keep them?
  -- mjv
  +-------                 END BOX 36                 -------+

  +-------                BEGIN BOX 37                -------+
  Yes.   I  believe this was an inadvertant omission due to the proposal
  being based on a draft that did not contain  sungetc .  -- jss.
  +-------                 END BOX 37                 -------+

      int      sungetc();
      int      sputc(int c);
      int_type sputn(const char_type* s, streamsize n);

  protected:
      basic_streambuf();
      char_type* eback() const;
      char_type* gptr() const;
      char_type* egptr() const;
      void       gbump(int n);
      void       setg(char_type* gbeg_arg,
                      char_type* gnext_arg,
                      char_type* gend_arg);
      char_type* pbase() const;
      char_type* pptr() const;
      char_type* epptr() const;
      void       pbump(int n);
      void       setp(char_type* pbeg_arg,
                      char_type* pend_arg);
      virtual int_type overflow (int_type c = eof());
      virtual int_type pbackfail(int_type c = eof());

  +-------                BEGIN BOX 38                -------+
  The following was not part of the proposal.  Should we  keep  it?   --
  mjv
  +-------                 END BOX 38                 -------+

  +-------                BEGIN BOX 39                -------+
  Yes. It is the public interface to in_avail.  -- jss
  +-------                 END BOX 39                 -------+

      virtual int      showmany();
      virtual int_type underflow();
      virtual int_type uflow();
      virtual streamsize xsgetn(char_type* s, streamsize n);
      virtual streamsize xsputn(const char_type* s, streamsize n);
      virtual pos_type seekoff(off_type off,
              basic_ios<charT,baggage>::seekdir way,
              basic_ios<charT,baggage>::openmode which = in | out);
      virtual pos_type seekpos(pos_type sp,
              basic_ios<charT,baggage>::openmode which = in | out);
      virtual basic_streambuf<char_type,baggage>*
                setbuf(char_type* s, streamsize n);
      virtual int sync();

  +-------                BEGIN BOX 40                -------+
  The  following two member functions are introduced to support raw byte
  I/O, whose behaviors are implementation-defined.
  +-------                 END BOX 40                 -------+

  +-------                BEGIN BOX 41                -------+
  Private discussions in Kitchener concluded that these functions cannot
  be  implemented  in  any  generic fashion and that their usefulness is
  doubtful.

2 Jerry  Schwarz  proposal:  Remove  write_byte  and  read_byte here and
  throughout the working paper.
  +-------                 END BOX 41                 -------+

      virtual streamsize write_byte(const char* buf, streamsize len);
      virtual streamsize read_byte (char* buf, streamsize len);
      private:
  //  char_type* gbeg;    exposition only
  //  char_type* gnext;   exposition only
  //  char_type* gend;    exposition only
  //  char_type* pbeg;    exposition only
  //  char_type* pnext;   exposition only
  //  char_type* pend;    exposition only
      };
      class streambuf : public basic_streambuf<char> {};
      class wstreambuf : public basic_streambuf<wchar_t> {};

3 The  class  template  basic_streambuf<charT,baggage>  serves   as   an
  abstract  base class for deriving various stream buffers whose objects
  each control two character sequences:

  --a character input sequence;

  --a character output sequence.

4 The  class  streambuf  is  an  instantiation  of  the  template  class
  basic_streambuf specialized by the type char.

5 The  class  wstreambuf  is  an  instantiation  of  the  template class
  basic_streambuf specialized by the type wchar_t.

6 Stream buffers can impose various constraints on  the  sequences  they
  control.  Some constraints are:

  --The controlled input sequence can be not readable.

  --The controlled output sequence can be not writable.

  --The  controlled  sequences  can  be  associated with the contents of
    other representations for  character  sequences,  such  as  external
    files.

  --The  controlled sequences can support operations directly to or from
    associated sequences.

  --The controlled sequences can impose limitations on how  the  program
    can read characters from a sequence, write characters to a sequence,
    put characters back into an input  sequence,  or  alter  the  stream
    position.

7 Each  sequence  is characterized by three pointers which, if non-null,
  all point into the same charT array object.  The array  object  repre­
  sents, at any moment, a (sub)sequence of characters from the sequence.
  Operations performed on a sequence alter the values  stored  in  these

  pointers,  perform  reads  and  writes  directly to or from associated
  sequences, and alter "the stream position"  and  conversion  state  as
  needed  to maintain this subsequence relationship.  The three pointers
  are:

  --the beginning pointer,  or  lowest  element  address  in  the  array
    (called xbeg here);

  --the  next  pointer, or next element address that is a current candi­
    date for reading or writing (called xnext here);

  --the end pointer, or first element address  beyond  the  end  of  the
    array (called xend here).

8 The  following  semantic constraints shall always apply for any set of
  three pointers for a sequence, using the pointer names  given  immedi­
  ately above:

  --If  xnext  is  not  a null pointer, then xbeg and xend shall also be
    non-null pointers into the same charT array, as described above.

  --If xnext is not a null pointer  and  xnext  <  xend  for  an  output
    sequence,  then a write position is available.  In this case, *xnext
    shall be assignable as the next element to  write  (to  put,  or  to
    store a character value, into the sequence).

  --If  xnext  is  not  a  null  pointer  and  xbeg < xnext for an input
    sequence, then a putback  position  is  available.   In  this  case,
    xnext[-1]  shall  have  a  defined value and is the next (preceding)
    element to store a  character  that  is  put  back  into  the  input
    sequence.

  --If  xnext  is  not  a  null  pointer  and  xnext < xend for an input
    sequence, then a read position is available.  In this  case,  *xnext
    shall  have a defined value and is the next element to read (to get,
    or to obtain a character value, from the sequence).

9 For the sake of exposition, the maintained data is presented here as:

  --char_type* gbeg, the beginning pointer for the input sequence;

  --char_type* gnext, the next pointer for the input sequence;

  --char_type* gend, the end pointer for the input sequence;

  --char_type* pbeg, the beginning pointer for the output sequence;

  --char_type* pnext, the next pointer for the output sequence;

  --char_type* pend, the end pointer for the output sequence.

  27.2.1.2.1  basic_streambuf destructor       [lib.basic.streambuf.des]
      virtual ~basic_streambuf();

1 Destroys an object of class basic_streambuf.

  27.2.1.2.2                                 [lib.streambuf::pubseekoff]
       basic_streambuf::pubseekoff
      pos_type pubseekoff(off_type off,
          basic_ios<charT,baggage>::seekdir way,
          basic_ios<charT,baggage>::openmode which
              = basic_ios<charT,baggage>::in | basic_ios<charT,baggage>::out);

1 Returns seekoff(off, way, which).

  27.2.1.2.3                                 [lib.streambuf::pubseekpos]
       basic_streambuf::pubseekpos
      pos_type pubseekpos(pos_type sp,
          basic_ios<charT,baggage>::openmode which
              = basic_ios<charT,baggage>::in | basic_ios<charT,baggage>::out);

1 Returns seekpos(sp, which).

  27.2.1.2.4  basic_streambuf::pubsetbuf      [lib.streambuf::pubsetbuf]
      basic_streambuf<char_type,baggage>*
          pubsetbuf(char_type* s, streamsize n);

1 Returns setbuf(s, n).

  +-------                BEGIN BOX 42                -------+
  The following was not part of the proposal.  Should we keep it?
  +-------                 END BOX 42                 -------+

  27.2.1.2.5  basic_streambuf::in_avail        [lib.streambuf::in.avail]
      int in_avail();

1 If the input sequence does not have a read position available, returns
  showmany().  Otherwise, returns gend - gnext.

  27.2.1.2.6  basic_streambuf::pubsync          [lib.streambuf::pubsync]
      int pubsync();

1 Returns sync().

  27.2.1.2.7  basic_streambuf::sbumpc            [lib.streambuf::sbumpc]
      int_type sbumpc();

1 If the input sequence does not have a read position available, returns
  uflow().  Otherwise, returns (char_type)*gnext++.

  27.2.1.2.8  basic_streambuf::sgetc              [lib.streambuf::sgetc]
      int_type sgetc();

1 If the input sequence does not have a read position available, returns
  underflow().  Otherwise, returns (char_type)*gnext.

  27.2.1.2.9  basic_streambuf::sgetn              [lib.streambuf::sgetn]
      int sgetn(char_type* s, streamsize n);

1 Returns xsgetn(s, n).

  27.2.1.2.10  basic_streambuf::snextc           [lib.streambuf::snextc]
      int_type snextc();

1 Calls  sbumpc()  and,  if  that function returns eof(), returns eof().
  Otherwise, returns sgetc().

  +-------                BEGIN BOX 43                -------+
  Note: baggage::eos() ... the definition of EOF
  +-------                 END BOX 43                 -------+

  27.2.1.2.11                                 [lib.streambuf::sputbackc]
       basic_streambuf::sputbackc
      int_type sputbackc(char_type c);

1 If  the  input sequence does not have a putback position available, or
  if  c  !=  gnext[-1],  returns   pbackfail(c).    Otherwise,   returns
  (char_type)*--gnext.

  +-------                BEGIN BOX 44                -------+
  The following was not part of the proposal.  Should we keep it?
  +-------                 END BOX 44                 -------+

  27.2.1.2.12  basic_streambuf::sungetc         [lib.streambuf::sungetc]
      int sungetc();

1 If  the  input  sequence  does  not have a putback position available,
  returns pbackfail().  Otherwise, returns (char_type)*--gnext.

  +-------                BEGIN BOX 45                -------+
  The following was not part of the proposal.  Should we keep it?  --mjv
  +-------                 END BOX 45                 -------+

  +-------                BEGIN BOX 46                -------+
  Absolutely sputc is a fundamental member of the interface -- jss
  +-------                 END BOX 46                 -------+

  27.2.1.2.13  basic_streambuf::sputc             [lib.streambuf::sputc]
      int sputc(int c);

1 If  the  output  sequence  does  not  have a write position available,
  returns overflow(c).  Otherwise, returns (*pnext++ = c).

  27.2.1.2.14  basic_streambuf::sputn             [lib.streambuf::sputn]
      int_type sputn(const char_type* s, streamsize n);

1 Returns xsputn(s, n).

  27.2.1.2.15  basic_streambuf                [lib.basic.streambuf.cons]
       constructor
      basic_streambuf();

1 Constructs  an object of class basic_streambuf<charT,baggage> and ini­
  tializes: 12)

  --all its pointer member objects to null pointers,

  --the loc member object to the return value of locale::global().

  +-------                BEGIN BOX 47                -------+
  Once the loc member is initialized its locale-dependent behavior  does
  not change until the next imbueing of the locale.
  +-------                 END BOX 47                 -------+

  27.2.1.2.16  basic_streambuf::eback             [lib.streambuf::eback]
      char_type* eback() const;

1 Returns gbeg.

  27.2.1.2.17  basic_streambuf::gptr               [lib.streambuf::gptr]
      char_type* gptr() const;

1 Returns gnext.

  27.2.1.2.18  basic_streambuf::egptr             [lib.streambuf::egptr]
      char_type* egptr() const;

1 Returns gend.

  27.2.1.2.19  basic_streambuf::gbump             [lib.streambuf::gbump]
      void gbump(int n);

1 Assigns gnext + n to gnext.

  _________________________
  12) The default constructor is protected for class basic_streambuf  to
  assure  that  only  objects for classes derived from this class may be
  constructed.

  27.2.1.2.20  basic_streambuf::setg               [lib.streambuf::setg]
      void setg(char_type* gbeg_arg,
          char_type* gnext_arg,
          char_type* gend_arg);

1 Assigns gbeg_arg to gbeg, gnext_arg to gnext, and gend_arg to gend.

  27.2.1.2.21  basic_streambuf::pbase             [lib.streambuf::pbase]
      char_type* pbase() const;

1 Returns pbeg.

  27.2.1.2.22  basic_streambuf::pptr               [lib.streambuf::pptr]
      char_type* pptr() const;

1 Returns pnext.

  27.2.1.2.23  basic_streambuf::epptr             [lib.streambuf::epptr]
      char_type* epptr() const;

1 Returns pend.

  27.2.1.2.24  basic_streambuf::pbump             [lib.streambuf::pbump]
      void pbump(int n);

1 Assigns pnext + n to pnext.

  27.2.1.2.25  basic_streambuf::setp               [lib.streambuf::setp]
      void setp(char_type* pbeg_arg, char_type* pend_arg);

1 Assigns pbeg_arg to pbeg, pbeg_arg to pnext, and pend_arg to pend.

  27.2.1.2.26  basic_streambuf::overflow       [lib.streambuf::overflow]
      virtual int_type overflow(int_type c = eof());

1 Consumes  some  initial  subsequence  of the characters of the pending
  sequence.  The pending sequence is defined as the concatenation of

  a)if pbeg is NULL then the empty  sequence  otherwise,  pnext  -  pbeg
    characters beginning at pbeg.

  b)if  c  == eof() then the empty sequence otherwise, the sequence con­
    sisting of c.

2 The member functions sputc and sputn call this function in  case  that
  no  room can be found in the put buffer enough to accomodate the argu­
  ment character sequence.

3 Every overiding definition of this virtual  function  shall  obey  the
  following constraints:

  1)The  effect  of  consuming  a  character  on  the  associated output
    sequence is specified13)
  _________________________

  2)Let r be the number of characters in the pending sequence  not  con­
    sumed.  If r  is non-zerof then pbeg and pnext must be set so that:
            pnext - pbeg == r
    and  the  r  characters  starting  at pbeg are the associated output
    stream.  In case r  is zero (all characters of the pending  sequence
    have  been  consumed)  then  either pbeg is set to NULL, or pbeg and
    pnext are both set to the same non-NULL value.

  3)The function may fail if either  appending  some  character  to  the
    associated  output stream fails or if it is unable to establish pbeg
    and pnext according to the above rules.

4 Returns eof() or throws an exception if the function fails.

5 Otherwise, returns some value other than eof()14) to indicate success.

6 Default behavior: returns eof().

  +-------                BEGIN BOX 48                -------+
  Should be pure virtual. -- mjv
  +-------                 END BOX 48                 -------+

  +-------                BEGIN BOX 49                -------+
  I  disagree.  Accidental attempts to create a streambuf are eliminated
  by making the constructors protected.  By giving  definitions  to  all
  the  virtuals  in  streambuf  we make it possible to derive from it by
  only supplying definitions for the  virtuals  that  are  needed.   For
  example,  you  do  not  have to define overflow in a streambuf that is
  only intended for input.  I have a similar response to all  the  other
  places  where  there  is  a box asking this question although IUm only
  making this response in one place.  -- jss
  +-------                 END BOX 49                 -------+

  27.2.1.2.27                                 [lib.streambuf::pbackfail]
       basic_streambuf::pbackfail
      virtual int_type pbackfail(int c = eof());

  +-------                BEGIN BOX 50                -------+
  Check vs. _lib.basic.filebuf::pbackfail_
  +-------                 END BOX 50                 -------+

  +-------                BEGIN BOX 51                -------+
  Jerry Schwarz proposal: Replace this section by the following and make
  corresponding changes to  descriptions  of  the  overriding  functions
  _________________________
  13)  That  is,  for  each  class  derived  from  an  instance  of  ba­
  sic_streambuf in this clause, a specification of how consume a charac­
  ter effects the associated output sequence is given.  There is no  re­
  quirement on a user defined class.
  14) Typically, c.

  defined elsewhere in the working paper.

1 The  public  functions  of basic_streambuf call this virtual only when
  gnext is null, gnext==gbeg or *gnext!=c.  Other calls shall also  sat­
  isfy that constraint.

2 The    pending    sequence   is   defined   as   for   underflow   (in
  _lib.streambuf::underflow_) with the modifications that

  --If c==eof() then the input  sequence  is  backed  up  one  character
    before the pending sequence is determined.

  --If  c!=eof()  then  c  is  prepended.  Whether the input sequence is
    backed up or modified in any other way is unspecified.

3 On return, the constraints of gnext, gbeg, and pnext are the  same  as
  for underflow (in _lib.streambuf::underflow_)

4 Returns  eof()  to  indicate  failure.   Failure may occur because the
  input sequence could not be backed up, or if for some other reason the
  pointers could not be set consistent with the constraints.

5 Returns some value other than eof() to indicate success.

6 Default behavior: returns  eof()
  +-------                 END BOX 51                 -------+

7 Puts back the character designated by c to the input sequence, if pos­
  sible, in one of five ways:

  --If c != eof(), if either the input sequence has a  putback  position
    available or the function makes a putback position available, and if
    (charT)c == (charT)gnext[-1], assigns gnext - 1 to gnext.

    Returns (char_type)c.

  --If c != eof(), if either the input sequence has a  putback  position
    available or the function makes a putback position available, and if
    the function is permitted to assign to the putback position, assigns
    c to *--gnext.

    Returns (char_type)c.

  --If c != eof(), if no putback position is available, and if the func­
    tion can put back a  character  directly  to  the  associated  input
    sequence, puts back c directly to the associated input sequence.

    Returns (char_type)c.

  --If  c  == eof() and if either the input sequence has a putback posi­
    tion available or the function makes a putback  position  available,
    assigns gnext - 1 to gnext.

    Returns (char_type)c.

  --If  c == eof(), if no putback position is available, if the function
    can put back a character directly to the associated input  sequence,
    and if the function can determine the character x immediately before
    the current position in the associated input sequence, puts  back  x
    directly to the associated input sequence.

    Returns a value other than eof().

8 Returns eof() to indicate failure.

9 Default behavior:  returns eof().

  +-------                BEGIN BOX 52                -------+
  Should be pure virtual.
  +-------                 END BOX 52                 -------+

10Notes:

11If  the  function  can  succeed  in more than one of these ways, it is
  unspecified which way is chosen.  The function can alter the number of
  putback positions available as a result of any call.  How (or whether)
  the function makes a putback position available, puts back a character
  directly  to  the  input sequence, or determines the character immedi­
  ately before the current position in the associated input sequence  is
  defined separately for each class derived from basic_streambuf in this
  clause.

  +-------                BEGIN BOX 53                -------+
  The following was not part of the proposal.  Should we keep it?
  +-------                 END BOX 53                 -------+

  27.2.1.2.28                                  [lib.streambuf::showmany]
       basic_streambuf::showmany15)
      virtual int showmany();

1 Returns  a  count  of  the guaranteed number of characters that can be
  read from the input sequence before a call to uflow()  or  underflow()
  returns  eof().   A  positive  return value of indicates that the next
  such call will not return eof().16)

2 Default behavior:  returns zero.

  _________________________
  15) The morphemes of showmany are "es-how-manyS, not "show-many".
  16) The next such call might fail by throwing an exception.   The  in­
  tention is that the next call will return ``immediately.''

  27.2.1.2.29                                 [lib.streambuf::underflow]
       basic_streambuf::underflow
      virtual int_type underflow();

1 The  public members of basic_streambuf call this virtual only if gnext
  is null or gnext >= gend

2 Returns the first character of  the  pending  sequence,  if  possible,
  without  moving  the  input sequence position past it.  If the pending
  sequence is null then the function fails.

3 The pending sequence of characters is defined as the concatenation of:

  a)If  gnext  is non-NULL, then the gend - gnext characters starting at
    gnext, otherwise the empty sequence.

  b)Some sequence (possibly empty) of characters  read  from  the  input
    sequence.

4 The result character is

  a)If  the  pending  sequence  is non-empty, the first character of the
    sequence.

  b)If the pending sequence empty then the next character that would  be
    read from the input sequence.

5 The backup sequence is defined as the concatenation of:

  a)If gbeg is null then empty,

  b)Otherwise the gnext - gbeg characters beginning at gbeg.

6 The function sets up the gnext and gend satisfying one of:

  a)If  the  pending  sequence is non-empty, gend is non-null and gend -
    gnext characters starting at gnext are the characters in the pending
    sequence

  b)If  the pending sequence is empty, either gnext is null or gnext and
    gend are set to the same non-NULL pointer.

7 If gbeg and gnext are non-null then the function is not constrained as
  to their contents, but the ``usual backup condition'' is that either:

  a)If  the  backup  sequence contains at least gnext - gbeg characters,
    then the gnext - gbeg characters starting at  gbeg  agree  with  the
    last gnext - gbeg characters of the backup sequence.

  b)Or  the  n  characters  starting  at gnext - n agree with the backup
    sequence (where n is the length of the backup sequence)

8 Returns eof() to indicate failure.

9 Default behavior:  returns eof().

  +-------                BEGIN BOX 54                -------+
  Should be pure virtual.
  +-------                 END BOX 54                 -------+

  27.2.1.2.30  basic_streambuf::uflow             [lib.streambuf::uflow]
      virtual int_type uflow();

1 The    constraints    are    the     same     as     for     underflow
  (_lib.streambuf::underflow_)  except  that  the  result  character  is
  transfered from the pending sequence to the backup sequence,  and  the
  pending sequence may not be empty before the transfer.

2 Default behavior: Calls underflow(eof()).  If underflow returns eof(),
  returns eof().  Otherwise, do gbump(-1) and returns (char_type)*gnext.

  +-------                BEGIN BOX 55                -------+
  Jerry Schwarz proposal: Returns not_eof(c).
  +-------                 END BOX 55                 -------+

  27.2.1.2.31  basic_streambuf::xsgetn           [lib.streambuf::xsgetn]
      virtual streamsize xsgetn(char_type* s, streamsize n);

1 Assigns  up  to n characters to successive elements of the array whose
  first element is designated by s.  The characters  assigned  are  read
  from  the input sequence as if by repeated calls to sbumpc().  Assign­
  ing stops when either n characters have been assigned  or  a  call  to
  sbumpc() would return eof().

2 Returns the number of characters assigned.17)

  27.2.1.2.32  basic_streambuf::xsputn           [lib.streambuf::xsputn]
      virtual streamsize xsputn(const char_type* s, streamsize n);

1 Writes  up  to  n  characters to the output sequence as if by repeated
  calls to sputc(c).  The characters written are obtained  from  succes­
  sive  elements  of  the  array whose first element is designated by s.
  Writing stops when either n characters have been written or a call  to
  sputc(c) would return eof().

2 Returns the number of characters written.

  _________________________
  17)  Classes  derived  from basic_streambuf can provide more efficient
  ways to implement xsgetn and xsputn by overriding these definitions in
  the base class.

  27.2.1.2.33  basic_streambuf::seekoff         [lib.streambuf::seekoff]
      virtual pos_type seekoff(off_type off,
          basic_ios<charT,baggage>::seekdir way,
          basic_ios<charT,baggage>::openmode which
              = basic_ios<charT,baggage>::in | basic_ios<charT,baggage>::out);

1 Alters  the  stream  positions  within  one  or more of the controlled
  sequences in a way that is defined separately for each  class  derived
  from basic_streambuf in this clause.

2 Default  behavior:  returns an object of class pos_type that stores an
  invalid stream position.

  +-------                BEGIN BOX 56                -------+
  Should be pure virtual.
  +-------                 END BOX 56                 -------+

  27.2.1.2.34  basic_streambuf::seekpos         [lib.streambuf::seekpos]
      virtual pos_type seekpos(pos_type sp,
          basic_ios<charT,baggage>::openmode which = in | out);

1 Alters the stream positions within  one  or  more  of  the  controlled
  sequences  in  a way that is defined separately for each class derived
  from basic_streambuf in this clause.

2 Default behavior: returns an object of class pos_type that  stores  an
  invalid stream position.

  +-------                BEGIN BOX 57                -------+
  Should be pure virtual.
  +-------                 END BOX 57                 -------+

  27.2.1.2.35  basic_streambuf::setbuf           [lib.streambuf::setbuf]
      virtual basic_streambuf*
          setbuf(char_type* s, streamsize n);

1 Performs  an  operation  that  is  defined  separately  for each class
  derived from basic_streambuf in this clause.

  +-------                BEGIN BOX 58                -------+
  Should be pure virtual.
  +-------                 END BOX 58                 -------+

2 Default behavior:  returns this.

  27.2.1.2.36  basic_streambuf::sync               [lib.streambuf::sync]
      virtual int sync();

1 Synchronizes the controlled sequences with the arrays.   That  is,  if
  pbeg  is non-null the characters between pbeg and pnext are written to
  the controlled sequence, and  if  gnext  is  non-null  the  characters

  between gnext and gend are restored to the input sequence.  The point­
  ers may then be reset as appropriate.

2 Returns -1 on failure.  What constitutes failure is determined by each
  derived class.

3 Default behavior:  returns zero.

  27.2.1.2.37                                 [lib.streambuf::read.byte]
       basic_streambuf::read_byte

  +-------                BEGIN BOX 59                -------+
  Jerry  Schwarz  proposal:  Delete  read_byte.   It cannot be given any
  generic definition.
  +-------                 END BOX 59                 -------+

      streamsize read_byte(char* s, streamsize n);

  Assigns up to n bytes to successive elements of an array  whose  first
  element  is  designated by s.  How the characters written are obtained
  is the implementation-defined.  Assigning stops when either n  charac­
  ters have been assigned or end-of-file occurs on the input sequence.

1 Returns the number of characters assigned.

  +-------                BEGIN BOX 60                -------+
  The reason that the behavior of read_byte is unspecified (or implemen­
  tation-defined) is because we cannot assume the nature of the external
  source/sink  stream.   If  the  external  source/sink stream is a byte
  stream, we have a chance to specify more clear description  about  the
  behavior.   However, there is no insurance that the external stream be
  a byte sequence.  In case the stream is a wide character stream.   How
  we  should  convert  it  to a byte sequence, use ``narrow'' functions,
  every wide character breaks an element of bytes, or converted  into  a
  multibyte  character  sequence?   Because  even library users can cus­
  tomize the C++ iostream, any kind of external source/sink  stream  may
  be  applied  and  any  kind of conversion will be challenged.  So, the
  Standard should not provide any specification about the nature of  the
  conversion.
  +-------                 END BOX 60                 -------+

  27.2.1.2.38                                [lib.streambuf::write.byte]
       basic_streambuf::write_byte

  +-------                BEGIN BOX 61                -------+
  Jerry Schwarz proposal: Delete write_byte.  It  cannot  be  given  any
  generic definition.
  +-------                 END BOX 61                 -------+

      streamsize write_byte(const char* s, streamsize n);

1 Writes  up  to n bytes to the output sequences.  The bytes written are
  obtained from successive elements of the array whose first element  is

  designated  by s.  How the bytes written are converted to the external
  source/sink stream  is  implementation-defined.   Writing  stops  when
  either n characters have been written or a write fails.

2 Returns the number of characters written.

  27.2.2  Input streams                              [lib.input.streams]

1 The header <istream> defines a type and a function signature that con­
  trol input from a stream buffer.

  27.2.2.1  Template class basic_istream                   [lib.istream]
  template <class charT, class baggage = ios_baggage<charT> >
  class basic_istream : virtual public basic_ios<charT,baggage> {
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;
      int_type  eof()     { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }
  private:
  // for abbreviation:
      typedef basic_istream<char_type,baggage> istream_type;
      typedef basic_ios<charT,baggage> ios_type;
  public:
      basic_istream(basic_streambuf<charT,baggage>* sb);
      virtual ~basic_istream();
      bool ipfx(bool noskipws = 0);
      void isfx();
      istream_type& operator>>(istream_type& (*pf)(istream_type&))
      istream_type& operator>>(ios_type& (*pf)(ios_type&))
      istream_type& operator>>(char_type* s);

  +-------                BEGIN BOX 62                -------+
  The following two were not part of the proposal.  Should we keep them?
  -- mjv
  +-------                 END BOX 62                 -------+

  +-------                BEGIN BOX 63                -------+
  They cannot be kept because their types are not legal.  You can't make
  an arbitrary char_type signed or unsigned.  However they are very much
  a  part  of  the  current  iostream  interface, and I suspect are used
  extensively, so they must be supported.  The only way  I  can  see  to
  deal  with this is to make basic_iostream<char> a specialization.  I'm
  not making this an "Jerry Schwarz proposal" because I am not convinced
  that this is the best solution.  -- jss
  +-------                 END BOX 63                 -------+

      istream_type& operator>>(unsigned char_type* s)
      istream_type& operator>>(signed char_type* s);
      istream_type& operator>>(char_type& c);

  +-------                BEGIN BOX 64                -------+
  The following two were not part of the proposal.  Should we keep them?
  -- mjv
  +-------                 END BOX 64                 -------+

  +-------                BEGIN BOX 65                -------+
  The same considerations as applied to operator>> apply here.  -- jss
  +-------                 END BOX 65                 -------+

      istream_type& operator>>(unsigned char_type& c)
      istream_type& operator>>(signed char_type& c)
      istream_type& operator>>(bool& n);
      istream_type& operator>>(short& n);
      istream_type& operator>>(unsigned short& n);
      istream_type& operator>>(int& n);
      istream_type& operator>>(unsigned int& n);
      istream_type& operator>>(long& n);
      istream_type& operator>>(unsigned long& n);
      istream_type& operator>>(float& f);
      istream_type& operator>>(double& f);
      istream_type& operator>>(long double& f);
      istream_type& operator>>(void*& p);
      istream_type& operator>>(basic_streambuf<char_type,baggage>& sb);
      int_type get();
      istream_type& get(char_type* s, streamsize n,
                        char_type delim = newline());

  +-------                BEGIN BOX 66                -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 66                 -------+

  +-------                BEGIN BOX 67                -------+
  The same considerations as applied to operator>> apply here.  -- jss
  +-------                 END BOX 67                 -------+

      istream_type& get(unsigned char_type* s, streamsize n,
                        char_type delim = newline())

  +-------                BEGIN BOX 68                -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 68                 -------+

      istream_type& get(signed char_type* s, streamsize n,
                        char_type delim = newline())
      istream_type& get(char_type& c);
      istream_type& get(unsigned char_type& c);
      istream_type& get(signed char_type& c);
      istream_type& get(basic_streambuf<char_type,baggage>& sb,
                        char_type delim = newline());
      istream_type& getline(char_type* s, streamsize n,
                            char_type delim = newline());

  +-------                BEGIN BOX 69                -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 69                 -------+

  +-------                BEGIN BOX 70                -------+
  The same considerations as applied to operator>> apply here.  -- jss
  +-------                 END BOX 70                 -------+

      istream_type& getline(unsigned char_type* s, streamsize n,
                            char_type delim = newline())
      istream_type& getline(signed char_type* s, streamsize n,
                            char_type delim = newline())
      istream_type& ignore(streamsize n = 1, int_type delim = eof());
      istream_type& read(char_type* s, streamsize n);

  +-------                BEGIN BOX 71                -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 71                 -------+

  +-------                BEGIN BOX 72                -------+
  The same considerations as applied to operator>> apply here.  -- jss
  +-------                 END BOX 72                 -------+

      istream_type& read(unsigned char_type* s, streamsize n)
      istream_type& read(signed char_type* s, streamsize n)

  +-------                BEGIN BOX 73                -------+
  A new member function for supporting the raw byte I/O in which it per­
  forms rdbuf().read_byte(s,n)
  +-------                 END BOX 73                 -------+

      istream_type& read_byte(char* s, streamsize n);

  +-------                BEGIN BOX 74                -------+
  The following was not part of the proposal.  Should we  keep  it?   --
  mjv
  +-------                 END BOX 74                 -------+

  +-------                BEGIN BOX 75                -------+
  Yes, it is the interface to in_avail -- jss
  +-------                 END BOX 75                 -------+

      int readsome(char_type* s, int n);
      int peek();
      istream_type& putback(char_type c);
      istream_type& unget();
      streamsize gcount() const;
      int sync();
  private:
  //  streamsize chcount; exposition only
  };

  +-------                BEGIN BOX 76                -------+
  We  talked  about this in Kitchener and it seems that deriving istream
  from an instance of basic_istream<char> doesn't work unless it  dupli­
  cates all the members with return type modified to istream rather than
  basic_istream<char>.  Rather than do that we could "bite  the  bullet"
  and  make  them  typedefs.   The consequence of that any existing code
  that declares  them  to  be  (incomplete)  classes  without  including
  <iostream.h>  will  break.   Both  of  these are unpleasant.  But some
  change is required, so as a placeholder Jerry Schwarz proposal:
      typedef basic_istream<char> istream;
      typedef basic_istream<wchar_t> wistream;
  +-------                 END BOX 76                 -------+

      class istream : public basic_istream<char> {};
      class wistream : public basic_istream<wchar_t> {};

1 The class basic_istream defines a number of member function signatures
  that  assist  in  reading  and  interpreting input from sequences con­
  trolled by a stream buffer.

  +-------                BEGIN BOX 77                -------+
  [To Be Filled]
  +-------                 END BOX 77                 -------+

2 For the sake of exposition, the data maintained by an object of  class
  basic_istream is presented here as:

  --int  chcount,  stores the number of characters extracted by the last
    unformatted input member function called for the object.

3 Two groups of member function signatures share common properties:  the
  formatted  input  functions  (or extractors) and the unformatted input
  functions. Both groups of input functions are  described  as  if  they
  obtain  (or  extract)  input  characters  by  calling  sb.sbumpc()  or
  sb.sgetc().  They may use other public members of istream except  that
  they do not invoke any tuals members of sb except uflow.

4 If  sb.sbumpc()  or sb.sgetc() returns eof(), then the input function,
  except as explicitly noted otherwise, completes its actions  and  does
  setstate(eofbit) before returning.

5 If  one  of  these  called  functions throws an exception, then unless
  explicitly noted otherwise the input function  calls  setstate(badbit)
  and  if  badbit is on in sb.exception() rethrows the exception without
  completing its actions.

  27.2.2.1.1  basic_istream constructor         [lib.basic.istream.cons]
      basic_istream(basic_streambuf<charT,baggage>* sb);

1 Constructs an object of class basic_istream, assigning initial  values
  to  the base class by calling basic_ios::init(sb), then assigning zero
  to chcount.

  27.2.2.1.2  basic_istream destructor           [lib.basic.istream.des]
      virtual ~basic_istream();

1 Destroys an object of class basic_istream.  Does not perform any oper­
  ations of sb.

  27.2.2.1.3  basic_istream::ipfx                    [lib.istream::ipfx]
      bool ipfx(bool noskipws = 0);

1 If  good()  is  true,  prepares  for  formatted  or unformatted input.
  First,  if  tie()  is  not  a  null  pointer,   the   function   calls
  tie()->flush()  to synchronize the output sequence with any associated
  external  C  stream.18)  If  noskipws  is zero and flags() & skipws is
  nonzero, the function extracts and discards each character as long  as
  the next available input character c is a whitespace character.

2 To  decide  if the character c is a whitespace character, the function
  performs as if it executes the following code fragment:
    locale::ctype<charT> ctype = getloc().use<locale::ctype<charT> >();
    if (baggage::char_bag::is_whitespace (c, ctype)!=0)
   // c is a whitespace character.

3 If, after any preparation is completed, good() is true, returns  true.
  Otherwise, it calls setstate(failbit) and returns false.19)

  +-------                BEGIN BOX 78                -------+
  The proposal will say as follows:

  The function basic_istream<charT,baggage>::ipfx() uses  the  function,
  bool  baggage::char_bag::is_whitespace(charT,  const  locale*)  in the
  baggage structure to determine whether the  next  input  character  is
  whitespace or not.

  A typical implementation of the ipfx function may be as follows:

  _________________________
  18) The call tie()->flush() does not necessarily occur if the function
  can determine that no synchronization is necessary.
  19)  The function signatures ipfx(int) and isfx() can also perform ad­
  ditional implementation-dependent operations.

  template <class charT, class baggage = ios_baggage<charT> >
  int basic_istream<charT,baggage>::ipfx() {
      ...
  // skipping whitespace according to a constraint function,
  // is_whitespace
      intT c;
      typedef locale::ctype<charT> ctype_type;
      ctype_type& ctype = getloc().use<ctype_type>();
      while ((c = rdbuf()->snextc()) != eof()) {
      if (!baggage::char_bag::is_whitespace (c,ctype)==0) {
          rdbuf()->sputbackc (c);
          break;
      }
      }
      ...
   }

  In case we use ios_baggage<char> or ios_baggage<wchar_t>, the behavior
  of the constraint function baggage::char_bag::is_whitespace() is as if
  it invokes:
     locale::ctype<charT>& ctype = getloc().use<locale::ctype<charT> >();
     ctype.is(locale::ctype<charT>::SPACE, c);
  otherwise,     the     behavior     of     the      function      bag­
  gage::char_bag::is_whitespace() is unspecified.

  Those  who  want  to  use  locale-independent whitespace predicate can
  specify   their   definition   of   is_whitespace   in    their    new
  ios_char_baggage as follows:
  struct my_baggage : public ios_baggage<char> {
      typedef my_char_baggage char_bag;
  };
  struct my_char_baggage : public ios_char_baggage<char> {
      static bool is_whitespace (char c, const locale::ctype<charT>& ctype) {
      ....(my own implementation)...
      }
  };
  +-------                 END BOX 78                 -------+

  27.2.2.1.4  basic_istream::isfx                    [lib.istream::isfx]
      void isfx();

1 Returns.

  27.2.2.1.5  basic_istream::sync                    [lib.istream::sync]
      int sync();

1 If  rdbuf()  is  a  null  pointer,  returns  eof().   Otherwise, calls
  rdbuf()->pubsync() and, if that function  returns  eof(),  calls  set­
  state(badbit) and returns eof().  Otherwise, returns zero.

  27.2.2.2  Formatted input functions            [lib.istream.formatted]

  27.2.2.2.1  Common requirements         [lib.istream.formatted.reqmts]

1 Each  formatted input function begins execution by calling ipfx().  If
  that function returns true,  the  function  endeavors  to  obtain  the
  requested  input.   In  any case, the formatted input function ends by
  calling isfx(), then returns *this

2 Some formatted input functions endeavor to obtain the requested  input
  by  parsing  characters  extracted from the input sequence, converting
  the result to a value of some scalar data type, and storing  the  con­
  verted value in an object of that scalar data type.

  +-------                BEGIN BOX 79                -------+
  The  numeric  conversion  behaviors  of  the  following extractors are
  locale-dependent.
      istream_type::operator>>(short& val);
      istream_type::operator>>(unsigned short& val);
      istream_type::operator>>(int& val);
      istream_type::operator>>(unsigned int& val);
      istream_type::operator>>(long& val);
      istream_type::operator>>(unsigned long& val);
      istream_type::operator>>(float& val);
      istream_type::operator>>(double& val);
      istream_type::operator>>(long double& val);
  As in the case of the inserters, these extractors depend on the Nathan
  Myers's  locale::num_get<>  object to perform parsing the input stream
  data.  The conversion occurs as if it  performed  the  following  code
  fragment:
    HOLDTYPE tmp;
    locale::num_get<charT>& fmt = loc.use< locale::num_get<charT> >();
    fmt.get (iter, *this, loc, tmp);
    if ((val = (TYPE)tmp) != tmp)
    // set fail bit...
  In  the  above  fragment,  loc  stands  for  the private member of the
  basic_ios class, TYPE stands for the  type  of  the  argument  of  the
  extractor, and HOLDTYPE is as follows;

  --for short, int and long, HOLDTYPE is long;

  --for  unsigned  short,  unsigned  int  and unsigned long, HOLDTYPE is
    unsigned long.

  --for float, double, HOLDTYPE is double.

  --for long double, HOLDTYPE is long double.

    The first argument provides an object of the istream_iterator  class
    which  is  an  iterator  pointed  to  an  input stream.  It bypasses
    istreams and uses streambufs directly.  Class locale relies on  this
    type  as its interface to istream, since the flexibility it has been
    abstracted away from direct dependence on istream.
  +-------                 END BOX 79                 -------+

3 In case the converting result is a value of either  an  integral  type
  (short,  unsigned  short, int, unsigned int, long, unsigned long) or a
  float type (float, double, long double), performing to parse and  con­
  vert  the  result depend on the imbued locale object.  So the behavior
  of the above type extractors are locale-dependent.  The imbued  locale
  object  uses  an  istreambuf_iterator  to  access  the input character
  sequence.

4 The behavior of such functions is described in terms of the conversion
  specification for an equivalent call to the function fscanf()20) oper­
  ating  with  the  global  locale set to loc, with the following alter­
  ations:

  --The formatted input  function  extracts  characters  from  a  stream
    buffer, rather than reading them from an input file.21)

  --If flags() & skipws is zero, the function does not skip any  leading
    white  space.   In  that  case, if the next input character is white
    space, the scan fails.

  --If the converted data value cannot be represented as a value of  the
    specified scalar data type, a scan failure occurs.

  +-------                BEGIN BOX 80                -------+
  Can  the current locale::num_put/num_get facet handle basefield speci­
  fication?  Needs more discussion.
  +-------                 END BOX 80                 -------+

5 If the scan fails for any reason, the formatted input  function  calls
  setstate(failbit).

6 For  conversion  to  an integral type other than a character type, the
  function determines the integral conversion specifier as indicated  in
  Table 12:

  _________________________
  20) The signature fscanf(FILE*, const char*, ...) is declared in <cst­
  dio> (_lib.file.streams_)
  21)  The  stream  buffer  can,  of course, be associated with an input
  file, but it need not be.

                      Table 12--Integer conversions

            +------------------------------------------------+
            |           State               stdio equivalent |
            +------------------------------------------------+
            |(flags() & basefield) == oct          %o        |
            +------------------------------------------------+
            |(flags() & basefield) == hex          %x        |
            |(flags() & uppercase) != 0            %X        |
            +------------------------------------------------+
            |(flags() & basefield) == 0            %i        |
            |                                                |
            |Otherwise,                                      |
            +------------------------------------------------+
            |signed integral type                  %d        |
            +------------------------------------------------+
            |unsigned integral type                %u        |
            +------------------------------------------------+

  +-------                BEGIN BOX 81                -------+
  Is this table clear with regards to f5%x vs. %X ?  -- jss
  +-------                 END BOX 81                 -------+

  27.2.2.2.2  basic_istream::operator>>        [lib.istream::extractors]
      istream_type& operator>>(istream_type& (*pf)(istream_type&))

1 Returns (*pf)(*this).22)
      istream_type& operator>>(ios_type& (*pf)(ios_type&))

2 Calls (*pf)(*this), then returns *this.23)
      istream_type& operator>>(char_type* s);

3 Extracts characters and stores them into successive  locations  of  an
  array  whose  first element is designated by s.  If width() is greater
  than zero, the maximum number of characters stored n is width();  oth­
  erwise it is INT_MAX.24)

4 Characters are extracted and stored until any of the following occurs:

  --n - 1 characters are stored;

  --end-of-file occurs on the input sequence;

  _________________________
  22) See, for example, the function signature ws(basic_istream&).
  23)      See,      for     example,     the     function     signature
  dec(basic_ios<charT,baggage>&).
  24) MAX_INT is defined in <climits> (_lib.file.streams_).

  --baggage::char_bag::is_whitespace(c,ctype) is nonzero  for  the  next
    available  input character c.  In the above code fragment, the argu­
    ment ctype is acquired by getloc().use<locale::ctype<charT> >().

5 If the function stores no characters, it calls setstate(failbit).   In
  any  case,  it  then  stores a null character into the next successive
  location of the array and calls width(0).

6 Returns *this.

  +-------                BEGIN BOX 82                -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 82                 -------+

      istream_type& operator>>(unsigned char_type* s)

7 Returns operator>>((char_type*)s).
      istream_type& operator>>(signed char_type* s);

8 Returns operator>>((char_type*)s).
      istream_type& operator>>(char_type& c);

9 Extracts a character, if one is available, and stores it in c.  Other­
  wise, the function calls setstate(failbit).

10Returns *this.

  +-------                BEGIN BOX 83                -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 83                 -------+

      istream_type& operator>>(unsigned char_type& c)

11Returns operator>>((char&)c).
      istream_type& operator>>(signed char_type& c)

12Returns operator>>((char&)c).
      istream_type& operator>>(bool& n);

13Converts a signed short integer, if one is available, and stores it in
  x.  Behaves as if:
    if (flags() & ios::boolalpha) {
      getloc().extract(*this, n);
    } else {
      int x;
      *this >> x;
      if (x == 0)
        n = false;
      else if (x == 1)
        n = true;
      else
        ; // indicate failure
    }
    return *this;

  +-------                BEGIN BOX 84                -------+
  Locale extraction (getloc().extract())  of  the  string  is  something
  like:
    istream i;
    string bool_false = ...; // locale dependent
    string bool_true  = ...;
    string s;
    i >> s;
    if (s == bool_false)
      n = false;
    else if (s == bool_true)
      n = true;
    else
      ; // indicate failure
  The strings for the default locale are "false" and "true".
  +-------                 END BOX 84                 -------+

14Returns *this.
      istream_type& operator>>(short& n);

15Converts a signed short integer, if one is available, and stores it in
  n.

16Returns *this.
      istream_type& operator>>(unsigned short& n);

17Converts an unsigned short integer, if one is available, and stores it
  in n.

18Returns *this.
      istream_type& operator>>(int& n);

19Converts a signed integer, if one is available, and stores it in n.

20Returns *this.
      istream_type& operator>>(unsigned int& n);

21Converts an unsigned integer, if one is available, and stores it in n.

22Returns *this.
      istream_type& operator>>(long& n);

23Converts a signed long integer, if one is available, and stores it  in
  n.

24Returns *this.
      istream_type& operator>>(unsigned long& n);

25Converts  an unsigned long integer, if one is available, and stores it
  in n.

26Returns *this.
      istream_type& operator>>(float& f);

27Converts a float, if one is available, and stores it in f.

28Returns *this.
      istream_type& operator>>(double& f);

29Converts a double, if one is available, and stores it in f.

30Returns *this.
      istream_type& operator>>(long double& f);

31Converts a long double, if one is available, and stores it in f.

32Returns *this.
      istream_type& operator>>(void*& p);

33Converts a pointer to void, if one is available, and stores it in p.

34Returns *this.
      istream_type& operator>>(basic_streambuf<charT,baggage>& sb);

35Extracts characters from *this and inserts them in the output sequence
  controlled by sb.  Characters are extracted and inserted until any  of
  the following occurs:

  --end-of-file occurs on the input sequence;

  --inserting  in the output sequence fails (in which case the character
    to be inserted is not extracted);

  --an exception occurs (in which case the exception is  caught).   set­
    state(badbit) is not called

36If the function inserts no characters, it calls setstate(failbit).  If
  failure was due to catching an exception thrown while extracting char­
  acters  from  sb and failbit is on in except then the caught exception
  is rethrown.

37Returns *this.

  27.2.2.3  Unformatted input functions        [lib.istream.unformatted]

1 Each unformatted input function begins execution by  calling  ipfx(1).
  If  that  function  returns nonzero, the function endeavors to extract
  the  requested  input.   It  also  counts  the  number  of  characters
  extracted.   In any case, the unformatted input function ends by stor­
  ing the count in a member object and calling  isfx(),  then  returning
  the value specified for the unformatted input function.

  27.2.2.3.1  basic_istream::get                      [lib.istream::get]
      int get();

1 Extracts  a  character  c,  if  one  is  available.  The function then
  returns  (unsigned  char)c.   Otherwise,  the  function   calls   set­
  state(failbit) and then returns eof().

      istream_type& get(char_type*  s, streamsize n,
                        char_type delim = newline());

2 Extracts  characters  and  stores them into successive locations of an
  array  whose  first  element  is  designated  by  s.   Characters  are
  extracted and stored until any of the following occurs:

  --n - 1 characters are stored;

  --end-of-file occurs on the input sequence (in which case the function
    calls setstate(eofbit));

  --c == delim for the next available input character c (in which case c
    is not extracted).

3 If  the function stores no characters, it calls setstate(failbit).  In
  any case, it then stores a null character  into  the  next  successive
  location of the array.

4 Returns *this.

  +-------                BEGIN BOX 85                -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 85                 -------+

      istream_type& get(unsigned char_type* s, streamsize n,
                        char_type delim = newline())

5 Returns get((char_type*)s, n, delim).
      istream_type& get(signed char_type* s, streamsize n,
                        char_type delim = newline())

6 Returns get((char_type*)s, n, delim).
      istream_type& get(char_type& c);

7 Extracts a character, if one is available, and assigns it to c.   Oth­
  erwise, the function calls setstate(failbit).

8 Returns *this.
      istream_type& get(unsigned char_type& c);

9 Returns get((char&)c).

  +-------                BEGIN BOX 86                -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 86                 -------+

      istream_type& get(signed char_type& c);

10Returns basic_istream::get((char&)c).
      istream_type& get(basic_streambuf<char_type,baggage>& sb,
                        char_type delim = newline());

11Extracts characters and inserts them in the output sequence controlled
  by sb.  Characters are extracted and inserted until any of the follow­
  ing occurs:

  --end-of-file occurs on the input sequence;

  --inserting  in the output sequence fails (in which case the character
    to be inserted is not extracted);

  --c == delim for the next available input character c (in which case c
    is not extracted);

  --an  exception occurs (in which case, the exception is caught but not
    rethrown).

12If the function inserts no characters, it calls setstate(failbit).

13Returns *this.

  27.2.2.3.2  basic_istream::getline              [lib.istream::getline]
      istream_type& getline(char_type* s, streamsize n,
                            char_type delim = newline());

1 Extracts characters and stores them into successive  locations  of  an
  array  whose  first  element  is  designated  by  s.   Characters  are
  extracted and stored until one of the following occurs:

  1)end-of-file occurs on the input sequence (in which case the function
    calls setstate(eofbit));

  2)c  ==  delim for the next available input character c (in which case
    the input character is extracted but not stored);25)

  3)n  -  1 characters are stored (in which case the function calls set­
    state(failbit)).

2 These conditions are tested in the order shown.26)

3 If the function extracts no characters, it calls setstate(failbit).27)

4 In any case, it then stores a null character into the next  successive
  location of the array.

5 Returns *this.

  _________________________
  25) Since the final input character is ``extracted,'' it is counted in
  the gcount(), even though it is not stored.
  26) This allows an input line which exactly fills the buffer,  without
  setting  failbit.  This is different behavior than the historical AT&T
  implementation.
  27) This implies an empty input line will not cause failbit to be set.

6 Example:
    #include <iostream>
    using std;

    const int line_buffer_size = 100;

    int main()
    {
      char buffer[line_buffer_size];
      int line_number = 0;

      while (cin.getline(buffer, line_buffer_size) || cin.gcount()) {
        int count = cin.gcount();
        if (cin.eof())
          cout << "Partial final line";   // cin.fail() is false
        else if (cin.fail()) {
          cout << "Partial long line";
          cin.clear(cin.rdstate() & ~ios::failbit);
        } else {
          count--;        // Don't include '\n' in count
          cout << "Line " << ++line_number;
        }
        cout << " (" << count << " chars): " << buffer << endl;
      }
    }

  +-------                BEGIN BOX 87                -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 87                 -------+

      istream_type& getline(unsigned char_type* s, streamsize n,
                            char_type delim = newline())

7 Returns getline((char_type*)s, n, delim).
      istream_type& getline(signed char_type* s, streamsize n,
                            char_type delim = newline())

8 Returns getline((char_type*)s, n, delim).

  27.2.2.3.3  basic_istream::ignore                [lib.istream::ignore]
      istream_type& ignore(int n = 1, int_type delim = eof());

1 Extracts characters and discards them.  Characters are extracted until
  any of the following occurs:

  --if n != INT_MAX, n characters are extracted

  --end-of-file occurs on the input sequence (in which case the function
    calls setstate(eofbit));

  --c == delim for the next available input character c (in which case c
    is extracted).  28)
  _________________________
  28) The macro INT_MAX is defined in <climits>.

2 The last condition will never occur if delim == eof().

3 Returns *this.

  27.2.2.3.4  basic_istream::read                    [lib.istream::read]
      istream_type& read(char_type* s, streamsize n);

1 Extracts characters and stores them into successive  locations  of  an
  array  whose  first  element  is  designated  by  s.   Characters  are
  extracted and stored until either of the following occurs:

  --n characters are stored;

  --end-of-file occurs on the input sequence (in which case the function
    calls setstate(failbit)).

2 Returns *this.

  +-------                BEGIN BOX 88                -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 88                 -------+

      istream_type& read(unsigned char_type* s, streamsize n)

3 Returns read((char_type*)s, n).
      istream_type& read(signed char_type* s, streamsize n)

4 Returns read((char_type*)s, n).

  27.2.2.3.5  basic_istream::read_byte          [lib.istream::read.byte]
      istream_type<charT,baggage>& read_byte(char* s, streamsize n);

1 Extracts bytes by invoking:
     rdbuf()->read_byte(s,n);

2 In case end-of-file occurs on the input character sequence, the  func­
  tion calls setstate(failbit).

3 Returns *this.

  +-------                BEGIN BOX 89                -------+
  The following was not part of the proposal.  Should we keep it?
  +-------                 END BOX 89                 -------+

  27.2.2.3.6  basic_istream::readsome            [lib.istream::readsome]
      int readsome(char_type* s, int n);

1 Extracts  characters  and  stores them into successive locations of an
  array whose first element is designated  by  s.   The  function  first
  determines  navail,  the  value  returned  by  calling in_avail().  If
  navail is 1, the function calls setstate(eofbit) and returns zero.

2 Otherwise, the function determines the number of characters to extract
  m as the smaller of n and navail, and returns read(s, m).

  27.2.2.3.7  basic_istream::peek                    [lib.istream::peek]
      int peek();

1 Returns    eof()    if    good()   is   false.    Otherwise,   returns
  rdbuf()->sgetc().

  27.2.2.3.8  basic_istream::putback              [lib.istream::putback]
      istream_type& putback(char_type c);

1 Calls rdbuf->sputbackc(c).  If that function returns eof(), calls set­
  state(badbit).

2 Returns *this.

  27.2.2.3.9  basic_istream::unget                  [lib.istream::unget]
      istream_type& unget();

1 Calls  rdbuf->sungetc().   If  that function returns eof(), calls set­
  state(badbit).

2 Returns *this.

  27.2.2.3.10  basic_istream::gcount               [lib.istream::gcount]
      streamsize gcount() const;

1 Returns chcount.

  27.2.2.4  Standard basic_istream             [lib.basic.istream.manip]
       manipulators
      template<class charT, class baggage>
          basic_istream<charT,baggage>& ws(basic_istream<charT,baggage>& is);

1 Saves  a  copy  of  is.fmtflags, then clears is.skipws in is.fmtflags.
  Then calls is.ipfx() and is.isfx(), and restores  is.fmtflags  to  its
  saved value.29)

2 Returns is.

  27.2.3  Template class                       [lib.istreambuf.iterator]
       istreambuf_iterator

  +-------                BEGIN BOX 90                -------+
  As  part  of  the original proposals, the class istreambuf_iterator is
  defined in the header <istream>.

  It    really    should    be    defined    as    part    of     Clause
  _lib.streambuf.iterators_.
  _________________________
  29)  The  effect  of cin >> ws is to skip any white space in the input
  sequence controlled by cin.

  +-------                 END BOX 90                 -------+

      template<class charT, class baggage = ios_baggage<charT> >
      class istreambuf_iterator {
      public:
          typedef charT char_type;
          typedef baggage baggage_type;
          typedef baggage::int_type int_type;
          typedef basic_streambuf<charT,baggage> streambuf;
          typedef basic_istream<charT,baggage> istream;
          class proxy {
              charT keep_;
              streambuf* sbuf_;
              proxy (charT c, streambuf* sbuf)
                : keep_(c), sbuf_(sbuf) {}
          public:
              charT operator*() { return keep_; }
              friend class istreambuf_iterator;
          };
      public:
          istreambuf_iterator();
          istreambuf_iterator(istream& s);
          istreambuf_iterator(streambuf* s);
          istreambuf_iterator(const proxy& p);
          charT operator*();
          istreambuf_iterator<charT,baggage>& operator++();
          proxy operator++(int);
          bool equal(istreambuf_iterator& b);
      private:
  //      streambuf* sbuf_;       exposition only
      };

1 The template class  istreambuf_iterator  reads  successive  characters
  from the streambuf for which it was constructed.

2 After it is constructed, and every time operator++ is used, the itera­
  tor reads and stores a value of character.  If the end  of  stream  is
  reached  (streambuf::sgetc()  returns  baggage::char_bag::eof()),  the
  iterator becomes equal to the  end  of  stream  iterator  value.   The
  default constructor istreambuf_iterator() and the constructor istream­
  buf_iterator(0) always construct an end  of  stream  iterator  object,
  which  is  the  only legitimate iterator to be used for the end condi­
  tion.

3 The result of operator*() on an end of stream is undefined.   For  any
  other iterator value a const char_type& is returned.  It is impossible
  to store things into input iterators.

4 Note that in the input iterators, ++ operators are not  equality  pre­
  serving,  that  is,  i == j does not guarantee at all that ++i == ++j.
  Every time ++ is used a new value is used.

5 The practical consequence of this fact is that an  istreambuf_iterator
  object  can be used only for one-pass algorithms, which actually makes

  perfect sense, since for  multi-pass  algorithms  it  is  always  more
  appropriate to use in-memory data structures.  Two end of stream iter­
  ators are always equal.  An end of stream iterator is not equal  to  a
  non-end of stream iterator.  Two non-end of stream iterators are equal
  when they are constructed from the same stream.

  27.2.3.1  Template class              [lib.istreambuf.iterator::proxy]
       istreambuf_iterator::proxy
      template <class charT, class baggage = ios_baggage<charT> >
      class istream_iterator::proxy {
          charT keep_;
          streambuf* sbuf_;
          proxy(charT c, streambuf* sbuf) :
              keep_(c), sbuf_(sbuf) {}
      public:
          charT operator*() { return keep_; }
          friend class istreambuf_iterator;
      };

1 Class   istream_iterator<charT,baggage>::proxy   provides  a  temporal
  placeholder as the return value of the post-increment operator (opera­
  tor++).   It  keeps  the character pointed to by the previous value of
  the iterator for some possible future access to get the character.

  27.2.3.2  istreambuf_iterator           [lib.istreambuf.iterator.cons]
       constructors
     istreambuf_iterator();

1 Constructs the end-of-stream iterator.
     istreambuf_iterator(basic_istream<charT,baggage>& s);

2 Constructs the istream_iterator pointing to the basic_streambuf object
  *(s.rdbuf()).
     istreambuf_iterator(const proxy& p);

3 Constructs the istreambuf_iterator  pointing  to  the  basic_streambuf
  object related to the proxy object p.

  27.2.3.3                                [lib.istreambuf.iterator::op*]
       istreambuf_iterator::operator*
      charT operator*()

1 Extract one character pointed to by the streambuf *sbuf_.

  27.2.3.4                               [lib.istreambuf.iterator::op++]
       istreambuf_iterator::operator++
      istreambuf_iterator<charT,baggage>&
          istreambuf_iterator<charT,baggage>::operator++();

1 Advances the iterator and returns the result
      proxy istreambuf_iterator<charT,baggage>::operator++(int);

2 Advances the iterator and returns the proxy object keeping the charac­
  ter pointed to by the previous iterator.

  27.2.3.5                              [lib.istreambuf.iterator::equal]
       istreambuf_iterator::equal
      bool equal(istreambuf_iterator<charT,baggage>& b);

1 Returns true if the iterators are equal.  Equality is defined as  fol­
  lows:

  --If both a and b are end-of-stream iterators, a == b.

  --If  either  a or b is an end-of-stream iterator, if the other points
    end-of-file, a == b, otherwise a != b.

  --If both a and b are not end-of-stream, the two streambuf pointed  to
    by the both iterators are compared.

  27.2.3.6  iterator_category                  [lib.iterator.category.i]
     input_iterator iterator_category(const istreambuf_iterator& s);

1 Returns the category of the iterator s.

  27.2.3.7  operator==                   [lib.istreambuf.iterator::op==]
     template <class charT, class baggage = ios_baggage<charT> >
     bool operator==(istreambuf_iterator<charT, baggage>& a,
                     istreambuf_iterator<charT, baggage>& b);

1 Returns a.equal(b).

  27.2.3.8  operator!=                   [lib.istreambuf.iterator::op!=]
     template <class charT, class baggage = ios_baggage<charT> >
     bool operator!=(istreambuf_iterator<charT, baggage>& a,
                    istreambuf_iterator<charT, baggage>& b);

1 Returns !a.equal(b).

  27.2.4  Output streams                            [lib.output.streams]

1 The  header  <ostream>  defines a type and several function signatures
  that control output to a stream buffer.

  27.2.4.1  Template class basic_ostream                   [lib.ostream]

  template <class charT, class baggage = ioc_baggage<charT> >
  class basic_ostream : virtual public basic_ios<charT,baggage> {
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;
      int_type  eof()     { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }
  private:
      typedef basic_ostream<charT,baggage> ostream_type;
  public:
      basic_ostream(basic_streambuf<char_type,baggage>* sb);
      virtual ~basic_ostream();
      bool opfx();
      void osfx();
      ostream_type& operator<<(ostream_type& (*pf)(ostream_type&));
      ostream_type& operator<<(ios_type& (*pf)(ios_type&));
      ostream_type& operator<<(const char_type* s);
      ostream_type& operator<<(char_type c);

  +-------                BEGIN BOX 91                -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 91                 -------+

      ostream_type& operator<<(unsigned char_type c);
      ostream_type& operator<<(signed char_type c);
      ostream_type& operator<<(bool n);
      ostream_type& operator<<(short n);
      ostream_type& operator<<(unsigned short n);
      ostream_type& operator<<(int n);
      ostream_type& operator<<(unsigned int n);
      ostream_type& operator<<(long n);
      ostream_type& operator<<(unsigned long n);
      ostream_type& operator<<(float f);
      ostream_type& operator<<(double f);
      ostream_type& operator<<(long double f);
      ostream_type& operator<<(void* p);
      ostream_type& operator<<(basic_streambuf<char_type,baggage>& sb);
      int put(char_type c);
      ostream_type& write(const char_type* s, streamsize n);

  +-------                BEGIN BOX 92                -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 92                 -------+

      ostream_type& write(const unsigned char_type* s, streamsize n);
      ostream_type& write(const signed char_type* s, streamsize n);
      ostream_type& write_byte (const char* s, streamsize n);
      ostream_type& flush();
  };
      class ostream : public basic_ostream<char> {};
      class wostream : public basic_ostream<wchar_t> {};

1 The class basic_ostream defines a number of member function signatures
  that assist in formatting and writing output to output sequences  con­
  trolled by a stream buffer.

  +-------                BEGIN BOX 93                -------+
  [To Be Filled]
  +-------                 END BOX 93                 -------+

2 Two  groups of member function signatures share common properties: the
  formatted output functions (or inserters) and the  unformatted  output
  functions. Both groups of output functions generate (or insert) output
  characters by actions equivalent to calling sb.sputc(int).   They  may
  use  other  public  members  of  basic_ostream except that they do not
  invoke any tuals members of sb except overflow.  If the  called  func­
  tion  throws  an exception, the output function calls setstate(badbit)
  and if badbit is on in except rethrows the exception.

  27.2.4.1.1  basic_ostream constructor      [lib.basic.ostream.sb.cons]
      basic_ostream(basic_streambuf<charT,baggage>* sb);

1 Constructs  an object of class basic_ostream, assigning initial values
  to the base class by calling basic_ios<charT,baggage>::init(sb).

  27.2.4.1.2  basic_ostream destructor           [lib.basic.ostream.des]
      virtual ~basic_ostream();

1 Destroys an object of class basic_ostream.  Does not perform any oper­
  ations on sb.

  27.2.4.1.3  basic_ostream::opfx                    [lib.ostream::opfx]
      bool opfx();

1 If  good()  is  nonzero, prepares for formatted or unformatted output.
  If tie() is not a null pointer, calls tie()->flush().30)

  +-------                BEGIN BOX 94                -------+
  Note:  Need to append the locale dependency on appropriate extractors.
  +-------                 END BOX 94                 -------+

2 Returns good().31)

  27.2.4.1.4  basic_ostream::osfx                    [lib.ostream::osfx]
      void osfx();

1 If flags() & unitbuf is nonzero, calls flush().

  _________________________
  30) The call tie()->flush() does not necessarily occur if the function
  can determine that no synchronization is necessary.
  31) The function signatures opfx() and osfx() can also  perform  addi­
  tional implementation-dependent operations.

  27.2.4.1.5  basic_ostream::flush                  [lib.ostream::flush]
      basic_ostream& flush();

1 If  rdbuf()  is not a null pointer, calls rdbuf()->pubsync().  If that
  function returns eof(), calls setstate(badbit).

2 Returns *this.

  27.2.4.2  Formatted output functions           [lib.ostream.formatted]

  27.2.4.2.1  Common requirements         [lib.ostream.formatted.reqmts]

1 Each formatted output function begins execution by calling opfx().  If
  that  function returns nonzero, the function endeavors to generate the
  requested output.  In any case, the formatted output function ends  by
  calling  osfx(),  then returning the value specified for the formatted
  output function.

  +-------                BEGIN BOX 95                -------+
  The following specification  description  has  not  reflected  locale-
  dependency  of the behavior of the integral type/float type inserters.

  The numeric  conversion  behaviors  of  the  following  inserters  are
  locale-dependent:
    basic_ostream<charT,baggage>::operator<<(short val);
    basic_ostream<charT,baggage>::operator<<(unsigned short val);
    basic_ostream<charT,baggage>::operator<<(int val);
    basic_ostream<charT,baggage>::operator<<(unsigned int val);
    basic_ostream<charT,baggage>::operator<<(long val);
    basic_ostream<charT,baggage>::operator<<(unsigned long val);
    basic_ostream<charT,baggage>::operator<<(float val);
    basic_ostream<charT,baggage>::operator<<(double val);
    basic_ostream<charT,baggage>::operator<<(long double val);
  According    to    the    Nathan    Myers's    locale   object   draft
  [X3J16/94-0064R1,WG21/N0451R1],  the   class   locale::num_get<>   and
  locale::num_put<> handle locale-dependent numeric formatting and pars­
  ing.  The above inserter functions refers the imbued locale  value  to
  utilize these numeric formatting functionality.

  The formatting conversion occurs as if it performed the following code
  fragment:
    locale::num_put<charT>& fmt = loc.use< locale::num_put<charT> >();
    fmt.put (ostreambuf_iterator(*this), *this, loc, val);

  In the above fragment, loc  stands  for  the  private  member  of  the
  basic_ios  class  which maintains the imbued locale object.  The first
  argument provides an object of the ostreambuf_iterator class which  is
  an  iterator for ostream class.  It bypasses ostreams and uses stream­
  bufs directly.  Class locale relies on these types as its interface to
  iostreams,  since  for  flexibility  it  has been abstracted away from
  direct dependence on ostream.
  +-------                 END BOX 95                 -------+

2 Some  formatted  output  functions  endeavor to generate the requested
  output by converting a value from some scalar or  NTBS  type  to  text
  form and inserting the converted text in the output sequence.

  +-------                BEGIN BOX 96                -------+
  Needs work:  NTBS.
  +-------                 END BOX 96                 -------+

  The behavior of such functions is described in terms of the conversion
  specification for an equivalent call to the function fprintf,32) oper­
  ating with the global locale set to loc,  with  the  following  alter­
  ations:

  --The formatted output function inserts characters in a stream buffer,
    rather than writing them to an output file.33)

  --The  formatted  output  function uses the fill character returned by
    fill() as the padding character (rather than the space character for
    left or right padding, or 0 for internal padding).

3 If  the  operation fails for any reason, the formatted output function
  calls setstate(badbit).

4 For conversion from an integral type other than a character type,  the
  function  determines the integral conversion specifier as indicated in
  Table 13:

                      Table 13--Integer conversions

            +------------------------------------------------+
            |           State               stdio equivalent |
            +------------------------------------------------+
            |(flags() & basefield) == oct          %o        |
            +------------------------------------------------+
            |(flags() & basefield) == hex          %x        |
            |(flags() & uppercase) != 0            %X        |
            |                                                |
            |Otherwise,                                      |
            +------------------------------------------------+
            |signed integral type                  %d        |
            +------------------------------------------------+
            |unsigned integral type                %u        |
            +------------------------------------------------+

  +-------                BEGIN BOX 97                -------+
  _________________________
  32) The signature fprintf(FILE*, const char_type*, ...) is declared in
  <cstdio> (_lib.file.streams_).
  33) The stream buffer can, of course, be  associated  with  an  output
  file, but it need not be.

  Is this table clear with regards to f5%x vs. f5%X ?  -- jss
  +-------                 END BOX 97                 -------+

5 For conversion from a floating-point type, the function determines the
  floating-point conversion specifier as indicated in Table 14:

  +-------                BEGIN BOX 98                -------+
  Can  the current locale::num_put/num_get facet handle basefield speci­
  fication?  Needs more discussion.
  +-------                 END BOX 98                 -------+

                   Table 14--Floating-point conversions

        +--------------------------------------------------------+
        |               State                   stdio equivalent |
        +--------------------------------------------------------+
        |(flags() & floatfield) == fixed               %f        |
        +--------------------------------------------------------+
        |(flags() & floatfield) == scientific          %e        |
        |(flags() & uppercase) != 0                    %E        |
        |                                                        |
        |Otherwise,                                              |
        +--------------------------------------------------------+
        |                                              %g        |
        |(flags() & uppercase) != 0                    %G        |
        +--------------------------------------------------------+

  +-------                BEGIN BOX 99                -------+
  Is this table clear with regards to f5%e vs. %E ?  -- jss
  +-------                 END BOX 99                 -------+

6 The conversion  specifier  has  the  following  additional  qualifiers
  prepended as indicated in Table 15:

                   Table 15--Floating-point conversions

  +----------------------------------------------------------------------+
  |       Type(s)                    State              stdio equivalent |
  +----------------------------------------------------------------------+
  |an integral type oth­   (flags() & showpos) != 0            +         |
  |er than a character     (flags() & showbase) != 0           #         |
  |type                                                                  |
  +----------------------------------------------------------------------+
  |a floating-point type   (flags() & showpos) != 0            +         |
  |                        (flags() & showpoint) != 0          #         |
  +----------------------------------------------------------------------+

  --For  any  conversion,  if  width() is nonzero, then a field width is
    specified in the conversion specification.  The value is width().

  --For conversion from a floating-point type, if  flags()  &  fixed  is
    nonzero  or if precision() is greater than zero, then a precision is
    specified in the conversion  specification.   The  value  is  preci­
    sion().

7 Moreover, for any conversion, padding with the fill character returned
  by fill() behaves as follows:

  --If (flags() & adjustfield) == right, no flag  is  prepended  to  the
    conversion   specification,   indicating  right  justification  (any
    padding occurs before the converted text).  A fill character  occurs
    wherever fprintf generates a space character as padding.

  --If  (flags()  & adjustfield) == internal, the flag 0 is prepended to
    the conversion specification, indicating internal justification (any
    padding  occurs within the converted text).  A fill character occurs
    wherever fprintf generates a 0 as padding.34)

8 Otherwise,  the  flag  - is prepended to the conversion specification,
  indicating left justification (any padding occurs after the  converted
  text).   A  fill  character  occurs wherever fprintf generates a space
  character as padding.

9 Unless explicitly stated otherwise for  a  particular  inserter,  each
  formatted  output  function calls width(0) after determining the field
  width.

  27.2.4.2.2  basic_ostream::operator<<          [lib.ostream.inserters]
      ostream_type& operator<<(ostream_type& (*pf)(ostream_type&))

1 Returns (*pf)(*this).35)
      ostream_type& operator<<(ios_type& (*pf)(ios_type&))

2 Calls (*(basic_ios<charT,baggage>*)pf)(*this), then returns *this.36)
      ostream_type& operator<<(const char_type* s);

3 Converts the NTBS s with the conversion specifier s.

4 Returns *this.
      ostream_type& operator<<(char_type c);

5 Converts  the  char_type c with the conversion specifier c and a field
  width      of      zero.       The      stored       field       width
  (basic_ios<charT,baggage>::wide) is not set to zero.
  _________________________
  34) The conversion specification #o generates a leading 0 which is not
  a padding character.
  35) See, for example, the function signature endl(basic_ostream&).
  36)     See,     for     example,     the      function      signature
  ::dec(basic_ios<charT,baggage>&).

6 Returns *this.

  +-------                BEGIN BOX 100               -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 100                -------+

      ostream_type& operator<<(unsigned char_type c)

7 Returns operator<<((char_type)c).
      ostream_type& operator<<(signed char_type c)

8 Returns operator<<((char_type)c).
      ostream_type& operator<<(bool n);

9 Behaves as if:
    {
      if (flags() & ios::boolalpha) {
        getloc().insert(*this, n);
      } else {
        *this << int(n);
      }
    }

10Returns *this.
      ostream_type& operator<<(short n);

11Converts the signed short integer n with the integral conversion spec­
  ifier preceded by h.

12Returns *this.
      ostream_type& operator<<(unsigned short n);

13Converts  the  unsigned  short  integer n with the integral conversion
  specifier preceded by h.

14Returns *this.
      ostream_type& operator<<(int n);

15Converts the signed integer n with the integral conversion  specifier.

16Returns *this.
      ostream_type& operator<<(unsigned int n);

17Converts  the  unsigned  integer n with the integral conversion speci­
  fier.

18Returns *this.
      ostream_type& operator<<(long n);

19Converts the signed long integer n with the integral conversion speci­
  fier preceded by l.

20Returns *this.
      ostream_type& operator<<(unsigned long n);

21Converts  the  unsigned  long  integer  n with the integral conversion
  specifier preceded by l.

22Returns *this.
      ostream_type& operator<<(float f);

23Converts the float f with the floating-point conversion specifier.

24Returns *this.
      ostream_type& operator<<(double f);

25Converts the double f with the floating-point conversion specifier.

26Returns *this.
      ostream_type& operator<<(long double f);

27Converts the long double f with the floating-point  conversion  speci­
  fier preceded by L.

28Returns *this.
      ostream_type& operator<<(void* p);

29Converts the pointer to void p with the conversion specifier p.

30Returns *this.
      ostream_type& operator<<(basic_streambuf<charT,baggage>& sb);

31Gets  characters  from  sb  and inserts them in *this.  Characters are
  read from sb  and inserted until any of the following occurs:

  --end-of-file occurs on the input sequence;

  --inserting in the output sequence fails (in which case the  character
    to  be inserted is not extracted); LI an exception occurs while get­
    ting a character from sb (in which case, the exception is rethrown).

32If  the  function  inserts  no  characters or if it stopped because an
  exception was thrown while  extracting  a  character,  it  calls  set­
  state(failbit).  If an exception was thrown while extracting a charac­
  ter and failbit is on in excedptions the caught exception is rethrown.

33Returns *this.

  27.2.4.3  Unformatted output functions       [lib.ostream.unformatted]

1 Each  unformatted  output function begins execution by calling opfx().
  If that function returns nonzero, the function endeavors  to  generate
  the  requested  output.   In any case, the unformatted output function
  ends by calling osfx(), then returning the  value  specified  for  the
  unformatted output function.

  27.2.4.3.1  basic_ostream::put                      [lib.ostream::put]
      int put(char_type c);

1 Inserts  the character c, if possible.  Then returns (unsigned char)c.

2 Otherwise, calls setstate(badbit) and returns eof().

  27.2.4.3.2  basic_ostream::write              [lib.ostream::write.str]
      basic_ostream& write(const char_type* s, streamsize n);

1 Obtains characters to insert from successive  locations  of  an  array
  whose first element is designated by s.  Characters are inserted until
  either of the following occurs:

  --n characters are inserted;

  --inserting in the output sequence fails (in which case  the  function
    calls setstate(badbit)).

2 Returns *this.

  +-------                BEGIN BOX 101               -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 101                -------+

      basic_ostream& write(const unsigned char_type* s, streamsize n)

3 Returns write((const char_type*)s, n).
      basic_ostream& write(const signed char_type* s, streamsize n)

4 Returns write((const char_type*)s, n).

  27.2.4.3.3  basic_ostream::write_byte        [lib.ostream::write.byte]
      streamsize write_byte(const char* s, streamsize n);

1 Inserts bytes by invoking:
      rdbuf()->write_byte(s,n);

2 In case writing characters fails, calls setstate(failbit).

3 Returns the number of bytes written.

  27.2.4.4  Standard basic_ostream             [lib.basic.ostream.manip]
       manipulators

  27.2.4.4.1  endl                                            [lib.endl]
      basic_ostream<charT,baggage>& endl(basic_ostream<charT,baggage>& os);

1 Calls os.put(baggage::newline()), then os.flush().

2 Returns os.37)
  _________________________
  37)  The effect of executing cout << endl is to insert a newline char­
  acter in the output sequence controlled by cout, then  synchronize  it

  27.2.4.4.2  ends                                            [lib.ends]
      basic_ostream<charT,baggage>& ends(basic_ostream<charT,baggage>& os);

1
  +-------                BEGIN BOX 102               -------+
  [To Be Filled]
  +-------                 END BOX 102                -------+

2 Returns os.38)

  27.2.4.4.3  flush                                          [lib.flush]
      basic_ostream<charT,baggage>& flush(basic_ostream<charT,baggage>& os);

1 Calls os.flush().

  +-------                BEGIN BOX 103               -------+
  [To Be Filled]
  +-------                 END BOX 103                -------+

2 Returns os.

  27.2.5  Template class                       [lib.ostreambuf.iterator]
       ostreambuf_iterator

  +-------                BEGIN BOX 104               -------+
  Because  the  class  locale::num_put<>  depends on the class, ostream­
  buf_iterator as the fundamental access way to the output  stream  with
  some  efficiency,  the  class  ostreambuf_iterator  is  defined in the
  header <ostream>.

  It    really    should    be    defined    as    part    of     Clause
  _lib.streambuf.iterators_.
  +-------                 END BOX 104                -------+

      template <class charT, class baggage = ios_char_baggage<charT> >
      class ostreambuf_iterator {
      public:
          typedef charT char_type;
          typedef baggage baggage_type;
          typedef basic_streambuf<charT,baggage> streambuf;
          typedef basic_ostream<charT,baggage>   ostream;

  _________________________
  with any external file with which it might be associated.
  38) The effect of executing ostr << ends is to insert a null character
  in the output sequence controlled by ostr.  If ostr is  an  object  of
  class  basic_strstreambuf,  the  null  character can terminate an NTBS
  constructed in an array object.

      public:
          ostreambuf_iterator() : sbuf_(0) {}
          ostreambuf_iterator(ostream& s) : sbuf_(s.rdbuf()) {}
          ostreambuf_iterator(streambuf* s) : sbuf_(s) {}
          ostreambuf_iterator& operator*() { return *this; }
          ostreambuf_iterator& operator++() { return *this; }
          ostreambuf_iterator& operator++(int) { return *this; }
          ostreambuf_iterator& operator=(charT c) {
              sbuf_->sputc(baggage::to_int_type(c));
          }
          bool equal(ostreambuf_iterator& b) {
              return sbuf_ == b.sbuf_;
          }
      private:
  //      streambuf* sbuf_;       exposition only
      };

1 The template class ostreambuf_iterator  writes  successive  characters
  onto  the output stream from which it was constructed.  It is not pos­
  sible to get a value out of the output iterator.

2 Two output iterators are equal if they are constructed with  the  same
  output streambuf.
      output_iterator iterator_category (const ostreambuf_iterator&) {
        return output_iterator();
      }
    template<class charT, class baggage = ios_char_baggage<charT> >
    bool operator==(ostreambuf_iterator<charT,baggage>& a,
                    ostreambuf_iterator<charT,baggage>& b) {
            return a.equal (b);
    }
    template<class charT, class baggage = ios_char_baggage<charT> >
    bool operator!=(ostreambuf_iterator<charT,baggage>& a,
                    ostreambuf_iterator<charT,baggage>& b) {
            return !a.equal (b);
    }

  27.3  Stream manipulators                           [lib.manipulators]

1 Headers:

  --<iomanip>

2 Table 16:

                   Table 16--Header <iomanip> synopsis

     +---------------------------------------------------------------+
     |       Type                           Name(s)                  |
     +---------------------------------------------------------------+
     |Template classes:                                              |
     |basic_imanip          imanip                wimanip            |
     |basic_omanip          omanip                womanip            |
     |basic_smanip          smanip                wsmanip            |
     +---------------------------------------------------------------+
     |Template operators:                                            |
     |operator<< (omanip)   operator>> (imanip)                      |
     |operator<< (smanip)   operator>> (smanip)                      |
     +---------------------------------------------------------------+
     |Template functions:                                            |
     |basic_resetiosflags   basic_setfill         basic_setprecision |
     |basic_setbase         basic_setiosflags                        |
     +---------------------------------------------------------------+
     |Functions:                                                     |
     |resetiosflags         setfill               setprecision       |
     |setbase               setiosflags           setw               |
     +---------------------------------------------------------------+

3 The  header  <iomanip>  defines  three  template  classes  and several
  related functions that use these template classes to  provide  extrac­
  tors   and  inserters  that  alter  information  maintained  by  class
  basic_ios and its derived classes.  It also defines several instantia­
  tions of these template classes and functions.

  27.3.1  Input manipulators                           [lib.input.manip]

  +-------                BEGIN BOX 105               -------+
  Manipulators  have  gotten way out of hand.  The standard mainpulators
  should be provided, but the general mechanism isn't needed and a  sim­
  pler way to define them should be possible.
  +-------                 END BOX 105                -------+

  27.3.1.1  Template class basic_imanip      [lib.template.basic.imanip]

  template<class T, class charT, class baggage = ios_char_baggage<charT> >
  class basic_imanip {
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;
      int_type eof()      { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }
  public:
      basic_imanip(
        basic_ios<charT,baggage>& (*pf_arg)(basic_ios<charT,baggage>&, T), T);
  //  basic_ios<charT,baggage>& (*pf)(basic_ios<charT,baggage>&, T);      exposition only
  //  T manarg;   exposition only
      };
      template <class T> class imanip<T> : public basic_imanip<T,char> {};
      template <class T> class wimanip<T> : public basic_imanip<T,wchar_t> {};

1 The template class basic_imanip<T,charT,baggage> describes  an  object
  that can store a function pointer and an object of type T.  The desig­
  nated function accepts an argument of this type T.

  +-------                BEGIN BOX 106               -------+
  [To Be Filled]
  +-------                 END BOX 106                -------+

2 For the sake of exposition, the maintained data is presented here as:

  --basic_ios<charT,baggage>& (*pf)(basic_ios<charT,baggage>&,  T),  the
    function pointer;

  --T manarg, the object of type T.

  27.3.1.1.1  basic_imanip<T>          [lib.basic.imanip.basic.ios.cons]
       constructor
      basic_imanip(basic_ios<charT,baggage>&
                     (*pf_arg)(basic_ios<charT,baggage>&, T), T manarg_arg);

1 Constructs an object of  class  basic_imanip<T>,  initializing  pf  to
  pf_arg and manarg to manarg_arg.

  27.3.1.1.2  operator>>                          [lib.ext.basic.imanip]
      template<class T, class charT, class baggage>
      basic_istream<charT,baggage>&
          operator>>(basic_istream<charT,baggage>& is,
                     const basic_imanip<T,charT,baggage>& a);

1 Calls  (*a.pf)(is,  a.manarg)  and  catches any exception the function
  call  throws.   If  the  function  catches  an  exception,  it   calls
  is.setstate(basic_ios::failbit) (the exception is not rethrown).

2 Returns is.

  27.3.2  Template class basic_omanip        [lib.template.basic.omanip]
  template<class T, class charT, class baggage = ios_char_baggage<charT> >
  class basic_omanip {
  public:
      basic_omanip(
        basic_ios<charT,baggage>& (*pf_arg)(basic_ios<charT,baggage>&, T), T);
  //  basic_ios<charT,baggage>& (*pf)(basic_ios<charT,baggage>&, T);      exposition only
  //  T manarg;   exposition only
  };
      template <class T> class omanip<T> : public basic_omanip<T,char> {};
      template <class T> class womanip<T> : public basic_omanip<T,wchar_t> {};

1 The  template class basic_omanip<T> describes an object that can store
  a function pointer and an object of type T.  The  designated  function
  accepts an argument of this type T.

  +-------                BEGIN BOX 107               -------+
  [To Be Filled]
  +-------                 END BOX 107                -------+

2 For the sake of exposition, the maintained data is presented here as:

  --basic_ios<charT,baggage>&  (*pf)(basic_ios<charT,baggage>&,  T), the
    function pointer;

  --T manarg, the object of type T.

  27.3.2.1  basic_omanip               [lib.basic.omanip.basic.ios.cons]
       constructor
      basic_omanip(
         basic_ios<charT,baggage>& (*pf_arg)(basic_ios<charT,baggage>&,T),
         T manarg_arg);

1 Constructs  an  object  of  class  basic_omanip<T>, initializing pf to
  pf_arg and manarg to manarg_arg.

  27.3.2.2  operator<<                            [lib.ins.basic.omanip]
      template<class T, class charT, class baggage>
      basic_ostream<charT,baggage>&
          operator<<(basic_ostream<charT,baggage>& os,
                     const basic_omanip<T,charT,baggage>& a);

1 Calls (*a.pf)(os, a.manarg) and catches  any  exception  the  function
  call   throws.   If  the  function  catches  an  exception,  it  calls
  os.setstate(basic_ios::failbit) (the exception is not rethrown).

2 Returns os.

  27.3.3  Template class basic_smanip        [lib.template.basic.smanip]

      template<class T, class charT, class baggage = ios_baggage<charT> >
      class basic_smanip {
      public:
          typedef charT char_type;
          typedef baggage::char_bag::int_type int_type;
          typedef baggage::pos_bag::pos_type  pos_type;
          typedef baggage::pos_bag::off_type  off_type;
          int_type  eof()     { return baggage::char_bag::eof(); }
          char_type newline() { return baggage::char_bag::newline(); }
      public:
          basic_smanip(
            basic_ios<charT,baggage>& (*pf_arg)(basic_ios<charT,baggage>&, T),
            T);
  //      basic_ios<charT,baggage>& (*pf)(basic_ios<charT,baggage>&, T);  exposition only
  //      T manarg;       exposition only
      };
      template <class T> class smanip<T> : public basic_smanip<T,char> {};
      template <class T> class wsmanip<T> : public basic_smanip<T,wchar_t> {};

1 The template class basic_smanip<T,charT,baggage> describes  an  object
  that can store a function pointer and an object of type T.  The desig­
  nated function accepts an argument of this type T.

  +-------                BEGIN BOX 108               -------+
  [To Be Filled]
  +-------                 END BOX 108                -------+

2 For the sake of exposition, the maintained data is presented here as:

  --basic_ios<charT,baggage>& (*pf)(basic_ios<charT,baggage>&,  T),  the
    function pointer;

  --T manarg, the object of type T.

  27.3.3.1  basic_smanip               [lib.basic.smanip.basic.ios.cons]
       constructor
      basic_smanip(
        basic_ios<charT,baggage>& (*pf_arg)(basic_ios<charT,baggage>&, T),
        T manarg_arg);

1 Constructs an object of  class  basic_smanip<T>,  initializing  pf  to
  pf_arg and manarg to manarg_arg.

  27.3.3.2  operator>>                            [lib.ext.basic.smanip]
      template<class T, class charT, class baggage>
      basic_istream<charT,baggage>&
          operator>>(basic_istream<charT,baggage>& is,
                     const basic_smanip<T,charT,baggage>& a);

1 Calls  (*a.pf)(is,  a.manarg)  and  catches any exception the function
  call  throws.   If  the  function  catches  an  exception,  it   calls
  is.setstate(basic_ios::failbit) (the exception is not rethrown).

2 Returns is.

  27.3.3.3  operator<<                            [lib.ins.basic.smanip]
      template<class T, class charT, class baggage>
      basic_ostream<charT,baggage>&
          operator<<(basic_ostream<charT,baggage>& os,
                     const basic_smanip<T,charT,baggage>& a);

1 Calls  (*a.pf)(os,  a.manarg)  and  catches any exception the function
  call  throws.   If  the  function  catches  an  exception,  it   calls
  os.setstate(basic_ios::failbit) (the exception is not rethrown).

2 Returns os.

  27.3.4  Standard manipulators                          [lib.std.manip]

  27.3.4.1  basic_resetiosflags                [lib.basic.resetiosflags]
      template<class charT, class baggage>
      basic_smanip<basic_ios<charT,baggage>::fmtflags>
          basic_resetiosflags(basic_ios<charT,baggage>::fmtflags mask);

1 Returns   basic_smanip<basic_ios<charT,baggage>::fmtflags>(&f,  mask),
  where f can be defined as:39)
      template<class charT, class baggage>
      basic_ios<charT,baggage>& f(basic_ios<charT,baggage>& str,
                                   basic_ios<charT,baggage>::fmtflags mask)
      { // reset specified flags
        str.setf((basic_ios<charT,baggage>::fmtflags)0, mask);
        return str;
      }

  27.3.4.2  basic_setiosflags                    [lib.basic.setiosflags]
      template<class charT, class baggage>
      basic_smanip<basic_ios<charT,baggage>::fmtflags>
          basic_setiosflags(basic_ios<charT,baggage>::fmtflags mask);

1 Returns     basic_smanip<basic_ios<charT,baggage>::fmtflags>(&f,mask),
  where f can be defined as:
      template<class charT, class baggage>
      basic_ios<charT,baggage>& f(basic_ios<charT,baggage>& str,
                                   basic_ios<charT,baggage>::fmtflags mask)
      { // set specified flags
        str.setf(mask);
        return str;
      }
  _________________________
  39)        The        expression        cin        >>         resetba­
  sic_iosflags(basic_ios<charT,baggage>::skipws)        clears       ba­
  sic_ios<charT,baggage>::skipws in the format flags stored in  the  ba­
  sic_istream  object cin (the same as cin >> noskipws), and the expres­
  sion cout  <<  resetbasic_iosflags(basic_ios<charT,baggage>::showbase)
  clears  basic_ios<charT,baggage>::showbase  in the format flags stored
  in the basic_ostream object cout (the same as cout << noshowbase).

  27.3.4.3  basic_setbase                            [lib.basic.setbase]
      template<class charT, class baggage>
      basic_smanip<int> basic_setbase(int base);

1 Returns basic_smanip<int>(&f, base), where f can be defined as:
      template<class charT, class baggage>
      basic_ios<charT,baggage>& f(basic_ios<charT,baggage>& str, int base)
      { // set basefield
        str.setf(n ==  8 ? basic_ios<charT,baggage>::oct :
                                 n == 10 ? basic_ios<charT,baggage>::dec :
                                 n == 16 ? basic_ios<charT,baggage>::hex :
                                 basic_ios<charT,baggage>::fmtflags(0),
                                 basic_ios<charT,baggage>::basefield);
        return str;
      }

  27.3.4.4  basic_setfill                            [lib.basic.setfill]
      basic_smanip<int> basic_setfill(int c);

1 Returns basic_smanip<int>(&f, c), where f can be defined as:
      template<class charT, class baggage>
      basic_ios<charT,baggage>& f(basic_ios<charT,baggage>& str, int c)
      { // set fill character
        str.fill(c);
        return str;
      }

  27.3.4.5  basic_setprecision                  [lib.basic.setprecision]
      template<class charT, class baggage>
      basic_smanip<int> basic_setprecision(int n);

1 Returns basic_smanip<int>(&f, n), where f can be defined as:
      template<class charT, class baggage>
      basic_ios<charT,baggage>& f(basic_ios<charT,baggage>& str, int n)
      { // set precision
        str.precision(n);
        return str;
      }

  27.3.4.6  basic_setw                                  [lib.basic.setw]
      template<class charT, class baggage>
      basic_smanip<int> basic_setw(int n);

1 Returns basic_smanip<int>(&f, n), where f can be defined as:
      template<class charT, class baggage>
      basic_ios<charT,baggage>& f(basic_ios<charT,baggage>& str, int n)
      { // set width
        str.width(n);
        return str;
      }

  +-------                BEGIN BOX 109               -------+
  [To Be Filled]
  +-------                 END BOX 109                -------+

  27.4  String-based streams                        [lib.string.streams]

1 Headers:

  --<sstream>

  --<strstream>

  --<cstdlib> ascii <-> numeric conversions

2 Table 17:

                   Table 17--Header <sstream> synopsis

      +------------------------------------------------------------+
      |       Type                          Name(s)                |
      +------------------------------------------------------------+
      |Template classes:                                           |
      |basic_istringstream   basic_ostringstream   basic_stringbuf |
      +------------------------------------------------------------+
      |Classes:              stringbuf             wstringbuf      |
      |                      istringstream         wistringstream  |
      |                      ostringstream         wostringstream  |
      +------------------------------------------------------------+

3 Table 18:

                  Table 18--Header <strstream> synopsis

  +-------                     BEGIN BOX 110                    -------+
  I believe that strstream is obsolete and should not be included in the
  standard.  The interface is klunky (a "technical term" meaning the de­
  scription is longer than it ought to be) and has been frequently crit­
  icized for making memory management hard.  sstream(or a class that us­
  es a general STL iterator) should be a replacement for it, not an  ad­
  dition.   I am not making an editorial proposal because I realize that
  this is likely to be controversial.  -- jss
  +-------                      END BOX 110                     -------+

  +--------------------------------------------------------------------+
  |  Type                             Name(s)                          |
  +--------------------------------------------------------------------+
  |Template   basic_istrstream   basic_ostrstream   basic_strstreambuf |
  |classes:                                                            |
  +--------------------------------------------------------------------+
  |Classes:   istrstream         ostrstream         strstreambuf       |
  +--------------------------------------------------------------------+

4 Table 19:

                   Table 19--Header <cstdlib> synopsis

                          +---------------------+
                          |Type      Name(s)    |
                          +---------------------+
                          |Functions:           |
                          |       atoi   strtod |
                          |       atol   strtol |
                          +---------------------+

5 SEE ALSO: ISO C subclause 7.10.1.

  27.4.1  char* streams                             [lib.str.strstreams]

1 The  header  <strstream>  defines  three  types  that associate stream
  buffers with character array objects and assist  reading  and  writing
  such objects.

  27.4.1.1  Template class basic_strstreambuf         [lib.strstreambuf]
  template <class charT, class baggage = ios_baggage<charT> >
  class basic_strstreambuf : public basic_streambuf<charT,baggage> {
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;
      int_type  eof()     { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }

  +-------                BEGIN BOX 111               -------+
  Note: null character constraint is needed in ios_baggage.
  +-------                 END BOX 111                -------+

  public:
      basic_strstreambuf(streamsize alsize_arg = 0);
      basic_strstreambuf(void* (*palloc_arg)(size_t),
          void (*pfree_arg)(void*));
      basic_strstreambuf(char_type* gnext_arg, streamsize n,
          char_type* pbeg_arg = 0);

  +-------                BEGIN BOX 112               -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 112                -------+

      basic_strstreambuf(unsigned char_type* gnext_arg, streamsize n,
          unsigned char_type* pbeg_arg = 0);
      basic_strstreambuf(signed char_type* gnext_arg, streamsize n,
          signed char_type* pbeg_arg = 0);
      basic_strstreambuf(const char_type* gnext_arg, streamsize n);

  +-------                BEGIN BOX 113               -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 113                -------+

      basic_strstreambuf(const unsigned char_type* gnext_arg, streamsize n);
      basic_strstreambuf(const signed char_type* gnext_arg, streamsize n);
      virtual ~basic_strstreambuf();
      void freeze(bool = 1);
      char_type* str();
      int pcount();
  protected:
  //  virtual int_type overflow (int_type c = eof());    inherited
  //  virtual int_type pbackfail(int_type c = eof());    inherited

  +-------                BEGIN BOX 114               -------+
  The following was not part of the proposal.  Should we keep it?
  +-------                 END BOX 114                -------+

  //  virtual int      showmany();    inherited
  //  virtual int_type underflow();    inherited
  //  virtual int_type uflow();    inherited
  //  virtual streamsize xsgetn(char_type* s, streamsize n);    inherited
  //  virtual streamsize xsputn(const char_type* s, streamsize n);    inherited
  //  virtual pos_type seekoff(off_type off,
  //          basic_ios<charT,baggage>::seekdir way,
  //          basic_ios<charT,baggage>::openmode which
  //            = basic_ios<charT,baggage>::in | basic_ios<charT,baggage>::out);    inherited
  //  virtual pos_type seekpos(pos_type sp,
  //          basic_ios<charT,baggage>::openmode which
  //            = basic_ios<charT,baggage>::in | basic_ios<charT,baggage>::out);    inherited
  //  virtual basic_streambuf<char_type,baggage>*
  //      setbuf(char_type* s, streamsize n);     inherited
  //  virtual int sync(); inherited
  private:
  //  typedef T1 strstate;                exposition only
  //  static const strstate allocated;    exposition only
  //  static const strstate constant;     exposition only
  //  static const strstate dynamic;      exposition only
  //  static const strstate frozen;       exposition only
  //  strstate strmode;                   exposition only
  //  streamsize alsize;                  exposition only
  //  void* (*palloc)(size_t);            exposition only
  //  void (*pfree)(void*);               exposition only
  };

1 The    class   basic_strstreambuf<charT,baggage>   is   derived   from
  basic_streambuf<charT,baggage> to associate  the  input  sequence  and
  possibly  the  output  sequence with an object of some character array
  type, whose elements store arbitrary values.   The  array  object  has
  several attributes.

2 For  the  sake  of  exposition, these are represented as elements of a
  bitmask type (indicated here as T1)  called  strstate.   The  elements
  are:

  --allocated,  set  when a dynamic array object has been allocated, and
    hence should be freed by the destructor for  the  basic_strstreambuf
    object;

  --constant,  set when the array object has const elements, so the out­
    put sequence cannot be written;

  --dynamic, set when the array object is allocated (or reallocated)  as
    necessary to hold a character sequence that can change in length;

  --frozen, set when the program has requested that the array object not
    be altered, reallocated, or freed.

3 For the sake of exposition, the maintained data is presented here as:

  --strstate strmode, the attributes of the array object associated with
    the basic_strstreambuf object;

  --int alsize, the suggested minimum size for a dynamic array object;

  --void*  (*palloc)(size_t), points to the function to call to allocate
    a dynamic array object;

  --void (*pfree)(void*), points to the  function  to  call  to  free  a
    dynamic array object.

4 Each  object of class basic_strstreambuf<charT,baggage> has a seekable
  area, delimited by the pointers seeklow and seekhigh.  If gnext  is  a
  null  pointer,  the  seekable  area  is undefined.  Otherwise, seeklow
  equals gbeg and seekhigh is  either  pend,  if  pend  is  not  a  null
  pointer, or gend.

  27.4.1.1.1  basic_strstreambuf           [lib.basic.strstreambuf.cons]
       constructors
      basic_strstreambuf(streamsize alsize_arg = 0);

1 Constructs an object of  class  basic_strstreambuf,  initializing  the
  base  class  with basic_streambuf().  The postconditions of this func­
  tion are indicated in Table 20:

             Table 20--basic_strstreambuf(streamsize) effects

                        +-------------------------+
                        |Element       Value      |
                        +-------------------------+
                        |strmode   dynamic        |
                        |alsize    alsize_arg     |
                        |palloc    a null pointer |
                        |pfree     a null pointer |
                        +-------------------------+
      basic_strstreambuf(void* (*palloc_arg)(size_t), void (*pfree_arg)(void*));

2 Constructs an object of  class  basic_strstreambuf,  initializing  the
  base  class  with basic_streambuf().  The postconditions of this func­
  tion are indicated in Table 21:

  Table 21--basic_strstreambuf(void* (*)(size_t),void (*)(void*) effects

                     +-------------------------------+
                     |Element          Value         |
                     +-------------------------------+
                     |strmode   dynamic              |
                     |alsize    an unspecified value |
                     |palloc    palloc_arg           |
                     |pfree     pfree_arg            |
                     +-------------------------------+
      basic_strstreambuf(char_type* gnext_arg,
          streamsize n,
          char_type *pbeg_arg = 0);

3 Constructs an object of  class  basic_strstreambuf,  initializing  the
  base  class  with basic_streambuf().  The postconditions of this func­
  tion are indicated in Table 22:

      Table 22--basic_strstreambuf(charT*,streamsize,charT*) effects

                     +-------------------------------+
                     |Element          Value         |
                     +-------------------------------+
                     |strmode   0                    |
                     |alsize    an unspecified value |
                     |palloc    a null pointer       |
                     |pfree     a null pointer       |
                     +-------------------------------+

4 gnext_arg shall point to the first element of an  array  object  whose
  number of elements N is determined as follows:

  --If n > 0, N is n.

  --If n == 0, N is strlen(gnext_arg).

  +-------                BEGIN BOX 115               -------+
  Needs work, regarding charT length.
  +-------                 END BOX 115                -------+

  --If n < 0, N is INT_MAX.  40)
  _________________________
  40)   The  function  signature  strlen(const  char*)  is  declared  in
  <cstring>  (_lib.c.strings_).   The  macro  INT_MAX  is   defined   in

5 If pbeg_arg is a null pointer, the function executes:
    setg(gnext_arg, gnext_arg, gnext_arg + N);

6 Otherwise, the function executes:
    setg(gnext_arg, gnext_arg, pbeg_arg);
    setp(pbeg_arg,  pbeg_arg + N);

  +-------                BEGIN BOX 116               -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 116                -------+

      basic_strstreambuf(unsigned char_type* gnext_arg,
                         streamsize n,
                         unsigned char_type* pbeg_arg = 0);

7 Behaves  the  same  as  basic_strstreambuf((char_type*)gnext_arg,   n,
  (char_type*)pbeg_arg).
      basic_strstreambuf(signed char_type* gnext_arg,
                         streamsize n,
                         signed char_type* pbeg_arg = 0);

8 Behaves   the  same  as  basic_strstreambuf((char_type*)gnext_arg,  n,
  (char_type*)pbeg_arg).
      basic_strstreambuf(const char_type* gnext_arg, streamsize n);

9 Behaves  the  same  as  basic_strstreambuf((char_type*)gnext_arg,  n),
  except that the constructor also sets constant in strmode.

  +-------                BEGIN BOX 117               -------+
  The following two were not part of the proposal.  Should we keep them?
  +-------                 END BOX 117                -------+

      basic_strstreambuf(const unsigned char_type* gnext_arg, streamsize n);

10Behaves the same as basic_strstreambuf((const char_type*)gnext_arg,n).
      basic_strstreambuf(const signed char_type* gnext_arg, streamsize n);

11Behaves the same as basic_strstreambuf((const char_type*)gnext_arg,n).

  27.4.1.1.2  basic_strstreambuf            [lib.basic.strstreambuf.des]
       destructor
      virtual ~basic_strstreambuf();

1 Destroys  an  object  of class basic_strstreambuf.  The function frees
  the dynamically allocated array object only if strmode & allocated  is
  nonzero    and    strmode    &    frozen    is    zero.     (Subclause
  _basic_strstreambuf::overflow_ describes how a  dynamically  allocated
  array object is freed.)

  _________________________
  <climits> (_lib.support.limits_).

  27.4.1.1.3  basic_strstreambuf::freeze      [lib.strstreambuf::freeze]
      void freeze(bool freezefl = 1);

1 If strmode & dynamic is non-zero, alters  the  freeze  status  of  the
  dynamic  array  object  as follows: If freezefl is false, the function
  sets frozen in strmode.  Otherwise, it clears frozen in strmode.

  27.4.1.1.4  basic_strstreambuf::str            [lib.strstreambuf::str]
      char_type* str();

1 Calls freeze(), then returns  the  beginning  pointer  for  the  input
  sequence, gbeg.41)

  27.4.1.1.5  basic_strstreambuf::pcount      [lib.strstreambuf::pcount]
      int pcount() const;

1 If the next pointer for the output sequence, pnext, is a null pointer,
  returns  zero.  Otherwise, returns the current effective length of the
  array object as the next pointer minus the beginning pointer  for  the
  output sequence, pnext - pbeg.

  27.4.1.1.6                                [lib.strstreambuf::overflow]
       basic_strstreambuf::overflow
  //  virtual int_type overflow(int_type c = eof());    inherited

  +-------                BEGIN BOX 118               -------+
  This needs to be rewritten in terms of consuming characters to be con­
  sistent with the revised protocol for overflow.
  +-------                 END BOX 118                -------+

1 Appends  the character designated by c to the output sequence, if pos­
  sible, in one of two ways:

  --If c != eof() and if either the output sequence has a write position
    available  or  the  function  makes  a  write position available (as
    described below), assigns c to *pnext++.

    Returns (char_type)c.

  --If c == eof(), there is no character to append.

    Returns a value other than eof().

2 Returns eof() to indicate failure.

3 Notes:

4 The function can alter the number of write positions  available  as  a
  result of any call.

  _________________________
  41) The return value can be a null pointer.

5 To  make a write position available, the function reallocates (or ini­
  tially allocates) an array object with a sufficient number of elements
  n  to  hold the current array object (if any), plus at least one addi­
  tional write position.  How many additional write positions  are  made
  available is  otherwise  unspecified.42)  If  palloc  is  not  a  null
  pointer,  the  function calls (*palloc)(n) to allocate the new dynamic
  array object.  Otherwise, it evaluates the  expression  new  charT[n].
  In  either  case, if the allocation fails, the function returns eof().
  Otherwise, it sets allocated in strmode.

6 To free a previously existing dynamic array object whose first element
  address  is  p:  If  pfree  is  not a null pointer, the function calls
  (*pfree)(p).  Otherwise, it evaluates the expression delete[] p.

7 If strmode & dynamic is zero, or if strmode & frozen is  nonzero,  the
  function  cannot  extend the array (reallocate it with greater length)
  to make a write position available.

  27.4.1.1.7                               [lib.strstreambuf::pbackfail]
       basic_strstreambuf::pbackfail
  //  virtual int_type pbackfail(int_type c = eof());    inherited

  +-------                BEGIN BOX 119               -------+
  This needs to be rewritten in terms of consuming characters to be con­
  sistent with the revised protocol for pbackfail..
  +-------                 END BOX 119                -------+

1 Puts back the character designated by c to the input sequence, if pos­
  sible, in one of three ways:

  --If  c  != eof(), if the input sequence has a putback position avail­
    able, and if (char_type)c == char_type)gnext[-1], assigns gnext -  1
    to gnext.

    Returns (char_type)c.

  --If  c  != eof(), if the input sequence has a putback position avail­
    able, and if strmode & constant is zero, assigns c to *--gnext.

    Returns (char_type)c.

  --If c == eof() and if the  input  sequence  has  a  putback  position
    available, assigns gnext - 1 to gnext.

    Returns (char_type)c.

2 Returns eof() to indicate failure.

3 Notes:

  _________________________
  42)  An implementation should consider alsize in making this decision.

  +-------                BEGIN BOX 120               -------+
  Cannot distinguish success and failure if c == EOF.
  +-------                 END BOX 120                -------+

4 If  the  function  can  succeed  in more than one of these ways, it is
  unspecified which way is chosen.  The function can alter the number of
  putback positions available as a result of any call.

  +-------                BEGIN BOX 121               -------+
  The following was not part of the proposal.  Should we keep it?
  +-------                 END BOX 121                -------+

  27.4.1.1.8                                [lib.strstreambuf::showmany]
       basic_strstreambuf::showmany
  //  virtual int showmany();    inherited

1 Behaves the same as basic_streambuf::showmany(int).

  27.4.1.1.9                               [lib.strstreambuf::underflow]
       basic_strstreambuf::underflow
  //  virtual int_type underflow();    inherited

  +-------                BEGIN BOX 122               -------+
  This needs to be rewritten in terms of consuming characters to be con­
  sistent with the revised protocol for underflow..
  +-------                 END BOX 122                -------+

1 Reads a character from the input sequence, if possible, without moving
  the stream position past it, as follows:

  --If  the  input  sequence  has a read position available the function
    signals success by returning (char_type)*gnext.

  --Otherwise, if the current write next pointer pnext  is  not  a  null
    pointer and is greater than the current read end pointer gend, makes
    a read position available by: assigning to gend a value greater than
    gnext and no greater than pnext.

    Returns (char_type)*gnext.

2 Returns eof() to indicate failure.

3 Notes:

4 The  function  can  alter  the number of read positions available as a
  result of any call.

  27.4.1.1.10  basic_strstreambuf::uflow       [lib.strstreambuf::uflow]
  //  virtual int_type uflow();    inherited

1 Behaves the same as basic_streambuf::uflow().

  27.4.1.1.11                                 [lib.strstreambuf::xsgetn]
       basic_strstreambuf::xsgetn
  //  virtual streamsize xsgetn(char_type* s, streamsize n);    inherited

1 Behaves the same as basic_streambuf::xsgetn(s,n).

  27.4.1.1.12                                 [lib.strstreambuf::xsputn]
       basic_strstreambuf::xsputn
  //  virtual int xsputn(const char_type* s, streamsize n);    inherited

1 Behaves the same as basic_streambuf::xsputn(s,n).

  27.4.1.1.13                                [lib.strstreambuf::seekoff]
       basic_strstreambuf::seekoff
  //  virtual pos_type seekoff(off_type off, seekdir way,
  //      openmode which = in | out);    inherited

  +-------                BEGIN BOX 123               -------+
  Check vs. _lib.stringbuf::seekoff_
  +-------                 END BOX 123                -------+

1 Alters  the stream position within one of the controlled sequences, if
  possible, as indicated in Table 23:

                      Table 23--seekoff positioning

  +----------------------------------------------------------------------------+
  |        Conditions                              Result                      |
  +----------------------------------------------------------------------------+
  (which & basic_ios::in) != 0positions the input sequence                     |
  +----------------------------------------------------------------------------+
  (which& basic_ios::out) != 0positions the output sequence                    |
  +----------------------------------------------------------------------------+
  |Otherwise,                                                                   |
  (which & (basic_ios::in |   positions both the input and the output sequences|
  basic_ios::out)) == (ba­                                                     |
  sic_ios::in | ba­                                                            |
  sic_ios::out))                                                               |
  |and way == either ba­                                                        |
  sic_ios::beg or ba­                                                          |
  sic_ios::end                                                                 |
  +----------------------------------------------------------------------------+
  |Otherwise,                  the positioning operation fails.                 |
  +----------------------------------------------------------------------------+

  +-------                BEGIN BOX 124               -------+
  Comment:  this condition is unclear.  If the 2nd condition is true, is
  the 1st condition always true?  If so, the 2nd  operation  may  occur,
  mayn't it?
  +-------                 END BOX 124                -------+

2 For  a  sequence  to  be  positioned,  if  its  next pointer is a null
  pointer, the positioning operation  fails.   Otherwise,  the  function
  determines newoff as indicated in Table 24:

                         Table 24--newoff values

        +---------------------------------------------------------+
        |      Condition                   newoff Value           |
        +---------------------------------------------------------+
        |way == basic_ios::beg    0                               |
        +---------------------------------------------------------+
        |way == basic_ios::cur    the next pointer minus the be­  |
        |                         ginning pointer (xnext - xbeg)  |
        +---------------------------------------------------------+
        |way == basic_ios::end    seekhigh minus the beginning    |
        |                         pointer (seekhigh - xbeg)       |
        +---------------------------------------------------------+
        |If (newoff + off) <      the positioning operation fails |
        |(seeklow - xbeg),                                        |
        |or (seekhigh - xbeg) <                                   |
        |(newoff + off)                                           |
        +---------------------------------------------------------+

3 Otherwise,  the  function  assigns  xbeg  +  newoff  + off to the next
  pointer xnext.

4 Returns pos_type(newoff), constructed from the resultant offset newoff
  (of type off_type), that stores the resultant stream position, if pos­
  sible.  If the positioning operation  fails,  or  if  the  constructed
  object  cannot  represent  the  resultant  stream position, the object
  stores an invalid stream position.

  +-------                BEGIN BOX 125               -------+
  Note: Need posT object which stores an invalid stream position.   Com­
  ment:  Not clear if the constructed object cannot represent the resul­
  tant stream position
  +-------                 END BOX 125                -------+

  27.4.1.1.14                                [lib.strstreambuf::seekpos]
       basic_strstreambuf::seekpos
  //  virtual pos_type seekpos(pos_type sp,
  //      basic_ios<charT,baggage>::openmode which
  //          = basic_ios<charT,baggage>::in | basic_ios<charT,baggage>::out);    inherited

  +-------                BEGIN BOX 126               -------+
  Check vs. _lib.stringbuf::seekpos_
  +-------                 END BOX 126                -------+

1 Alters  the stream position within one of the controlled sequences, if
  possible, to correspond to  the  stream  position  stored  in  sp  (as
  described below).

  --If (which & basic_ios::in) != 0, positions the input sequence.

  --If (which & basic_ios::out) != 0, positions the output sequence.

  --If  the  function positions neither sequence, the positioning opera­
    tion fails.

2 For a sequence to be  positioned,  if  its  next  pointer  is  a  null
  pointer,  the  positioning  operation  fails.  Otherwise, the function
  determines newoff from sp.offset():

  --If newoff is an invalid stream position, has a  negative  value,  or
    has a value greater than (seekhigh - seeklow), the positioning oper­
    ation fails

  --Otherwise, the function adds newoff to the  beginning  pointer  xbeg
    and stores the result in the next pointer xnext.

3 Returns pos_type(newoff), constructed from the resultant offset newoff
  (of type off_type), that stores the resultant stream position, if pos­
  sible.   If  the  positioning  operation  fails, or if the constructed
  object cannot represent the  resultant  stream  position,  the  object
  stores an invalid stream position.

4
  27.4.1.1.15                                 [lib.strstreambuf::setbuf]
       basic_strstreambuf::setbuf
  //  virtual basic_streambuf<char_type,baggage>*
  //      setbuf(char_type* s, streamsize n);    inherited

1 Performs an operation  that  is  defined  separately  for  each  class
  derived from basic_strstreambuf.

  +-------                BEGIN BOX 127               -------+
  Should be pure virtual.
  +-------                 END BOX 127                -------+

2 Default behavior:  the same as for basic_streambuf::setbuf(char_type*,
  streamsize).

  27.4.1.1.16  basic_strstreambuf::sync         [lib.strstreambuf::sync]
  //  virtual int sync();    inherited

1 Behaves the same as basic_streambuf::sync().

  27.4.1.2  Template class basic_istrstream             [lib.istrstream]
  template<class charT, class baggage = int_baggage<charT> >
      class basic_istrstream : public basic_istream<charT,baggage> {
      public:
          typedef charT char_type;
          typedef baggage::char_bag::int_type int_type;
          typedef baggage::pos_bag::pos_type  pos_type;
          typedef baggage::pos_bag::off_type  off_type;
          int_type  eof()     { return baggage::char_bag::eof(); }
          char_type newline() { return baggage::char_bag::newline(); }
      public:
          basic_istrstream(const char_type* s);
          basic_istrstream(const char_type* s, streamsize n);
          basic_istrstream(char_type* s);
          basic_istrstream(char_type* s, streamsize n);
          virtual ~basic_istrstream();
          basic_strstreambuf<char_type,baggage>* rdbuf() const;
          char *str();
      private:
  //      basic_strstreambuf<char_type,baggage> sb;       exposition only
  //      typedef basic_strstreambuf<char_type,baggage> sb_type;   exposition only
  };

1 The  class  basic_istrstream  is  a  derivative  of basic_istream that
  assists in the reading of objects  of  class  basic_strstreambuf.   It
  supplies  a  basic_strstreambuf object to control the associated array
  object.

2 For the sake of exposition, the maintained data is presented here as:

  --sb, the basic_strstreambuf object.

  27.4.1.2.1  basic_istrstream               [lib.basic.istrstream.cons]
       constructors
      basic_istrstream(const char_type* s);

1 Constructs  an object of class basic_istrstream, initializing the base
  class with basic_istream(&sb), and initializing sb with sb_type(s, 0).
  s shall designate the first element of an NTBS.

  +-------                BEGIN BOX 128               -------+
  Needs work, NTBS.
  +-------                 END BOX 128                -------+

      basic_istrstream(const char_type* s, streamsize n);

2 Constructs  an object of class basic_istrstream, initializing the base
  class with basic_istream(&sb), and initializing sb with sb_type(s, n).
  s  shall  designate  the  first  element of an array whose length is n

  elements, and n shall be greater than zero.
      basic_istrstream(char_type* s);

3 Constructs  an object of class basic_istrstream, initializing the base
  class with basic_istream(&sb), and initializing sb with sb_type((const
  char_type*)s,0).  s shall designate the first element of an NTBS.

  +-------                BEGIN BOX 129               -------+
  Needs work, NTBS.
  +-------                 END BOX 129                -------+

      basic_istrstream(char_type* s, streamsize n);

4 Constructs  an object of class basic_istrstream, initializing the base
  class with basic_istream(&sb), and initializing sb with sb_type((const
  char_type*)s,n).   s  shall  designate  the  first element of an array
  whose length is n elements, and n shall be greater than zero.

  27.4.1.2.2  basic_istrstream                [lib.basic.istrstream.des]
       destructor
      virtual ~basic_istrstream();

1 Destroys an object of class basic_istrstream.

  27.4.1.2.3  basic_istrstream::rdbuf            [lib.istrstream::rdbuf]
      basic_strstreambuf* rdbuf() const;

1 Returns (basic_strstreambuf*)&sb.

  27.4.1.2.4  basic_istrstream::str                [lib.istrstream::str]
      char_type* str();

1 Returns sb.str().

  27.4.1.3  Template class basic_ostrstream             [lib.ostrstream]
      template <class charT, class baggage = int_baggage<charT> >
      class basic_ostrstream : public ostream<charT,baggage> {
      public:
          typedef charT char_type;
          typedef baggage::char_bag::int_type int_type;
          typedef baggage::pos_bag::pos_type  pos_type;
          typedef baggage::pos_bag::off_type  off_type;
          int_type  eof()     { return baggage::char_bag::eof(); }
          char_type newline() { return baggage::char_bag::newline(); }

      public:
          basic_ostrstream();
          basic_ostrstream(char_type* s, int n,
                           basic_ios<charT,baggage>::openmode mode
                               = basic_ios<charT,baggage>::out);
          virtual ~basic_ostrstream();
          basic_strstreambuf<char_type,baggage>* rdbuf() const;
          void freeze(int freezefl = 1);
          char_type* str();
          int pcount() const;
      private:
  //      basic_strstreambuf<char_type,baggage> sb;       exposition only
  //      typedef basic_strstreambuf<char_type,baggage> sb_type;    exposition only
  };

1 The class basic_ostrstream  is  a  derivative  of  basic_ostream  that
  assists  in  the  writing  of objects of class basic_strstreambuf.  It
  supplies a basic_strstreambuf object to control the  associated  array
  object.

2 For the sake of exposition, the maintained data is presented here as:

  --sb, the basic_strstreambuf object.

  27.4.1.3.1  basic_ostrstream               [lib.basic.ostrstream.cons]
       constructors
      basic_ostrstream();

1 Constructs an object of class basic_ostrstream, initializing the  base
  class with basic_ostream(&sb), and initializing sb with sb_type().
      basic_ostrstream(char_type* s, int n,
          basic_ios<charT,baggage>::openmode mode = basic_ios<charT,baggage>::out);

2 Constructs  an object of class basic_ostrstream, initializing the base
  class with basic_ostream(&sb), and initializing sb  with  one  of  two
  constructors:

  --If  mode  & app is zero, then s shall designate the first element of
    an array of n elements.  The constructor is sb_type(s, n, s).

  --If mode & app is nonzero, then s shall designate the  first  element
    of  an array of n elements that contains an NTBS whose first element
    is designated by s.

  +-------                BEGIN BOX 130               -------+
  Needs work, NTBS and length().
  +-------                 END BOX 130                -------+

  The constructor is sb_type(s, n, s + ::strlen(s)).  43)

  _________________________
  43) The function signature strlen(const  char_type*)  is  declared  in
  <cstring> (_lib.file.streams_).

  27.4.1.3.2  basic_ostrstream                [lib.basic.ostrstream.des]
       destructor
      virtual ~basic_ostrstream();

1 Destroys an object of class basic_ostrstream.

  27.4.1.3.3  basic_ostrstream::rdbuf            [lib.ostrstream::rdbuf]
      basic_strstreambuf* rdbuf() const;

1 Returns (basic_strstreambuf*)&sb.

  27.4.1.3.4  basic_ostrstream::freeze          [lib.ostrstream::freeze]
      void freeze(int freezefl = 1);

1 Calls sb.freeze(freezefl).

  27.4.1.3.5  basic_ostrstream::str                [lib.ostrstream::str]
      char_type* str();

1 Returns sb.str().

  27.4.1.3.6  basic_ostrstream::pcount          [lib.ostrstream::pcount]
      int pcount() const;

1 Returns sb.pcount().

  27.4.2  string streams                         [lib.string.strstreams]

1 The header <sstream> defines three types that associate stream buffers
  with objects of class string, as described in clause _lib.string_.

  27.4.2.1  Template class basic_stringbuf               [lib.stringbuf]

  +-------                BEGIN BOX 131               -------+
  When strings are rationalized with STL, that is when they become  con­
  tainers  with  iterators,  this class ought to be replaced by a method
  that uses a general STL container.
  +-------                 END BOX 131                -------+

  template <class charT, class baggage = int_charT_baggage<charT> >
  class basic_stringbuf : public basic_streambuf<charT,baggage> {
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;
      int_type  eof()     { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }

  public:
      basic_stringbuf(basic_ios<charT,baggage>::openmode which
                          = basic_ios<charT,baggage>::in
                          | basic_ios<charT,baggage>::out);
      basic_stringbuf(const basic_string<char_type>& str,
                      basic_ios<charT,baggage>::openmode which
                          = basic_ios<charT,baggage>::in
                          | basic_ios<charT,baggage>::out);
      virtual ~basic_stringbuf();
      basic_string<char_type> str() const;
      void str(const basic_string<char_type>& str_arg);
  protected:
  //  virtual int_type   overflow (int_type c = eof());   inherited
  //  virtual int_type   pbackfail(int_type c = eof());   inherited

  +-------                BEGIN BOX 132               -------+
  The following was not part of the proposal.  Should we keep it?
  +-------                 END BOX 132                -------+

  //  virtual int        showmany();      inherited
  //  virtual int_type   underflow();     inherited
  //  virtual int_type   uflow();         inherited
  //  virtual streamsize xsgetn(char_type* s, streamsize n);      inherited
  //  virtual streamsize xsputn(const char_type* s, streamsize n);        inherited
  //  virtual pos_type   seekoff(off_type off,
  //                             basic_ios<charT,baggage>::seekdir way,
  //                             basic_ios<charT,baggage>::openmode which
  //                               = basic_ios<charT,baggage>::in
  //                               | basic_ios<charT,baggage>::out);      inherited
  //  virtual pos_type   seekpos(pos_type sp,
  //                             basic_ios<charT,baggage>::openmode which
  //                               = basic_ios<charT,baggage>::in
  //                               | basic_ios<charT,baggage>::out);      inherited
  //  virtual basic_streambuf<char_type,baggage>*
  //                     setbuf(char_type* s, streamsize n);      inherited
  //  virtual int sync();         inherited
  private:
  //  basic_ios<charT,baggage>::openmode mode;    exposition only
  };

  +-------                BEGIN BOX 133               -------+
  The descriptions of the virtuals in this class need to be brought into
  agreement with the new descriptions of the generic protocols.  As part
  of that we have

1 Jerry Schwarz proposal:
  //
  //  string             data ; exposition only
  +-------                 END BOX 133                -------+

      class stringbuf : public basic_stringbuf<char> {};
      class wstringbuf : public basic_stringbuf<wchar_t> {};

  +-------                BEGIN BOX 134               -------+

  Note: same charT type string can be fed.
  +-------                 END BOX 134                -------+

2 The class basic_stringbuf is derived from basic_streambuf to associate
  possibly  the  input  sequence and possibly the output sequence with a
  sequence of arbitrary characters.  The  sequence  can  be  initialized
  from, or made available as, an object of class basic_string.

  +-------                BEGIN BOX 135               -------+
  [To Be Filled]
  +-------                 END BOX 135                -------+

3 For the sake of exposition, the maintained data is presented here as:

  --basic_ios<charT,baggage>::openmode  mode,  has  in  set if the input
    sequence can be read, and out set if  the  output  sequence  can  be
    written.

4 For the sake of exposition, the stored character sequence is described
  here as an array object.

  27.4.2.1.1  basic_stringbuf                 [lib.basic.stringbuf.cons]
       constructors
      basic_stringbuf(basic_ios<charT,baggage>::openmode which
                          = basic_ios<charT,baggage>::in
                          | basic_ios<charT,baggage>::out);

1 Constructs  an  object of class basic_stringbuf, initializing the base
  class with basic_streambuf(), and initializing mode with  which.   The
  function allocates no array object.
      basic_stringbuf(const basic_string<char_type>& str,
                      basic_ios<charT,baggage>::openmode which
                          = basic_ios<charT,baggage>::in
                          | basic_ios<charT,baggage>::out);

2 Constructs  an  object of class basic_stringbuf, initializing the base
  class with basic_streambuf(), and initializing mode with which.

3 If str.length() is nonzero, the function allocates an array  object  x
  whose length n is str.length() and whose elements x[I] are initialized
  to str[I].  If which & basic_ios::in is  nonzero,  the  function  exe­
  cutes:
    setg(x, x, x + n);

4 If which & basic_ios::out is nonzero, the function executes:
    setp(x, x + n);

  27.4.2.1.2  basic_stringbuf destructor       [lib.basic.stringbuf.des]
      virtual ~basic_stringbuf();

1 Destroys an object of class basic_stringbuf.

  27.4.2.1.3  basic_stringbuf::str                  [lib.stringbuf::str]
      basic_string<char_type> str() const;
  The return value of this function are indicated in Table 25:

                       Table 25--str return values

  +---------------------------------------------------------------------+
  |       Condition                         Return Value                |
  +---------------------------------------------------------------------+
  |(mode & basic_ios::in)     basic_string<char_type>(gbeg,gend - gbeg) |
  |!= 0 and (gnext != 0)                                                |
  +---------------------------------------------------------------------+
  |(mode & basic_ios::out)    basic_string<char_type>(pbeg,pptr - pbeg) |
  |!= 0 and (pnext != 0                                                 |
  +---------------------------------------------------------------------+
  |Otherwise                  basic_string<char_type>()                 |
  +---------------------------------------------------------------------+
      void str(const basic_string<char_type>& str_arg);

1 If str_arg.length() is zero, executes:
    setg(0, 0, 0);
    setp(0, 0);

2 and frees storage for any associated  array  object.   Otherwise,  the
  function   allocates   an   array   object   x   whose   length  n  is
  str_arg.length()  and  whose  elements   x[I]   are   initialized   to
  str_arg[I].   If  which & basic_ios<charT,baggage>::in is nonzero, the
  function executes:
    setg(x, x, x + n);

3 If which & basic_ios<charT,baggage>::out is nonzero, the function exe­
  cutes:
    setp(x, x + n);

  27.4.2.1.4  basic_stringbuf::overflow        [lib.stringbuf::overflow]
  //  virtual int_type overflow(int_type c = eof());    inherited

1 Appends  the character designated by c to the output sequence, if pos­
  sible, in one of two ways:

  --If c != eof() and if either the output sequence has a write position
    available  or  the  function  makes  a  write position available (as
    described below), the function assigns c to *pnext++.  The  function
    signals success by returning (char_type)c.

  --If  c  == eof(), there is no character to append.  The function sig­
    nals success by returning a value other than eof().

2 The function can alter the number of write positions  available  as  a
  result of any call.

3 Returns eof() to indicate failure.

4 The  function  can  make  a  write  position available only if (mode &
  basic_ios<charT,baggage>::out) != 0.  To make a write position  avail­
  able,  the  function  reallocates  (or  initially  allocates) an array
  object with a sufficient number of elements to hold the current  array
  object  (if  any),  plus  one  additional  write position.  If (mode &
  basic_ios<charT,baggage>::in) != 0, the function alters the  read  end
  pointer  gend  to  point just past the new write position (as does the
  write end pointer pend).

  27.4.2.1.5  basic_stringbuf::pbackfail      [lib.stringbuf::pbackfail]
  //  virtual int_type pbackfail(int_type c = eof());    inherited

  +-------                BEGIN BOX 136               -------+
  Check vs. _lib.streambuf::pbackfail_ and _lib.filebuf::pbackfail_
  +-------                 END BOX 136                -------+

1 Puts back the character designated by c to the input sequence, if pos­
  sible, in one of three ways:

  --If c != eof(), if the input sequence has a putback  position  avail­
    able, and if (char_type)c == (char_type)gnext[-1], assigns gnext - 1
    to gnext.

    Returns (char_type)c.

  --If c != eof(), if the input sequence has a putback  position  avail­
    able,  and  if  mode  &  basic_ios<charT,baggage>::out  is  nonzero,
    assigns c to *--gnext.

    Returns (char_type)c.

  --If c == eof() and if the  input  sequence  has  a  putback  position
    available, assigns gnext - 1 to gnext.

    Returns (char_type)c.

2 Returns eof() to indicate failure.

3 Notes:

4 If  the  function  can  succeed  in more than one of these ways, it is
  unspecified which way is chosen.

  +-------                BEGIN BOX 137               -------+
  The following was not part of the proposal.  Should we keep it?
  +-------                 END BOX 137                -------+

  27.4.2.1.6  basic_stringbuf::showmany        [lib.stringbuf::showmany]
  //  virtual int showmany();    inherited

1 Behaves the same as basic_streambuf<charT,baggage>::showmany().

  27.4.2.1.7  basic_stringbuf::underflow      [lib.stringbuf::underflow]
  //  virtual int_type underflow();    inherited

1 If   the  input  sequence  has  a  read  position  available,  returns
  (char_type)*gnext.  Otherwise, returns eof().

  27.4.2.1.8  basic_stringbuf::uflow              [lib.stringbuf::uflow]
  //  virtual int_type uflow();    inherited

1 Behaves the same as basic_streambuf<charT,baggage>::uflow().

  27.4.2.1.9  basic_stringbuf::xsgetn            [lib.stringbuf::xsgetn]
  //  virtual streamsize xsgetn(char_type* s, streamsize n);    inherited

1 Behaves the same as basic_streambuf<charT,baggage>::xsgetn(s,n).

  27.4.2.1.10  basic_stringbuf::xsputn           [lib.stringbuf::xsputn]
  //  virtual streamsize xsputn(const char_type* s, streamsize n);    inherited

1 Behaves the same as basic_streambuf<charT,baggage>::xsputn(s,n).

  27.4.2.1.11  basic_stringbuf::seekoff         [lib.stringbuf::seekoff]
  //  virtual pos_type seekoff(off_type off, basic_ios<charT,baggage>::seekdir way,
  //                           basic_ios<charT,baggage>::openmode which
  //                               = basic_ios<charT,baggage>::in | basic_ios<charT,baggage>::out);    inherited

  +-------                BEGIN BOX 138               -------+
  Check vs. _lib.strstreambuf::seekpos_
  +-------                 END BOX 138                -------+

1 Alters the stream position within one of the controlled sequences,  if
  possible, as indicated in Table 26:

                      Table 26--seekoff positioning

  +----------------------------------------------------------------------------+
  |        Conditions                              Result                      |
  +----------------------------------------------------------------------------+
  (which & basic_ios::in) != 0positions the input sequence                     |
  +----------------------------------------------------------------------------+
  (which& basic_ios::out) != 0positions the output sequence                    |
  +----------------------------------------------------------------------------+
  |Otherwise,                                                                   |
  (which & (basic_ios::in |   positions both the input and the output sequences|
  basic_ios::out)) == (ba­                                                     |
  sic_ios::in | ba­                                                            |
  sic_ios::out))                                                               |
  |and way == either ba­                                                        |
  sic_ios::beg or ba­                                                          |
  sic_ios::end                                                                 |
  +----------------------------------------------------------------------------+
  Otherwise,                  the positioning operation fails.                 |
  +----------------------------------------------------------------------------+

2 For a sequence to be  positioned,  if  its  next  pointer  is  a  null
  pointer,  the  positioning  operation  fails.  Otherwise, the function
  determines newoff as indicated in Table 27:

                         Table 27--newoff values

        +--------------------------------------------------------+
        |      Condition                  newoff Value           |
        +--------------------------------------------------------+
        |way == basic_ios::beg   0                               |
        +--------------------------------------------------------+
        |way == basic_ios::cur   the next pointer minus the be­  |
        |                        ginning pointer (xnext - xbeg). |
        +--------------------------------------------------------+
        |way == basic_ios::end   the end pointer minus the be­   |
        |                        ginning pointer (xend - xbeg)   |
        +--------------------------------------------------------+
        |If                                                      |
        |(newoff + off) < 0,                                     |
        |or                                                      |
        |(xend - xbeg) <                                         |
        |(newoff + off)                                          |
        |T}                      the positioning operation fails |
        +--------------------------------------------------------+

3 Otherwise,  the  function  assigns  xbeg  +  newoff  + off to the next
  pointer xnext.

4 Returns pos_type(newoff), constructed from the resultant offset newoff
  (of type off_type), that stores the resultant stream position, if pos­
  sible.  If the positioning operation  fails,  or  if  the  constructed
  object  cannot  represent  the  resultant  stream position, the object
  stores an invalid stream position.

  27.4.2.1.12  basic_stringbuf::seekpos         [lib.stringbuf::seekpos]
  //  virtual pos_type seekpos(pos_type sp,
  //                           basic_ios<charT,baggage>::openmode which
  //                             = basic_ios<charT,baggage>::in
  //                             | basic_ios<charT,baggage>::out);    inherited

  +-------                BEGIN BOX 139               -------+
  Check vs. lib.strstreambuf::seekpos_
  +-------                 END BOX 139                -------+

1 Alters the stream position within one of the controlled sequences,  if
  possible,  to  correspond  to  the  stream  position  stored in sp (as
  described below).

  --If (which & basic_ios::in) != 0, positions the input sequence.

  --If (which & basic_ios::out) != 0, positions the output sequence.

  --If the function positions neither sequence, the  positioning  opera­
    tion fails.

2 For  a  sequence  to  be  positioned,  if  its  next pointer is a null
  pointer, the positioning operation  fails.   Otherwise,  the  function
  determines newoff from sp.offset():

  --If  newoff  is  an invalid stream position, has a negative value, or
    has a value greater than (xend - xbeg),  the  positioning  operation
    fails.

  --Otherwise,  the  function  adds newoff to the beginning pointer xbeg
    and stores the result in the next pointer xnext.

3 Returns pos_type(newoff), constructed from the resultant offset newoff
  (of type off_type), that stores the resultant stream position, if pos­
  sible.  If the positioning operation  fails,  or  if  the  constructed
  object  cannot  represent  the  resultant  stream position, the object
  stores an invalid stream position.

  27.4.2.1.13  basic_stringbuf::setbuf           [lib.stringbuf::setbuf]
  //  virtual basic_streambuf<charT,baggage>*
  //      setbuf(char_type* s, streamsize n);    inherited

1 Performs an operation  that  is  defined  separately  for  each  class
  derived from basic_stringbuf<charT,baggage>.

  +-------                BEGIN BOX 140               -------+
  Should be pure virtual.

  +-------                 END BOX 140                -------+

2 Default         behavior:         the        same        as        for
  basic_streambuf<charT,baggage>::setbuf(char_type*, streamsize).

  27.4.2.1.14  basic_stringbuf::sync               [lib.stringbuf::sync]
  //  virtual int sync();    inherited

1 Behaves the same as basic_streambuf<charT,baggage>::sync().

  27.4.2.2  Template class basic_istringstream       [lib.istringstream]
  template <class charT, class baggage = ios_baggage<charT> >
  class basic_istringstream : public basic_istream<charT,baggage> {
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;
      int_type  eof()     { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }
  public:
      basic_istringstream(basic_ios<charT,baggage>::openmode which
                              = basic_ios<charT,baggage>::in);
      basic_istringstream(const basic_string<charT>& str,
                          basic_ios<charT,baggage>::openmode which
                              = basic_ios<charT,baggage>::in);
      virtual ~basic_istringstream();
      basic_stringbuf<charT,baggage>* rdbuf() const;
      basic_string<charT> str() const;
      void str(const basic_string<charT>& str);
  private:
  //  basic_stringbuf<charT,baggage> sb;  exposition only
  };
    class istringstream : public basic_istringstream<char> {};
    class wistringstream : public basic_istringstream<char> {};

1 The  class  basic_istringstream<charT,baggage>  is  a  derivative   of
  basic_istream<charT,baggage> that assists in the reading of objects of
  class basic_stringbuf<charT,baggage>.  It supplies  a  basic_stringbuf
  object to control the associated array object.

  +-------                BEGIN BOX 141               -------+
  [To Be Filled]
  +-------                 END BOX 141                -------+

2 For the sake of exposition, the maintained data is presented here as:

  --sb, the basic_stringbuf object.

  27.4.2.2.1  basic_istringstream       [lib.basic.istringstream.m.cons]
       constructors
      basic_istringstream(basic_ios<charT,baggage>::openmode which
                              = basic_ios<charT,baggage>::in);

1 Constructs an object of class basic_istringstream<charT,baggage>, ini­
  tializing  the  base class with basic_istream<charT,baggage>(&sb), and
  initializing sb with sb(which).
      basic_istringstream(const basic_string<charT>& str,
          basic_ios<charT,baggage>::openmode which = basic_ios<charT,baggage>::in);

2 Constructs an object of class basic_istringstream<charT,baggage>, ini­
  tializing  the  base class with basic_istream<charT,baggage>(&sb), and
  initializing sb with sb(str, which).

  27.4.2.2.2  basic_istringstream          [lib.basic.istringstream.des]
       destructor
      virtual ~basic_istringstream();

1 Destroys an object of class basic_istringstream.

  27.4.2.2.3  basic_istringstream::rdbuf      [lib.istringstream::rdbuf]
      basic_stringbuf<charT,baggage>* rdbuf() const;

1 Returns (basic_stringbuf*)&sb.

  27.4.2.2.4  basic_istringstream::str          [lib.istringstream::str]
      basic_string<charT> str() const;

1 Returns sb.str().
      void str(const basic_string<charT>& str_arg);

2 Calls sb.str(str_arg).

  27.4.2.3  Class basic_ostringstream                [lib.ostringstream]
  template <class charT, class baggage = ios_baggage<charT> >
  class basic_ostringstream : public basic_ostream<charT,baggage> {
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;
      int_type  eof()     { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }

  public:
      basic_ostringstream(basic_ios<charT,baggage>::openmode which
                              = basic_ios<charT,baggage>::out);
      basic_ostringstream(const basic_string<charT>& str,
                          basic_ios<charT,baggage>::openmode which
                              = basic_ios<charT,baggage>::out);
      virtual ~basic_ostringstream();
      basic_stringbuf<charT,baggage>* rdbuf() const;
      basic_string<charT> str() const;
      void str(const basic_string<charT>& str);
  private:
  //  basic_stringbuf<charT,baggage> sb;  exposition only
  };
      class ostringstream : public basic_ostringstream<char> {};
      class wostringstream : public basic_ostringstream<wchar_t> {};

1 The   class  basic_ostringstream<charT,baggage>  is  a  derivative  of
  basic_ostream<charT,baggage> that assists in the writing of objects of
  class  basic_stringbuf<charT,baggage>.   It supplies a basic_stringbuf
  object to control the associated array object.

  +-------                BEGIN BOX 142               -------+
  [To Be Filled]
  +-------                 END BOX 142                -------+

2 For the sake of exposition, the maintained data is presented here as:

  --sb, the basic_stringbuf<charT,baggage> object.

  27.4.2.3.1  basic_ostringstream         [lib.basic.ostringstream.cons]
       constructors
      basic_ostringstream(basic_ios<charT,baggage>::openmode which
                              = basic_ios<charT,baggage>::out);

1 Constructs  an  object  of class basic_ostringstream, initializing the
  base  class  with  basic_ostream(&sb),  and   initializing   sb   with
  sb(which).
      basic_ostringstream(const basic_string<charT>& str,
          basic_ios<charT,baggage>::openmode which = basic_ios<charT,baggage>::out);

2 Constructs an object of class basic_ostringstream<charT,baggage>, ini­
  tializing the base class with  basic_ostream<charT,baggage>(&sb),  and
  initializing sb with sb(str, which).

  27.4.2.3.2  basic_ostringstream          [lib.basic.ostringstream.des]
       destructor
      virtual ~basic_ostringstream();

1 Destroys an object of class basic_ostringstream.

  27.4.2.3.3  basic_ostringstream::rdbuf      [lib.ostringstream::rdbuf]
      basic_stringbuf<charT,baggage>* rdbuf() const;

1 Returns (basic_stringbuf<charT,baggage>*)&sb.

  27.4.2.3.4  basic_ostringstream::str          [lib.ostringstream::str]
      basic_string<charT> str() const;

1 Returns sb.str().
      void str(const basic_string<charT>& str_arg);

2 Calls sb.str(str_arg).

  27.5  File-based streams                            [lib.file.streams]

1 Headers:

  --<cstream>

  --<fstream>

  --<stdiostream>

  --<cstdio>

  --<cwchar>

2 Table 28:

3 Table 29:

                   Table 29--Header <cstream> synopsis

  +-------------------------------------------------------------------------+
  |      Type                                Name(s)                        |
  +-------------------------------------------------------------------------+
  |Template class:     basic_convbuf                                        |
  +-------------------------------------------------------------------------+
  |Template structs:   conv_baggage            ios_conv_baggage             |
  +-------------------------------------------------------------------------+
  |Structs:            conv_baggage<wchar_t>   ios_conv_baggage<wstreampos> |
  +-------------------------------------------------------------------------+

                   Table 29--Header <fstream> synopsis

    +-----------------------------------------------------------------+
    |    Type                            Name(s)                      |
    +-----------------------------------------------------------------+
    |Template classes:                                                |
    |basic_filebuf   basic_ifstream   basic_ofstream   basic_stdiobuf |
    +-----------------------------------------------------------------+
    |Classes:                                                         |
    |basic_filebuf<char>              filebuf          wfilebuf       |
    |basic_filebuf<wchar_t>           ifstream         wifstream      |
    |basic_ifstream<char>             istdiostream     wofstream      |
    |basic_ifstream<wchar_t>          ofstream                        |
    |basic_ofstream<char>             ostdiostream                    |
    |basic_ofstream<wchar_t>          stdiobuf                        |
    +-----------------------------------------------------------------+

4 Table 30:

                    Table 30--Header <cstdio> synopsis

  +-------------------------------------------------------------------------------+
  |    Type                                   Name(s)                             |
  +-------------------------------------------------------------------------------+
  |Macros:                                                                        |
  |BUFSIZ         L_tmpnam        SEEK_SET   TMP_MAX                              |
  |EOF            NULL <cstdio>   stderr     _IOFBF                               |
  |FILENAME_MAX   SEEK_CUR        stdin      _IOLBF                               |
  |FOPEN_MAX      SEEK_END        stdout     _IONBF                               |
  +-------------------------------------------------------------------------------+
  |Types:         FILE            fpos_t     size_t <cstdio>                      |
  +-------------------------------------------------------------------------------+
  |Functions:                                                                     |
  |clearerr       fgets           fscanf     gets              rewind    tmpfile  |
  |fclose         fopen           fseek      perror            scanf     tmpnam   |
  |feof           fprintf         fsetpos    printf            setbuf    ungetc   |
  |ferror         fputc           ftell      putc              setvbuf   vprintf  |
  |fflush         fputs           fwrite     puts              sprintf   vprintf  |
  |fgetc          fread           getc       remove            sscanf    vsprintf |
  |fgetpos        freopen         getchar    rename            tmpfile            |
  +-------------------------------------------------------------------------------+

5 Table 31:

                    Table 31--Header <cwchar> synopsis

  +------------------------------------------------------------------------+
  |  Type                               Name(s)                            |
  +------------------------------------------------------------------------+
  |Macros:    NULL <cwchar>   WCHAR_MAX   WCHAR_MIN   WEOF <cwchar>        |
  +------------------------------------------------------------------------+
  |Types:     mbstate_t       wint_t <cwchar>                              |
  +------------------------------------------------------------------------+
  |Struct:    tm <cwchar>                                                  |
  +------------------------------------------------------------------------+
  |Functions:                                                              |
  |btowc      getwchar        ungetwc     wcscpy      wcsrtombs   wmemchr  |
  |fgetwc     mbrlen          vfwprintf   wcscspn     wcsspn      wmemcmp  |
  |fgetws     mbrtowc         vswprintf   wcsftime    wcsstr      wmemcpy  |
  |fputwc     mbsinit         vwprintf    wcslen      wcstod      wmemmove |
  |fputws     mbsrtowcs       wcrtomb     wcsncat     wcstok      wmemset  |
  |fwide      putwc           wcscat      wcsncmp     wcstol      wprintf  |
  |fwprintf   putwchar        wcschr      wcsncpy     wcstoul     wscanf   |
  |fwscanf    swprintf        wcscmp      wcspbrk     wcsxfrm              |
  |getwc      swscanf         wcscoll     wcsrchr     wctob                |
  +------------------------------------------------------------------------+

  SEE ALSO: ISO C subclause 7.9, Amendment 1 subclause 4.6.2.

  27.5.1  Multi-byte conversions                     [lib.conv.fstreams]

  +-------                BEGIN BOX 143               -------+
  While  this  may  be  a  useful class, its primary purpose is to allow
  implementation of wfilebuf.  In the interest of simplicity I think  it
  is better to specify wfilebuf directly and leave the details of imple­
  mentations upto the system vendors.

1 Jerry Schwarz proposal: Delete this section.
  +-------                 END BOX 143                -------+

2 The header <cstream> defines one type, basic_convbuf  that  associates
  its  internal stream buffers holding a sequence of characters with the
  external source/sink stream representing a sequence of another type of
  characters.

  --Conversion  There is a bidirectional conversion between the external
    source/sink stream and character sequences held in the basic_convbuf
    class object.

  --uchar_type:   underlaid   character   container  type  The  external
    source/sink stream can be regarded as a sequence of a character con­
    tainer  type,  which  may be different to charT.  The character con­
    tainer type  on  the  external  source/sink  stream  is  called  the

    underlaid character container type, or uchar_type.

  --Encoding  rule Performing the conversion from a uchar_type character
    sequences to the corresponding character sequence, the basic_convbuf
    may parse the uchar_type sequence to extract the corresponding char­
    acter represented on the uchar_type sequence.  The rule how  a  cer­
    tain  character  is  to  be  represented on a sequence of uchar_type
    characters is called the encoding rule.  The  basic_convbuf  can  be
    regarded  as  having  a (virtual) conversion machine which obeys the
    encoding rule to parse uchar_type sequences.

  --Conversion state The conversion machine has its internal state  cor­
    responding to a certain position of the external source/sink stream.
    If the basic_convbuf stops the conversion to resume later, it has to
    save its internal state, so a class or a type is prepared for saving
    the state onto it so that an user of the basic_convbuf class  object
    can  handle  it.   The  class (or the type) is called the conversion
    state.

  --

  +-------                BEGIN BOX 144               -------+
  Multibyte character I/O support The basic_convbuf can  support  multi­
  byte character file I/O operations.  Provided that the code conversion
  functions between multibyte characters and wide  characters  are  pre­
  pared,  we  may specify the conversion state, and the conversion func­
  tions in the ios_conv_baggage so that  the  basic_convbuf  can  handle
  this multibyte characters.
  +-------                 END BOX 144                -------+

  27.5.1.1  Template class conv_baggage               [lib.conv.baggage]
  template <class charT> struct conv_baggage {}
  struct conv_baggage<wchar_t> {
      typedef ios_char_baggage<wchar_t>   char_bag;
      typedef ios_pos_baggage<wstreampos> pos_bag;
      typedef ios_conv_baggage<state_t>   conv_bag;
  };

1 The template struct conv_baggage<charT> is a baggage class which main­
  tains the definitions of the types and functions necessary  to  imple­
  ment  the  template class basic_convbuf.  The template parameter charT
  reprsents the character container type and each specialized version of
  conv_baggage  provides  the  default  definitions corresponding to the
  specialized character container type.

2 The    conv_baggage<charT>    declaration    has    three     members,
  ios_char_baggage, ios_pos_baggage, and ios_conv_baggage.

3 Although the former two of them are same as in the ios_baggage<charT>,
  the last baggage, ios_conv_baggage<charT> provides all the definitions
  about types and functions necessary to perform conversion.

  27.5.1.2  Template class ios_conv_baggage       [lib.ios.conv.baggage]
      template <class stateT> struct ios_conv_baggage {};

1 As  is the other baggage structs, there is no definition in the decla­
  ration of the template struct, ios_conv_baggage.  All of  the  defini­
  tions   related   to   the   conversion  and  necessary  to  implement
  basic_convbuf  class  shall  be  provided  in  a   template   version,
  ios_conv_baggage<STATE_T>  specialized for a conversion state STATE_T.

  27.5.1.2.1  Struct                      [lib.ios.conv.baggage.state.t]
       ios_conv_baggage<STATE_T>
  struct ios_conv_baggage<STATE_T> {
      typedef CHAR_T  char_type;
      typedef STATE_T conv_state;
      typedef UPOS_T  conv_upos;
      typedef UCHAR_T uchar_type;
      typedef POS_T   pos_type;
      typedef OFF_T   off_type;
      typedef locale::codecnv<uchar_type,char_type,conv_state> codecvt_in;
      typedef locale::codecnv<char_type,uchar_type,conv_state> codecvt_out;
      locale::result convin(codecvt_in*, conv_state&,
              const uchar_type*, const uchar_type*, const uchar_type*&,
              char_type*, char_typeT*, char_type*&);
      locale::result convout(codecvt_out*, conv_state&,
              const char_type*, const char_type*, const char_type*&,
              uchar_type*, uchar_type*, uchar_type*&);
      pos_type   get_pos(conv_state&, conv_upos&);
      off_type   get_off(conv_state&, conv_upos&);
      conv_state get_posstate pos_type&);
      conv_state get_offstate(off_type&);
      conv_upos  get_posupos (pos_type&);
      conv_upos  get_offupos (off_type&);
  };

1 A  specialized version of the struct ios_conv_baggage<STATE_T> is nec­
  essary to use the basic_convbuf class.  In order to construct  a  spe­
  cialized  version  of the struct, the following set of types and func­
  tions shall be provided.

  --CHAR_T: is the character container type which shall be same  as  the
    template parameter of the class, conv_baggage.

  --STATE_T: is the conversion state type which also the template param­
    eter type of this baggage.  It is the  parsing/tracing  state  which
    the function, convin and convout are taken.

  --Every  type of conversion states have a state, called initial state,
    which corresponds to the state beginning to parse  a  new  sequence.
    The  constructor,  STATE_T::STATE_T()  or  STATE_T::STATE_T(0)  con­
    structs the initial state.

  --UCHAR_T: is the underlaid character container type for the  external
    source/sink stream handled by the basic_convbuf.

  --UPOS_T:  is  the  repositional  information  type  for  the external
    source/sink stream.  It is used  to  implement  the  seekpos/seekoff
    member functions in the basic_convbuf.

  --POS_T:  is the repositional information which the basic_convbuf sup­
    ports for the client of the object.  It shall be  the  same  as  the
    template  parameter  type  of the struct ios_pos_baggage in the same
    conv_baggage.

  --OFF_T: is an integral type which is used as the repositional  infor­
    mation which the basic_convbuf supports.

  27.5.1.2.1.1  convin            [lib.ios.conv.baggage.state.t::convin]
      locale::result
          convin(codecvt_in* ccvt, conv_state& stat,
                 const uchar_type* from, const uchar_type* from_end,
                 const uchar_type*& from_next,
                 char_type* to, char_typeT* to_limit, char_type*& to_next);

1 The  conversion  state designated by stat represents the parsing state
  on the underlaid source sequence.  According to the  conversion  state
  designated  by  stat, it begins to parse the source character sequence
  whose begining and end position designated by  from  and  from_end  to
  convert them.  It stores the result sequence (if any) into the succes­
  sive location of an array pointed to by to and to_limit.  The  conver­
  sion stops when either of the following occurs:

  1)parses  all of the underlaid character sequences and stores the last
    character into the destination array.

  2)fills all of the destination array and no more room to store.

  3)encounters an invalid underlaid character in the source sequence.

2 In case (1), it returns ok.  In case (2), it returns partial.  In case
  (3), it returns error.

3 In all cases it leaves the from_next and to_next pointers pointing one
  beyond the last character successfully converted and leaves  the  con­
  version state onto the stat for the next time conversion.  If case (3)
  occurs, the conversion state on the stat becomes undefined value.   No
  more conversion with the value is available.

4 If  the locale-dependent conversion functions are needed, the nconver­
  sion function which the locale::codecnv facet object, ccnv provides is
  available as the following invokation:
      ccnv.convert(stat, from, from_end, from_next, to, to_limit, to_next);

5 The  default conversion function depends on the locale_codecvt facets.
  Users can customize the encoding scheme by specifying their  own  con­
  version functions in a new conv_baggage class.

  27.5.1.2.1.2  convout          [lib.ios.conv.baggage.state.t::convout]
      locale::result convout(codecvt_out* ccvt, conv_state&,
                  const char_type from*, const char_type* from_end,
                  const char_type*& from_next.,
                  uchar_type*, uchar_type*, uchar_type*&);

1 The  conversion  state designated by stat represents the parsing state
  on the underlaid destination  sequence.   It  begins  to  convert  the
  source  character  sequence whose begining and end position designated
  by from and from_end.  According to the conversion state designated by
  stat, it stores the result destination underlaid chracter sequence (if
  any) into the successive location of an array pointed  to  by  to  and
  to_limit.  The conversion stops when either of the following occurs:

  1)consumes  all  of the source character sequences and stores the last
    underlaid character into the destination array.

  2)fills all of the destination array and no more room to store.

  3)encounters an invalid character in the source sequence.

2 In case (1), it returns ok.  In case (2), it returns partial.  In case
  (3), it returns error.

3 In  all  cases  it leaves the 5from_next and to_next pointers pointing
  one beyond the last character successfully converted  and  leaves  the
  conversion  state onto the stat for the next time conversion.  If case
  (3) occurs, the conversion state on the stat becomes undefined  value.
  No more conversion with the value is available.

4 If  the  locale-dependent conversion functions are needed, the conver­
  sion function which the locale::codecnv facet object, ccnv provides is
  available as the following invocation;
      ccnv.convert(stat, from, from_end, from_next, to, to_limit, to_next);

5 The  default  conversion  function  is  depends  on the locale_codecvt
  facets.  Users can customize the encoding scheme by  specifying  their
  own conversion functions in a new conv_baggage class.

  27.5.1.2.1.3  get_pos and      [lib.ios.conv.baggage.state.t::get.pos]
       get_off
      pos_type get_pos(conv_state& stat, conv_upos& upos);
      off_type get_off(conv_state&, conv_upos&);

1 Constructs the pos_type object or off_type object from the  conversion
  state, stat and the repositional information for the underlaid stream,
  upos and returns it.  These are used to make the return value  of  the
  basic_convbuf::seekpos/seekoff protected member function.

  27.5.1.2.1.4             [lib.ios.conv.baggage.state.t::get.pos.state]
       get_posstate
       and
       get_offstate

      conv_state get_posstate(pos_type& pos);
      conv_state get_offstate(off_type& off);

1 Extract the conversion state held by the repositional information, pos
  or  off.   These  are used to reset the conversion state maintained in
  the basic_convbuf class object when the basic_convbuf::seetpos/seekoff
  functions are performed.

  27.5.1.2.1.5              [lib.ios.conv.baggage.state.t::get.pos.upos]
       ios_conv_baggage<STATE_T>::get_posupos
       and get_offupos
      conv_upos  get_posupos(pos_type&);
      conv_upos  get_offupos(off_type&);

1 Extract the repositioning information for the  underlaid  stream  from
  the  repositioning information on the basic_convbuf stream.  These are
  used in the basic_convbuf::seekpos/seekoff protected member  functions
  to reposition the external source/sink stream.

  27.5.1.2.2  Struct                   [lib.ios.conv.baggage.wstreampos]
       ios_conv_baggage<wstreampos>
  struct ios_conv_baggage<wstreampos> {
      typedef wchar_t char_type;
      typedef STATE_T conv_state;
      typedef UPOS_T  conv_upos;
      typedef char    uchar_type;
      typedef wstreampos pos_type;
      typedef wstreamoff off_type;
      typedef locale::codecnv<char,wchar_t,STATE_T> codecnv_in;
      typedef locale::codecnv<wchar_t,char,STATE_T> codecnv_out;
      locale::result convin(codecvt_in* ccvt, conv_state& stat,
             const char *from, const char* from_end, const char*& from_next,
             wchar_t* to, wchar_t* to_limit, wchar_t*& to_next) {
              return ccvt->convert (stat, from, from_end, from_next,
                   to, to_limit, to_next);
          }
      locale::result convout(codecvt_out* ccvt, conv_state& stat,
             const wchar_t* from, const wchar_t* from_end, const wchar_t*& from_next,
             char* to, char* to_limit, char* to_next) {
              return ccvt->convert (stat, from, from_end, from_next,
                   to, to_limit, to_next);
          }
      pos_type   get_pos(conv_state&, conv_upos&);
      off_type   get_off(conv_state&, conv_upos&);
      conv_state get_posstate(pos_type&);
      conv_state get_offstate(off_type&);
      conv_upos  get_posupos (pos_type&);
      conv_upos  get_offupos (off_type&);
  };

1 The  specialized  version  of the struct, ios_conv_baggage<wstreampos>
  supports the wide-oriented  basic_convbuf  class  and  the  conversion
  between  wide  characters  and  multibyte  characters as the underlaid
  character sequence.  The types, STATE_T and UPOS_T are implementation-

  defined  types.   The  behavior  of the conversion functions depend on
  those of the locale object.

2 The encoding rule  of  the  multibyte  characters  is  implementation-
  defined.

  27.5.1.3  Template class basic_convbuf             [lib.basic.convbuf]
  template <class charT, class baggage = conv_baggage<charT> >
  class basic_convbuf : public basic_streambuf<charT,baggage> {
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;
      int_type  eof()     { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }
  private:
      typedef baggage::conv_bag::conv_state state_type;
      typedef baggage::conv_bag::conv_upos upos_type ;
  public:
      basic_convbuf();

      virtual ~basic_convbuf();
  protected:
  //  virtual int_type overflow (int_type c = eof());     inherited
  //  virtual int_type pbackfail(int_type c = eof());     inherited
  //  virtual int_type underflow();                                       inherited
  //  virtual int_type uflow();                                           inherited
  //  virtual streamsize xsgetn(charT* s, streamsize n);          inherited
  //  virtual streamsize xsputn(const charT* s, streamsize n);    inherited
  //  virtual pos_type seekoff(off_type, basic_ios<charT,baggage>::seekdir way,
  //                           basic_ios<charT,baggage>::openmode which
  //                             = basic_ios<charT,baggage>::in
  //                             | basic_ios<charT,baggage>::out);        inherited
  //  virtual pos_type seekpos(pos_type  sp, basic_ios<charT,baggage>::openmode which
  //                             = basic_ios<charT,baggage>::in
  //                             | basic_ios<charT,baggage>::out);        inherited
  //  virtual basic_streambuf<charT,baggage>*
  //                   setbuf(charT* s, streamsize n);    inherited
  //  virtual int sync();         inherited
  private:
  //  state_type state;   exposition only
  };

1 The   template  class  basic_convbuf<charT,baggage>  is  derived  from
  basic_streambuf<charT,baggage> to associate  the  character  sequences
  and  the  underlaid  character  sequences.  It performs the conversion
  between these two types of chracter sequences.

2 For the sake of exposition, the basic_convbuf maintains the conversion
  state  to  restart the conversion to read/write the character sequence
  from/to the underlaid stream.

  27.5.1.3.1  basic_convbuf  constructor        [lib.basic.convbuf.cons]
     basic_convbuf();

1 Constructs an object of template  class  basic_convbuf<charT,baggage>,
  initializing the base class with basic_streambuf<charT,baggage>(), and
  initializing;

  --state with state_type(0) as to specify initial state.

  27.5.1.3.2  basic_convbuf  destructor          [lib.basic.convbuf.des]
     virtual ~basic_convbuf();

1 Destroys an object of class basic_convbuf<charT,baggage>.

  27.5.1.3.3  basic_convbuf::overflow       [lib.basic.convbuf.overflow]
      virtual int_type overflow(int_type c = eof());

1 Behaves  the  same   as   basic_streambuf<charT,baggage>::overflow(c),
  except that the behavior of ``consuming a character'' is as follows:

  --(1)  Converting  the  characters  to  be consumed into the underlaid
    character sequence with the function baggage::conv_bag::convout().

  --(2) The result underlaid character sequence is appended to the asso­
    ciated output stream.

  27.5.1.3.4                              [lib.basic.convbuf::pbackfail]
       basic_convbuf::pbackfail
      virtual int_type pbackfail(int_type c);

1 Puts back the character designated by c to the input sequence, if pos­
  sible, in one of three ways:

  +-------                BEGIN BOX 145               -------+
  Because  the parsing on the underlaid character sequence generally can
  only go advance or most of parsing machined cannot go  back,  some  of
  the   basic_convbuf   implementations  cannot  ``put  back  characters
  directly to the associated input sequence.''  So the behaviors related
  to putting back the associated input stream are removed.
  +-------                 END BOX 145                -------+

  --If  c  != eof(), if either the input sequence has a putback position
    available or the function makes a putback position available, and if
    (charT)c == (charT)gnext[-1], assigns gnext - 1 to gnext.

    Returns (charT)c.

  --If  c  != eof(), if either the input sequence has a putback position
    available or the function makes a putback position available, and if
    the function is permitted to assign to the putback position, assigns
    c to *--gnext.

    Returns (charT)c.

  --If c == eof() and if either the input sequence has a  putback  posi­
    tion  available  or the function makes a putback posotion available,
    assigns gnext - 1 to gnext.

    Returns (charT)c.

2 Returns eof() to signal the failure.

3 Notes:

4 The function does not put back  a  character  directly  to  the  input
  sequence.

5 If  the  function  can  succeed  in more than one of these ways, it is
  unspecified which way is chosen.  The function can alter the number of
  putback positions available as a result of any call.

6 Default behavior:  returns baggage::char_bag::eof().

  +-------                BEGIN BOX 146               -------+
  Should be pure virtual.
  +-------                 END BOX 146                -------+

  27.5.1.3.5                              [lib.basic.convbuf::underflow]
       basic_convbuf::underflow
  //  virtual int_type underflow();    inherited

1 Returns the first character of  the  pending  sequence,  if  possible,
  without  moving  the stream position past it.  If the pending sequence
  is null then the function fails.

2 The pending sequence of characters is defined as the concatenation of:

  a)If  gnext  is non-NULL, then the gend - gnext characters starting at
    gnext, otherwise the empty sequence.

  b)Some sequence (possibly empty) of characters  read  from  the  input
    stream.

  --These  underlaid  character sequence shall be converted by the func­
    tion baggage::conv_bag::convin() before concatinating  to  construct
    the  pending  sequence.   In  case that there remains some underlaid
    characters which cannot be converted  to  any  more  characters,  we
    treat it empty as the subsequence (b).

3 The  result  character is the first character of the pending sequence,
  if any.  The backup sequence is defined as the concatenation of:

  a)If gbeg is non-NULL then empty, otherwise the gnext -  gbeg  charac­
    ters beginning at gbeg.

  b)the result character.

4 The function sets up gnext and gend satisfying:

  a)In case the pending sequence has more than one character the gend  -
    gnext characters starting at gnext are the characters in the pending
    sequence after the result character.

  b)If the pending sequence has exactly one character,  then  gnext  and
    gend may be NULL or may both be set to the same non-NULL pointer.

5 If gbeg and gnext are non-NULL then the function is not constrained as
  to their contents,  but  the  ``unusual  backup  condition''  is  that
  either:

  a)If  the  backup  sequence  contains at least gnext - gbeg characters
    then the gnext - gbeg characters starting at  gbeg  agree  with  the
    last gnext - gbeg characters of the backup sequence.

  b)Or  the  n  characters  starting  a  gnext - n agree with the backup
    sequence (where n is the length of the backup sequence)

6 Returns eof() to indicate failure.

7 Default behavior:  returns baggage::char_bag::eof().

  +-------                BEGIN BOX 147               -------+
  Should be pure virtual.
  +-------                 END BOX 147                -------+

  27.5.1.3.6  basic_convbuf::uflow            [lib.basic.convbuf::uflow]
  //  virtual int_type uflow();    inherited

1 Behaves the same as basic_streambuf<charT,baggage>::uflow().

  27.5.1.3.7  basic_convbuf::xsgetn                [lib.convbuf::xsgetn]
  //  virtual streamsize xsgetn(char_type* s, streamsize n);    inherited

1 Behaves the same as basic_streambuf<charT,baggage>::xsgetn(char_type*,
  streamsize).

  27.5.1.3.8  basic_convbuf::xsputn                [lib.convbuf::xsputn]
  //  virtual streamsize xsputn(const char_type* s, streamsize n);    inherited

1 Behaves the same as basic_streambuf<charT,baggage>::xsputn(char_type*,
  streamsize).

  27.5.1.3.9  basic_convbuf::seekoff              [lib.convbuf::seekoff]
  //  virtual pos_type seekoff(off_type off, basic_ios<charT,baggage>::seekdir way,
  //      basic_ios<charT,baggage>::openmode which
  //        = basic_ios<charT,baggage>::in | basic_ios<charT,baggage>::out);    inherited

1 Behaves                  the                  same                  as
  basic_streambuf<charT,baggage>::seekoff(off,way,which),   except  that
  the behavior ``alters the stream position'' means that:

  --(a) altering the underlaid character stream position which they  get
    with       the       return       value       of       the      bag­
    gage::conv_bag::get_posupos(off_type&); and,

  --(b) restoring the current conversion state by resetting the  member,
    state      with     the     return     value     of     the     bag­
    gage::conv_bag::get_offstate(off_type&).

  27.5.1.3.10  basic_convbuf::seekpos             [lib.convbuf::seekpos]
  //  virtual pos_type seekpos(pos_type sp,
  //      basic_ios<charT,baggage>::openmode which
  //        = basic_ios<charT,baggage>::in | basic_ios<charT,baggage>::out);    inherited

1 At first do sync() to clear up the get buffer, and alters  the  stream
  position, as follows:

  --(a)  altering  the  underlaid character stream position by which the
    function, baggage::conv_bag::get_posupos(pos), returns.  and,

  --(b) restoring the member, state with the return value  of  the  bag­
    gage::conv_bag::get_posstate(pos).

2 Returns  pos_type,  newpos,  constructed  from  the resultant upos and
  state if both (a) and (b) are successfully terminated.

3 If either or both (a) or/and (b) fail(s), or if the constructed object
  cannot  represent  the resultant stream position, the object stores an
  invalid stream position.

4 Whichever  value  is  specified   in   the   which   parameters,   the
  basic_convbuf handles only one external source/sink stream.

5 If (a) succeeds, returns a newly constructed streampos object returned
  by baggage::conv_bag::get_pos(state, upos) where upos is a UPOS_T type
  object which represent the current position of the underlaid stream.

6 Otherwise, the object stores an invalid stream position.

  27.5.1.3.11  basic_convbuf::setbuf               [lib.convbuf::setbuf]
  //  virtual basic_streambuf<charT,baggage>*
  //      setbuf(char_type* s, streamsize n);    inherited

1 Makes  the  array of n (charT type) characters, whose first element is
  designated by s, available for use as a buffer area for the controlled
  sequences, if possible.

  +-------                BEGIN BOX 148               -------+
  The  basic_convbuf  does  not  fix the buffer management strategy.  It
  remains alternatives for the derived class designers.
  +-------                 END BOX 148                -------+

  27.5.1.3.12  basic_convbuff::sync                  [lib.convbuf::sync]
  //  virtual int sync();    inherited

1 Reflects the pending sequence to the external sink sequence and  reset
  the  get/put  buffer pointers.  It means that if there are some unread
  sequence on the get buffer and the external  source  sequense  is  not
  seekable, the unread sequence is perfectly lost.

2 The detailed behavior is as follows:

  a)Consumes  all  of  the  pending  sequence of characters, (as pending
    sequence and ``consumes the sequence,'' see the description  in  the
    basic_streambuf<charT,baggage>::overflow()
    _lib.streambuf::overflow_)

    In case that consuming means appending characters to the  associated
    output stream, the character sequense shall be converted to the cor­
    responding   underlaid    character    sequence    by    the    bag­
    gage::conv_bag::convout().

  b)Clears  all  of  the  following  pointers:  pbeg, pnext, pend, gbeg,
    gnext, and gend.

3 Returns -1 if (a) fails, otherwise 0.

  27.5.1.4  Examples of trait specialization       [lib.examples.traits]
  class fstate_t { ... };       // Implementation-defined conversion state
                                // object which is for file I/O.
  class wfstate_t { ... };
  template <class charT> struct file_baggage {};
  struct file_baggage<char> {
      typedef ios_char_baggage<char> char_bag;
      typedef ios_pos_baggage<streampos> char_pos;
      typedef ios_conv_baggage<fstate_t> conv_pos;
  };
  struct file_baggage<wchar_t>{
      typedef ios_char_baggage<char> char_bag;
      typedef ios_pos_baggage<wstreampos> char_pos;
      typedef ios_conv_baggage<wfstate_t> conv_pos;
  };
  template <class stateT> struct ios_file_baggage {};
  //
  // Specialized for the single-byte filebuf
  //
  struct ios_conv_baggage<fstate_t> {
      typedef char       char_type;       // char/wchar_t...
      typedef fstate_t   conv_state;      // key parameter(mainly depend on uchar_type)
      typedef streamoff  conv_upos;       // Physical file offset
      typedef char       uchar_type;      // Physical file I/O
      typedef streampos  pos_type;        // Enough to large
      typedef streamoff  off_type;        // Enough to large
      typedef locale::codecnv<char,wchar_t,fstate_t> codecnv_in;
      typedef locale::codecnv<wchar_t,char,fstate_t> codecnv_out;

      locale::result convin(codecvt_in* ccvt, conv_state& stat,
                            const char *from, const char* from_end,
                            const char*& from_next,
                            char* to, char* to_limit, char*& to_next) {
          return ccvt->convert (stat, from, from_end, from_next,
                               to, to_limit, to_next);
      }
      locale::result convout(codecvt_out* ccvt, conv_state& stat,
                             const char* from, const char* from_end,
                             const char*& from_next,
                             char* to, char* to_limit, char* to_next) {
          return ccvt->convert (stat, from, from_end, from_next,
                               to, to_limit, to_next);
      }
      pos_type get_pos(conv_state&, conv_upos&);
      off_type get_off(conv_state&, conv_upos&);
      conv_state get_posstate(pos_type&);
      conv_state get_offstate(off_type&);
      conv_upos  get_posupos (pos_type&);
      conv_upos  get_offupos (off_type&);
  };
  //
  // Specialized for the wfilebuf
  //
  struct ios_conv_baggage<wfstate_t> {
      typedef wchar_t    char_type;       // char/wchar_t...
      typedef wfstate_t   conv_state;     // key parameter(mainly depend on uchar_type)
      typedef streamoff  conv_upos;       // Physical file offset
      typedef char       uchar_type;      // Physical file I/O
      typedef wstreampos pos_type;        // Enough to large
      typedef wstreamoff off_type;        // Enough to large
      typedef locale::codecnv<char,wchar_t,fstate_t> codecnv_in;
      typedef locale::codecnv<wchar_t,char,fstate_t> codecnv_out;
      locale::result convin (codecvt_in* ccvt, conv_state& stat,
                const char *from, const char* from_end, const char*& from_next,
                wchar_t* to, wchar_t* to_limit, wchar_t*& to_next) {
          return ccvt->convert (stat, from, from_end, from_next,
                               to, to_limit, to_next);
      }
      locale::result convout (codecvt_out* ccvt, conv_state& stat,
                const wchar_t* from, const wchar_t* from_end,
                const wchar_t*& from_next,
                char* to, char* to_limit, char* to_next) {
          return ccvt->convert (stat, from, from_end, from_next,
                               to, to_limit, to_next);
      }

      pos_type get_pos (conv_state&, conv_upos&);
          // wstreampos get_pos (wfstate_t&, streampos);
      off_type get_off (conv_state&, conv_upos&);
          // wstreamoff get_off (wfstate_t&, streampos);
      conv_state get_posstate (pos_type&);
          // wfstate_t get_posstate (wstreampos&);
      conv_state get_offstate (off_type&);
          // wfstate_t get_offstate (wstreamoff&);
      conv_upos  get_posupos (pos_type&);
          //
      conv_upos  get_offupos (off_type&);
  };

  +-------                BEGIN BOX 149               -------+
  Need more description about these definitions
  +-------                 END BOX 149                -------+

  27.5.2  File streams                                    [lib.fstreams]

1 The header <fstream> defines six types that associate  stream  buffers
  with files and assist reading and writing files.

  +-------                BEGIN BOX 150               -------+
  Note:  Although filebuf object is templated, it accepts only type char
  as charT parameter and it continues to  provide  narrow-oriented  file
  I/O operations.  So this subclause remains unchanged.  -- mjv
  +-------                 END BOX 150                -------+

  +-------                BEGIN BOX 151               -------+
  Jerry  Schwarz proposal: basic_filebuf<charT,baggage> should be speci­
  fied so that it treats a file as a  sequence  of  charT.   Except  for
  filebuf and wfilebuf that implies it treats the file as binary.
  +-------                 END BOX 151                -------+

2 In  this  subclause,  the  type  name  FILE  is a synonym for the type
  FILE.44)

  --File A File provides an external source/sink stream whose  underlaid
    character type is char (byte).

  --Multibyte  characters  and Files Class basic_filebuf is derived from
    basic_convbuf to support multibyte  character  I/O.   A  File  is  a
    sequence  of multibyte characters.  In order to provide the contents
    as a wide character sequence, wfilebuf should convert  between  wide
    character sequences and multibyte character sequences.

  --basic_filebuf  Derived  from  basic_convbuf.   Even  the single byte
    character  version  because  single  byte  code  conversion  may  be
  _________________________
  44) FILE is defined in <cstdio> (_lib.file.streams_).

    necessary...  A basic_filebuf provide... file I/O, char/wchar_t par­
    ity.  fstate_t ... template parameter for ios_conv_baggage

  --Customize Mechanism Change name (conv_bag  ->  file_bag),  customize
    ios_conv_baggage<fstate_t>.      Modify     the     definition    of
    ios_conv_baggage.

  --Multibyte character and Files A File provides  byte  sequences.   So
    the streambuf (or its derived classes) treats a file as the external
    source/sink byte sequence.  In a large  character  set  environment,
    multibyte  character  sequences are held in files.  In order to pro­
    vide the contents of a  file  as  wide  character  sequences,  wide-
    oriented  filebuf,  namely  wfilebuf  should  convert wide character
    sequences.  Because of  necessity  of  the  conversion  between  the
    external source/sink streams and wide character sequences.

  27.5.2.1  Template class basic_filebuf                   [lib.filebuf]
  template <class charT, class baggage = conv_baggage<charT> >
  class basic_filebuf : public basic_convbuf<charT,baggage> {
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;
      int_type  eof()     { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }
  public:
      basic_filebuf();
      virtual ~basic_filebuf();
      bool is_open() const;
      basic_filebuf<charT,baggage>*
           open(const char* s, basic_ios<charT,baggage>::openmode mode);
  //  basic_filebuf<charT,baggage>* open(const char* s, ios::open_mode mode);
      basic_filebuf<charT,baggage>* close();
  protected:
  //  virtual int_type overflow (int_type c = eof());     inherited
  //  virtual int_type pbackfail(int_type c = eof());     inherited

  +-------                BEGIN BOX 152               -------+
  The following was not part of the proposal.  Should we keep it?
  +-------                 END BOX 152                -------+

  //  virtual int      showmany();                inherited
  //  virtual int_type underflow();               inherited
  //  virtual int_type uflow();                   inherited
  //  virtual streamsize xsgetn(char_type* s  streamsize n);      inherited
  //  virtual streamsize xsputn(const char_type* s, streamsize n);        inherited
  //  virtual pos_type seekoff(off_type off,
  //                           basic_ios<charT,baggage>::seekdir way,
  //                           basic_ios<charT,baggage>::openmode which
  //                             = basic_ios<charT,baggage>::in
  //                             | basic_ios<charT,baggage>::out);        inherited
  //  virtual pos_type seekpos(pos_type sp,
  //                           basic_ios<charT,baggage>::openmode which
  //                             = basic_ios<charT,baggage>::in
  //                             | basic_ios<charT,baggage>::out);        inherited
  //  virtual basic_streambuf<charT,baggage>*
  //                   setbuf(char_type* s, streamsize n);        inherited
  //  virtual int sync();                         inherited
  private:
  //  FILE* file; exposition only
  };
      class filebuf : public basic_filebuf<char> {};
      class wfilebuf : public basic_filebuf<wchar_t> {};

1 The    class    basic_filebuf<charT,bagggage>    is    derived    from
  basic_streambuf<charT,bagggage> to associate both the  input  sequence
  and the output sequence with an object of type FILE.

2 For the sake of exposition, the maintained data is presented here as:

  --FILE  *file,  points to the FILE associated with the object of class
    basic_filebuf<charT,bagggage>.

3 The restrictions on reading and writing a sequence  controlled  by  an
  object  of  class  basic_filebuf<charT,bagggage>  are  the same as for
  reading and writing its associated file.  In particular:

  --If the file is not  open  for  reading  or  for  update,  the  input
    sequence cannot be read.

  --If  the  file  is  not  open  for  writing or for update, the output
    sequence cannot be written.

  --A joint file position is maintained for both the input sequence  and
    the output sequence.

4 In  order to support file I/O and multibyte/wide character conversion,
  the following arrangement is applied to the baggage structures:

  --Specify char as the underlaid character type, uchar_type defined  in
    the ios_conv_baggage<>.

  --Define state_t, the template parameter of the ios_conv_baggage<>, so
    that it can apply to the conversion function.  In case  the  conver­
    sion function provided by the locale::codecnv facet uses, we adopt a

    specialized template parameter stateT for the  locale-oriented  con­
    version  function  suitable for the multibyte/wide character conver­
    sion.  Now we assume the name of  the  conversion  state  object  is
    fstate_t.

  --Define  streamoff (or streampos) as the repositional information for
    the underlaid byte sequence.

  --Define streamoff, wstreampos for the  wide-oriented  streambufs  (or
    filebufs) so that some composite function in the ios_conv_baggage(),
    for example:
        wstreampos get_pos(fstate_t fs, streampos s);
        wstreamoff get_off(fstate_t fs, streampos s);

  27.5.2.1.1  basic_filebuf constructor         [lib.basic.filebuf.cons]
      basic_filebuf();

1 Constructs an object of class basic_filebuf<charT,baggage>, initializ­
  ing the base class with basic_streambuf<charT,baggage>(), and initial­
  izing file to a null pointer.

  27.5.2.1.2  basic_filebuf destructor           [lib.basic.filebuf.des]
      virtual ~basic_filebuf();

1 Destroys  an  object  of  class  basic_filebuf<charT,baggage>.   Calls
  close().

  27.5.2.1.3  basic_filebuf::is_open              [lib.filebuf::is.open]
      bool is_open() const;

1 Returns true if file is not a null pointer.

  27.5.2.1.4  basic_filebuf::open                    [lib.filebuf::open]
      basic_filebuf<charT,baggage>* open(const char* s,
                                         basic_ios<charT,baggage>::openmode mode);

1 If  file  is  not  a null pointer, returns a null pointer.  Otherwise,
  calls  basic_streambuf<charT,baggage>::basic_streambuf().    It   then
  opens  a  file,  if  possible,  whose name is the NTBS s, ``as if'' by
  calling fopen(s,modstr) and assigning the return value to file.

2 The     NTBS     modstr     is     determined     from     mode      &
  ~basic_ios<charT,baggage>::ate as indicated in Table 32:

                        Table 32--File open modes

              +---------------------------------------------+
              |basic_ios<charT,baggage>    stdio equivalent |
              |        Value(s)                             |
              +---------------------------------------------+
              |in                          "r"              |
              |out | trunc                 "w"              |
              |out | app                   "a"              |
              |in | out                    "r+"             |
              |in | binary                 "rb"             |
              |out | trunc | binary        "wb"             |
              |out | app | binary          "ab"             |
              |in | out                    "r+              |
              |in | out | trunc            "w+"             |
              |in | out | app              "a+"             |
              |in | out | binary           "r+b"            |
              |in | out | trunc | binary   "w+b"            |
              |in | out | app | binary     "a+b"            |
              +---------------------------------------------+

3 If   the   resulting   file   is   not  a  null  pointer  and  mode  &
  basic_ios<charT,baggage>::ate  is  nonzero,   calls   fseek(file,   0,
  SEEK_END).45)

4 If  fseek  returns  a  null  pointer, calls close() and returns a null
  pointer.  Otherwise, returns this.
      basic_filebuf<charT,baggage>* open(const char* s, ios::open_mode mode);

5 Returns open(s, basic_ios<charT,baggage>::openmode(mode)).

  27.5.2.1.5  basic_filebuf::close                  [lib.filebuf::close]
      basic_filebuf* close();

1 If file is a null pointer, returns a null pointer.  Otherwise, if  the
  call  fclose(file) returns zero, the function stores a null pointer in
  file and returns this.46) Otherwise, returns a null pointer.

  27.5.2.1.6  basic_filebuf::overflow            [lib.filebuf::overflow]
  //  virtual int_type overflow(int_type c = eof());    inherited

1 Behaves   the   same  as  basic_streambuf<charT,baggage>::overflow(c),
  except that tThe behavior of ``consuming a character'' is as follows:
  _________________________
  45)  The  macro  SEEK_END  is  defined,  and  the  function signatures
  fopen(const char_type*, const char_type*) and fseek(FILE*, long,  int)
  are declared, in <cstdio> (_lib.file.streams_).
  46) The function signature  fclose(FILE*)  is  declared,  in  <cstdio>
  (_lib.file.streams_).

  --(1) Converting the characters to  be  consumed  into  the  underlaid
    character  sequence  with the function baggage::conv_bag::convout().
    During the conversion, convout maintains the conversion state in the
    member  state.   At the end of execution of the conversion, the con­
    version state is saved on it.

  --(2) The result underlaid character sequence is written to  the  file
    specified by file.

    At  the consumption of the pending characters, none of them are dis­
    carded.  All of the characters are converted to be  writted  to  the
    file.

2 Returns  eof()  to  indicate  failure.  If file is a null pointer, the
  function always fails.

  27.5.2.1.7  basic_filebuf::pbackfail          [lib.filebuf::pbackfail]
  //  virtual int_type pbackfail(int_type c = eof());    inherited

  +-------                BEGIN BOX 153               -------+
  Check vs. _lib.streambuf::pbackfail_ and _lib.strstreambuf::pbackfail_
  and _lib.basic.convbuf::pbackfail_
  +-------                 END BOX 153                -------+

1 Puts back the character designated by c to the input sequence, if pos­
  sible, in one of four ways:

  +-------                BEGIN BOX 154               -------+
  Because the parsing on the underlaid character sequence generally  can
  only  go  advance  or most of parsing machined cannot go back, some of
  the  basic_convbuf  implementations  cannot  ``put   back   characters
  directly to the associated input sequence.''  So the behaviors related
  to putting back the associated input stream are removed.
  +-------                 END BOX 154                -------+

  --If c != eof() and if the function makes a putback position available
    and  if  (char_type)c  == (char_type)gnext[-1], assigns gnext - 1 to
    gnext.

    Returns (char_type)c.

  --If c != eof() and if the function makes a putback position available
    and  if the function is permitted to assign to the putback position,
    assigns c to *--gnext.

    Returns (char_type)c.

  --If c == eof() and if either the input sequence has a  putback  posi­
    tion  available  or the function makes a putback position available,
    assigns gnext - 1 to gnext.

    Returns (char_type)c.

2 Returns eof() to indicate failure.

3 Notes:

4 If file is a null pointer, the function always fails.

5 The function does not put back  a  character  directly  to  the  input
  sequence.

6 If  the  function  can  succeed  in more than one of these ways, it is
  unspecified which way is chosen.  The function can alter the number of
  putback positions available as a result of any call.

7 Default behavior:  returns baggage::char_bag::eof().

  +-------                BEGIN BOX 155               -------+
  Should be pure virtual.
  +-------                 END BOX 155                -------+

  +-------                BEGIN BOX 156               -------+
  Shall   we   impose   Library  uses  onto  performing  sync()...  make
  gbuffer/pbuffer empty every time they try to write after read or  vice
  versa, as in the current MSE.  -- mjv
  +-------                 END BOX 156                -------+

  +-------                BEGIN BOX 157               -------+
  No.   On  systems  where  this is necessary the basic_filebuf virtuals
  should keep track of the last operation performed on the FILE  and  do
  whatever  is neccessary (equivalent of an fseek?)  in order to reverse
  the direction.  -- jss
  +-------                 END BOX 157                -------+

  +-------                BEGIN BOX 158               -------+
  The following was not part of the proposal.  Should we keep it?
  +-------                 END BOX 158                -------+

  27.5.2.1.8  basic_filebuf::showmany            [lib.filebuf::showmany]
  //  virtual int showmany();    inherited

1 Behaves the same as basic_streambuf::showmany().47)

  _________________________
  47) An implementation might well provide an overriding definition  for
  this  function  signature if it can determine that more characters can
  be read from the input sequence.

  27.5.2.1.9  basic_filebuf::underflow          [lib.filebuf::underflow]
  //  virtual int_type underflow();    inherited

1 Behaves  the same as basic_convbuf<charT,baggage>::underflow(), except
  that the underlaid input character sequence is the  byte  sequence  in
  the file specified by file.

  +-------                BEGIN BOX 159               -------+
  Describing  the  behavior  about  maintaining  the conversion state is
  needed.
  +-------                 END BOX 159                -------+

  27.5.2.1.10  basic_filebuf::uflow                 [lib.filebuf::uflow]
  //  virtual int_type uflow();    inherited

1 Behaves the same as basic_convbuf<charT,baggage>::uflow().

  27.5.2.1.11  basic_filebuf::xsgetn               [lib.filebuf::xsgetn]
  //  virtual streamsize xsgetn(char_type* s, streamsize n);    inherited

1 Behaves the same as basic_convbuf<charT,baggage>::xsgetn(s,n).

  27.5.2.1.12  basic_filebuf::xsputn               [lib.filebuf::xsputn]
  //  virtual streamsize xsputn(const char_type* s, streamsize n);    inherited

1 Behaves the same as basic_convbuf<charT,baggage>::xsputn(s,n).

  27.5.2.1.13  basic_filebuf::seekoff             [lib.filebuf::seekoff]
  //  virtual pos_type seekoff(off_type off, basic_ios<charT,baggage>::seekdir way,
  //                           basic_ios<charT,baggage>::openmode which
  //                             = basic_ios<charT,baggage>::in
  //                             | basic_ios<charT,baggage>::out);    inherited

1 Alters the stream position within the controlled sequences, if  possi­
  ble, as described below.

2 Returns  a newly constructed pos_type object that stores the resultant
  stream position, if possible.  If the positioning operation fails,  or
  if  the  object  cannot  represent  the resultant stream position, the
  object stores an invalid stream position.

3 If file is a null pointer, the positioning  operation  fails.   Other­
  wise,  the  function  determines  one of three values for the argument
  whence, of type int, as indicated in Table 33:

                        Table 33--seekoff effects

                   +----------------------------------+
                   |  way Value      stdio Equivalent |
                   +----------------------------------+
                   |basic_ios::beg   SEEK_SET         |
                   |basic_ios::cur   SEEK_CUR         |
                   |basic_ios::end   SEEK_END         |
                   +----------------------------------+

4 The function then calls fseek(file, off, whence) and, if that function
  returns nonzero, the positioning operation fails.48)

5 The  function  extracts  the  conversion  state  from  off by means of
  get_offstate() to reset the state member.

  27.5.2.1.14  basic_filebuf::seekpos             [lib.filebuf::seekpos]
  //  virtual pos_type seekpos(pos_type sp,
  //                           basic_ios<charT,baggage>::openmode which
  //                             = basic_ios<charT,baggage>::in
  //                             | basic_ios<charT,baggage>::out);    inherited

  +-------                BEGIN BOX 160               -------+
  [To Be Filled]
  +-------                 END BOX 160                -------+

  27.5.2.1.15  basic_filebuf::setbuf               [lib.filebuf::setbuf]
  //  virtual basic_streambuf* setbuf(char_type* s, int n);    inherited

  +-------                BEGIN BOX 161               -------+
  [To Be Filled]
  +-------                 END BOX 161                -------+

  27.5.2.1.16  basic_filebuf::sync                   [lib.filebuf::sync]
  //  virtual int sync();    inherited

  +-------                BEGIN BOX 162               -------+
  [To Be Filled]
  +-------                 END BOX 162                -------+

  _________________________
  48)  The  macros SEEK_SET, SEEK_CUR, and SEEK_END are defined, and the
  function signature fseek(FILE*, long, int) is  declared,  in  <cstdio>
  (_lib.file.streams_).

  27.5.2.2  Template class basic_ifstream                 [lib.ifstream]
  template <class charT, class baggage = file_baggage<charT> >
  class basic_ifstream : public basic_istream<charT,baggage> {
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;
      int_type  eof()     { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }
  public:
      basic_ifstream();
      basic_ifstream(const char* s, openmode mode = in);
      virtual ~basic_ifstream();
      basic_filebuf<charT,baggage>* rdbuf() const;
      bool is_open();
      void open(const char* s, openmode mode = in);
  //  void open(const char* s, open_mode mode = in);    optional
      void close();
  private:
  //  basic_filebuf<charT,baggage> fb;    exposition only
  };
      class ifstream : public basic_ifstream<char> {};
      class wifstream : public basic_ifstream<wchar_t> {};

1 The   class   basic_ifstream<charT,baggage>   is   a   derivative   of
  basic_istream<charT,baggage>  that  assists  in  the  reading of named
  files.  It supplies a basic_filebuf<charT,baggage> object  to  control
  the associated sequence.

2 For the sake of exposition, the maintained data is presented here as:

  --basic_filebuf<charT,baggage> fb, the basic_filebuf object.

  27.5.2.2.1  basic_ifstream constructors      [lib.basic.ifstream.cons]
      basic_ifstream();

1 Constructs an object of class basic_ifstream<charT,baggage>,  initial­
  izing the base class with basic_istream<charT,baggage>(&fb).
      basic_ifstream(const char* s, openmode mode = in);

2 Constructs  an  object  of class basic_ifstream, initializing the base
  class  with  basic_istream<charT,baggage>(&fb),  then  calls   open(s,
  mode).

  27.5.2.2.2  basic_ifstream destructor         [lib.basic.ifstream.des]
      virtual ~basic_ifstream();

1 Destroys an object of class basic_ifstream<charT,baggage>.

  27.5.2.2.3  basic_ifstream::rdbuf                [lib.ifstream::rdbuf]
      basic_filebuf<charT,baggage>* rdbuf() const;

1 Returns fb.

  27.5.2.2.4  basic_ifstream::is_open            [lib.ifstream::is.open]
      bool is_open();

1 Returns fb.is_open().

  27.5.2.2.5  basic_ifstream::open                  [lib.ifstream::open]
      void open(const char* s, openmode mode = in);

1 Calls  fb.open(s,  mode).   If  is_open()  returns  zero,  calls  set­
  state(failbit).

  27.5.2.2.6  basic_ifstream::close                [lib.ifstream::close]
      void close();

1 Calls fb.close() and,  if  that  function  returns  zero,  calls  set­
  state(failbit).

  27.5.2.3  Template class basic_ofstream                 [lib.ofstream]
  template <class charT, class baggage = file_baggage<charT> >
  class basic_ofstream : public basic_ostream<charT,baggage> {
  public:
      typedef charT char_type;
      typedef baggage::char_bag::int_type int_type;
      typedef baggage::pos_bag::pos_type  pos_type;
      typedef baggage::pos_bag::off_type  off_type;
      int_type  eof()     { return baggage::char_bag::eof(); }
      char_type newline() { return baggage::char_bag::newline(); }
  public:
      basic_ofstream();
      basic_ofstream(const char* s, openmode mode = out);
      virtual ~basic_ofstream();
      basic_filebuf<charT,baggage>* rdbuf() const;
      bool is_open();
      void open(const char* s, openmode mode = out | trunc);
  //  void open(const char* s, open_mode mode = out | trunc);    optional
      void close();
  private:
  //  basic_filebuf<charT,baggage> fb;    exposition only
  };
      class ofstream : public basic_ofstream<char> {};
      class wofstream : public basic_ofstream<wchar_t> {};

1 The   class   basic_ofstream<charT,baggage>   is   a   derivative   of
  basic_ostream<charT,baggage> that assists  in  the  writing  of  named
  files.   It  supplies a basic_filebuf<charT,baggage> object to control
  the associated sequence.

2 For the sake of exposition, the maintained data is presented here as:

  --basic_filebuf<charT,baggage> fb, the basic_filebuf object.

  27.5.2.3.1  basic_ofstream constructors      [lib.basic.ofstream.cons]
      basic_ofstream();

1 Constructs  an object of class basic_ofstream<charT,baggage>, initial­
  izing the base class with basic_ostream<charT,baggage>(&fb).
      basic_ofstream(const char* s, openmode mode = out);

2 Constructs an object of class basic_ofstream<charT,baggage>,  initial­
  izing  the  base  class  with  basic_ostream<charT,baggage>(&fb), then
  calls open(s, mode).

  27.5.2.3.2  basic_ofstream destructor         [lib.basic.ofstream.des]
      virtual ~basic_ofstream();

1 Destroys an object of class basic_ofstream<charT,baggage>.

  27.5.2.3.3  basic_ofstream::rdbuf                [lib.ofstream::rdbuf]
      basic_filebuf<charT,baggage>* rdbuf() const;

1 Returns (basic_filebuf<charT,baggage>*)&fb.

  27.5.2.3.4  basic_ofstream::is_open            [lib.ofstream::is.open]
      bool is_open();

1 Returns fb.is_open().

  27.5.2.3.5  basic_ofstream::open                  [lib.ofstream::open]
      void open(const char* s, openmode mode = out);

1 Calls fb.open(s, mode).   If  is_open()  is  then  false,  calls  set­
  state(failbit).

  27.5.2.3.6  basic_ofstream::close                [lib.ofstream::close]
      void close();

1 Calls  fb.close()  and,  if  that  function  returns  zero, calls set­
  state(failbit).

  27.5.3  stdio streams                             [lib.stdio.fstreams]

  27.5.3.1  Template class basic_stdiobuf           [lib.basic.stdiobuf]

  +-------                BEGIN BOX 163               -------+
  basic_stdiobuf may be useful, and it is based on (untemplatized)  cur­
  rent  practice,  but  there  is  nothing  fundamental in it (it can be
  defined by a user in a fully portable and efficient way) no other part
  of  the workiing paper depends on it and it is used relatively little.
  So in the interests of keeping the working paper small

1 Jerry Schwarz proposal: Delete this section.
  +-------                 END BOX 163                -------+

      template <class charT, class baggage = stdio_baggage<charT> >
      class basic_stdiobuf : public streambuf<charT,baggage> {
      public:
          typedef charT char_type;
          typedef baggage::char_bag::int_type int_type;
          typedef baggage::pos_bag::pos_type  pos_type;
          typedef baggage::pos_bag::off_type  off_type;
          int_type  eof()     { return baggage::char_bag::eof(); }
          char_type newline() { return baggage::char_bag::newline(); }
      public:
      basic_stdiobuf(FILE* file_arg = 0);
      virtual ~basic_stdiobuf();
      bool buffered() const;
      void buffered(bool buf_fl);
      protected:
  //  virtual int_type overflow (int_type c = eof());     inherited
  //  virtual int_type pbackfail(int_type c = eof());     inherited

  +-------                BEGIN BOX 164               -------+
  The following was not part of the proposal.  Should we keep it?
  +-------                 END BOX 164                -------+

  //  virtual int      showmany();        inherited
  //  virtual int_type underflow();       inherited
  //  virtual int_type uflow();   inherited
  //  virtual streamsize xsgetn(char_type* s, streamsize n);      inherited
  //  virtual streamsize xsputn(const char_type* s, streamsize n);        inherited
  //  virtual pos_type seekoff(off_type off, basic_ios<charT,baggage>::seekdir way,
  //                           basic_ios<charT,baggage>::openmode which
  //                             = basic_ios<charT,baggage>::in
  //                             | basic_ios<charT,baggage>::out);        inherited
  //  virtual pos_type seekpos(pos_type sp,
  //                           basic_ios<charT,baggage>::openmode which
  //                             = basic_ios<charT,baggage>::in
  //                             | basic_ios<charT,baggage>::out);        inherited
  //  virtual int sync(); inherited
  private:
  //  FILE* file; exposition only
  //  bool is_buffered;                           exposition only
      };

  +-------                BEGIN BOX 165               -------+
  [To Be Filled]
  +-------                 END BOX 165                -------+

2 The    class    basic_stdiobuf<charT,baggage>    is    derived    from
  basic_streambuf<charT,baggage>  to  associate  both the input sequence
  and the output sequence with an externally  supplied  object  of  type
  FILE.49)

  _________________________
  49) Type FILE is defined in <cstdio> (_lib.file.streams_).

3 For the sake of exposition, the maintained data is presented here as:

  --FILE *file, points to the FILE associated with the stream buffer;

  --bool is_buffered, nonzero if the basic_stdiobuf object is  buffered,
    and hence need not be kept synchronized with the associated file (as
    described below).

4 The restrictions on reading and writing a sequence  controlled  by  an
  object  of class basic_stdiobuf are the same as for an object of class
  basic_filebuf.

5 If an basic_stdiobuf object is not buffered and file  is  not  a  null
  pointer, it is kept synchronized with the associated file, as follows:
  as indicated in Table 34:50)

                    Table 34--stdiobuf synchronization

                    +--------------------------------+
                    |  stdiobuf     stdio Equivalent |
                    +--------------------------------+
                    |sputc(c)       fputc(c,file)    |
                    |sputbackc(c)   ungetc(c,file)   |
                    |sbumpc()       fgetc(file)      |
                    +--------------------------------+

  27.5.3.1.1                                   [lib.basic.stdiobuf.cons]
       basic_stdiobuf::basic_stdiobuf
       constructor
      basic_stdiobuf(FILE* file_arg = 0);

1 Constructs  an object of class basic_stdiobuf<charT,baggage>, initial­
  izing the base class with basic_streambuf<charT,baggage>(),  and  ini­
  tializing file to file_arg and is_buffered to zero.

  27.5.3.1.2  basic_stdiobuf destructor         [lib.basic.stdiobuf.des]
      virtual ~basic_stdiobuf();

1 Destroys an object of class basic_stdiobuf<charT,baggage>.

  27.5.3.1.3                              [lib.basic.stdiobuf::buffered]
       basic_stdiobuf::buffered
      bool buffered() const;

1 Returns true if is_buffered is nonzero.
      void buffered(bool buf_fl);

  _________________________
  50) The functions fgetc(FILE*),  fputc(int,  FILE*),  and  ungetc(int,
  FILE*) are declared in <cstdio> (_lib.file.streams_).

2 Assigns buf_fl to is_buffered.

  27.5.3.1.4                              [lib.basic.stdiobuf::overflow]
       basic_stdiobuf::overflow
  //  virtual int_type overflow(int_type c = eof());    inherited

1 Behaves  the same as basic_filebuf<charT,baggage>::overflow(int), sub­
  ject to the buffering requirements specified by is_buffered.

  27.5.3.1.5                             [lib.basic.stdiobuf::pbackfail]
       basic_stdiobuf::pbackfail
  //  virtual int_type pbackfail(int_type c = eof());    inherited

1 Behaves the same as basic_filebuf<charT,baggage>::pbackfail(int), sub­
  ject to the buffering requirements specified by is_buffered.

  +-------                BEGIN BOX 166               -------+
  The following was not part of the proposal.  Should we keep it?
  +-------                 END BOX 166                -------+

  27.5.3.1.6                              [lib.basic.stdiobuf::showmany]
       basic_stdiobuf::showmany
  //  virtual int showmany();    inherited

1 Behaves the same as basic_streambuf<charT,baggage>::showmany().51)

  27.5.3.1.7                             [lib.basic.stdiobuf::underflow]
       basic_stdiobuf::underflow
  //  virtual int_type underflow();    inherited

1 Behaves the same as basic_filebuf<charT,baggage>::underflow(), subject
  to the buffering requirements specified by is_buffered.

  27.5.3.1.8  basic_stdiobuf::uflow          [lib.basic.stdiobuf::uflow]
  //  virtual int_type uflow();    inherited

1 Behaves  the same as basic_filebuf<charT,baggage>::uflow(), subject to
  the buffering requirements specified by is_buffered.

  27.5.3.1.9  basic_stdiobuf::xsgetn        [lib.basic.stdiobuf::xsgetn]
  //  virtual streamsize xsgetn(char_type* s, streamsize n);    inherited

1 Behaves the same as basic_streambuf<charT,baggage>::xsgetn(s,n).

  _________________________
  51)  An implementation might well provide an overriding definition for
  this function signature if it can determine that more  characters  can
  be read from the input sequence.

  27.5.3.1.10  basic_stdiobuf::xsputn       [lib.basic.stdiobuf::xsputn]
  //  virtual streamsize xsputn(const char_type* s, streamsize n);    inherited

1 Behaves the same as basic_streambuf<charT,baggage>::xsputn(s,n).

  27.5.3.1.11                              [lib.basic.stdiobuf::seekoff]
       basic_stdiobuf::seekoff
  //  virtual pos_type seekoff(off_type off, basic_ios<charT,baggage>::seekdir way,
  //                           basic_ios<charT,baggage>::openmode which
  //                             = basic_ios<charT,baggage>::in
  //                             | basic_ios<charT,baggage>::out);    inherited

1 Behaves                  the                  same                  as
  basic_filebuf<charT,baggage>::seekoff(off,way,which)

  27.5.3.1.12                              [lib.basic.stdiobuf::seekpos]
       basic_stdiobuf::seekpos
  //  virtual pos_type seekpos(pos_type sp,
  //                           basic_ios<charT,baggage>::openmode which
  //                             = basic_ios<charT,baggage>::in
  //                             | basic_ios<charT,baggage>::out);    inherited

1 Behaves the same as basic_filebuf<charT,baggage>::seekpos(sp,which)

  27.5.3.1.13  basic_stdiobuf::setbuf       [lib.basic.stdiobuf::setbuf]
  //  virtual basic_streambuf<charT,baggage>* setbuf(char_type* s, int n);    inherited

1 Behaves the same as basic_filebuf<charT,baggage>::setbuf(s,n)

  27.5.3.1.14  basic_stdiobuf::sync           [lib.basic.stdiobuf::sync]
  //  virtual int sync();    inherited

1 Behaves the same as basic_filebufs,n::sync()

  27.5.3.2  Class istdiostream                        [lib.istdiostream]
      class istdiostream : public basic_istream<char> {
      public:
          istdiostream(FILE* file_arg = 0);
          virtual ~istdiostream();
          basic_stdiobuf<char>* rdbuf() const;
          bool buffered() const;
          void buffered(bool buf_fl);
      private:
  //      basic_stdiobuf<char> fb;        exposition only
      };

1 The class istdiostream is a derivative of basic_istream<charT,baggage>
  that assists in the reading of files controlled  by  objects  of  type
  FILE.   It  supplies a basic_stdiobuf<charT,baggage> object to control
  the associated sequence.

2 For the sake of exposition, the maintained data is presented here as:

  --basic_stdiobuf fb, the basic_stdiobuf object.

  27.5.3.2.1  istdiostream::istdiostream         [lib.istdiostream.cons]
       constructor
      istdiostream(FILE* file_arg = 0);

1 Constructs  an  object  of  class  istdiostream, initializing the base
  class   with   basic_istream(&fb)    and    initializing    fb    with
  basic_stdiobuf(file_arg).

  27.5.3.2.2  istdiostream destructor             [lib.istdiostream.des]
      virtual ~istdiostream();

1 Destroys an object of class istdiostream.

  27.5.3.2.3  istdiostream::rdbuf              [lib.istdiostream::rdbuf]
      basic_stdiobuf<char>* rdbuf() const;

1 Returns fb.

  27.5.3.2.4  istdiostream::buffered        [lib.istdiostream::buffered]
      bool buffered() const;

1 Returns true if is_buffered is nonzero.

  27.5.3.2.5  istdiostream::buffered      [lib.istdiostream::buffered.b]
      void buffered(bool buf_fl);

1 Assigns buf_fl to is_buffered.

  27.5.3.3  Class ostdiostream                        [lib.ostdiostream]
      class ostdiostream : public basic_ostream<char> {
      public:
          ostdiostream(FILE* file_arg = 0);
          virtual ~ostdiostream();
          basic_stdiobuf<char>* rdbuf() const;
          bool buffered() const;
          void buffered(bool buf_fl);
      private:
  //      basic_stdiobuf<char> fb;        exposition only
      };

1 The class ostdiostream is a derivative of basic_ostream  that  assists
  in  the  writing of files controlled by objects of type FILE.  It sup­
  plies a basic_stdiobuf object to control the associated sequence.

2 For the sake of exposition, the maintained data is presented here as:

  --basic_stdiobuf<char> fb, the basic_stdiobuf object.

  27.5.3.3.1  ostdiostream constructor           [lib.ostdiostream.cons]
      ostdiostream(FILE* file_arg = 0);

1 Constructs an object of  class  ostdiostream,  initializing  the  base
  class    with    basic_ostream(&fb)    and    initializing   fb   with
  basic_stdiobuf(file_arg).

  27.5.3.3.2  ostdiostream destructor             [lib.ostdiostream.des]
      virtual ~ostdiostream();

1 Destroys an object of class ostdiostream.

  27.5.3.3.3  ostdiostream::rdbuf              [lib.ostdiostream::rdbuf]
      basic_stdiobuf<char>* rdbuf() const;

1 Returns fb.

  27.5.3.3.4  ostdiostream::buffered        [lib.ostdiostream::buffered]
      bool buffered() const;

1 Returns true if is_buffered is nonzero.

  27.5.3.3.5  ostdiostream::buffered      [lib.ostdiostream::buffered.b]
      void buffered(bool buf_fl);

1 Assigns buf_fl to is_buffered.