27 Input/output library [input.output]

Returns: The format control information for both input and output.

Postcondition: fmtfl == flags().

Returns: The previous value of flags().

Effects: Sets fmtfl in flags().

Returns: The previous value of flags().

Effects: Clears mask in flags(), sets fmtfl & mask in flags().

Returns: The previous value of flags().

Effects: Clears mask in flags().

Returns: The precision to generate on certain output conversions.

Postcondition: prec == precision().

Returns: The previous value of precision().

Returns: The minimum field width (number of characters) to generate on certain output conversions.

Postcondition: wide == width().

Returns: The previous value of width().

Effects: Calls each registered callback pair (fn,index) ([ios.base.callback]) as (*fn)(imbue_event,*this,index) at such a time that a call to ios_base::getloc() from within fn returns the new locale value loc.

Returns: The previous value of getloc().

Postcondition: loc == getloc().

Returns: If no locale has been imbued, a copy of the global C++ locale, locale(), in effect at the time of construction. Otherwise, returns the imbued locale, to be used to perform locale-dependent input and output operations.

Returns: true if the previous state of the standard iostream objects ([iostream.objects]) was synchronized and otherwise returns false. The first time it is called, the function returns true.

Effects: If any input or output operation has occurred using the standard streams prior to the call, the effect is implementation-defined. Otherwise, called with a false argument, it allows the standard streams to operate independently of the standard C streams.

When a standard iostream object str is synchronized with a standard stdio stream f, the effect of inserting a character c by

fputc(f, c);

is the same as the effect of

str.rdbuf()->sputc(c);

for any sequences of characters; the effect of extracting a character c by

c = fgetc(f);

is the same as the effect of

c = str.rdbuf()->sbumpc(c);

for any sequences of characters; and the effect of pushing back a character c by

ungetc(c, f);

is the same as the effect of

str.rdbuf()->sputbackc(c);

for any sequence of characters.299

Returns: index ++.

Effects: If iarray is a null pointer, allocates an array of long of unspecified size and stores a pointer to its first element in iarray. The function 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. The reference returned is invalid after any other operations on the object.300 However, the value of the storage referred to is retained, so that until the next call to copyfmt, calling iword with the same index yields another reference to the same value. If the function fails301 and *this is a base subobject of a basic_ios<> object or subobject, the effect is equivalent to calling basic_ios<>::setstate(badbit) on the derived object (which may throw failure).

Returns: On success iarray[idx]. On failure, a valid long& initialized to 0.

Effects: 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. The reference returned is invalid after any other operations on the object. However, the value of the storage referred to is retained, so that until the next call to copyfmt, calling pword with the same index yields another reference to the same value. If the function fails302 and *this is a base subobject of a basic_ios<> object or subobject, the effect is equivalent to calling basic_ios<>::setstate(badbit) on the derived object (which may throw failure).

Returns: On success parray[idx]. On failure a valid void*& initialized to 0.

Remarks: After a subsequent call to pword(int) for the same object, the earlier return value may no longer be valid.

Effects: Registers the pair (fn,index) such that during calls to imbue() ([ios.base.locales]), copyfmt(), or ~ios_base() ([ios.base.cons]), the function fn is called with argument index. Functions registered are called when an event occurs, in opposite order of registration. Functions registered while a callback function is active are not called until the next event.

Requires: The function fn shall not throw exceptions.

Remarks: Identical pairs are not merged. A function registered twice will be called twice.

Effects: Each ios_base member has an indeterminate value after construction. The object's members shall be initialized by calling basic_ios::init before the object's first use or before it is destroyed, whichever comes first; otherwise the behavior is undefined.

Effects: Destroys an object of class ios_base. Calls each registered callback pair (fn, index) ([ios.base.callback]) as (*fn)(erase_event, *this, index) at such time that any ios_base member function called from within fn has well defined results.

Effects: Assign s to st.

Returns: Current value of st.

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

Effects: Constructs an object of class basic_ios ([ios.base.cons]) leaving its member objects uninitialized. The object shall be initialized by calling basic_ios::init before its first use or before it is destroyed, whichever comes first; otherwise the behavior is undefined.

Remarks: The destructor does not destroy rdbuf().

Returns: An output sequence that is tied to (synchronized with) the sequence controlled by the stream buffer.

Requires: If tiestr is not null, tiestr must not be reachable by traversing the linked list of tied stream objects starting from tiestr->tie().

Postcondition: tiestr == tie().

Returns: The previous value of tie().

Returns: A pointer to the streambuf associated with the stream.

Postcondition: sb == rdbuf().

Effects: Calls clear().

Returns: The previous value of rdbuf().

Effects: Calls ios_base::imbue(loc) ([ios.base.locales]) and if rdbuf()!=0 then rdbuf()->pubimbue(loc) ([streambuf.locales]).

Returns: The prior value of ios_base::imbue().

Returns: use_facet< ctype<char_type> >(getloc()).narrow(c,dfault)

Returns: use_facet< ctype<char_type> >(getloc()).widen(c)

Returns: The character used to pad (fill) an output conversion to the specified field width.

Postcondition: traits::eq(fillch, fill())

Returns: The previous value of fill().

Effects: If (this == &rhs) does nothing. Otherwise assigns to the member objects of *this the corresponding member objects of rhs as follows:

1. 1.

   calls each registered callback pair (fn, index) as (*fn)(erase_event, *this, index);

2. 2.

   assigns to the member objects of *this the corresponding member objects of rhs, except that

   • (16.2.1)

     rdstate(), rdbuf(), and exceptions() are left unchanged;

   • (16.2.2)

     the contents of arrays pointed at by pword and iword are copied, not the pointers themselves;303 and

   • (16.2.3)

     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. 3.

   calls each callback pair that was copied from rhs as (*fn)(copyfmt_event, *this, index);

4. 4.

   calls exceptions(rhs.except()).

Note: The second pass through the callback pairs permits a copied pword value to be zeroed, or to have its referent deep copied or reference counted, or to have other special action taken.

Postconditions: The postconditions of this function are indicated in Table [tab:iostreams.copyfmt.effects].

Returns: *this.

Postconditions: *this shall have the state that rhs had before the function call, except that rdbuf() shall return 0. rhs shall be in a valid but unspecified state, except that rhs.rdbuf() shall return the same value as it returned before the function call, and rhs.tie() shall return 0.

Effects: The states of *this and rhs shall be exchanged, except that rdbuf() shall return the same value as it returned before the function call, and rhs.rdbuf() shall return the same value as it returned before the function call.

Requires: sb != nullptr.

Effects: Associates the basic_streambuf object pointed to by sb with this stream without calling clear().

Postconditions: rdbuf() == sb.

Throws: Nothing.

Returns: !fail().

Returns: fail().

Returns: The error state of the stream buffer.

Postcondition: If rdbuf()!=0 then state == rdstate(); otherwise rdstate()==(state | ios_base::badbit).

Effects: If ((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0, returns. Otherwise, the function throws an object fail of class basic_ios::failure ([ios::failure]), constructed with implementation-defined argument values.

Effects: Calls clear(rdstate() | state) (which may throw basic_ios::failure ([ios::failure])).

Returns: rdstate() == 0

Returns: true if eofbit is set in rdstate().

Returns: true if failbit or badbit is set in rdstate().304

Returns: true if badbit is set in rdstate().

Returns: A mask that determines what elements set in rdstate() cause exceptions to be thrown.

Postcondition: except == exceptions().

Effects: Calls clear(rdstate()).

Effects: Calls str.setf(ios_base::boolalpha).

Returns: str.

Effects: Calls str.unsetf(ios_base::boolalpha).

Returns: str.

Effects: Calls str.setf(ios_base::showbase).

Returns: str.

Effects: Calls str.unsetf(ios_base::showbase).

Returns: str.

Effects: Calls str.setf(ios_base::showpoint).

Returns: str.

Effects: Calls str.unsetf(ios_base::showpoint).

Returns: str.

Effects: Calls str.setf(ios_base::showpos).

Returns: str.

Effects: Calls str.unsetf(ios_base::showpos).

Returns: str.

Effects: Calls str.setf(ios_base::skipws).

Returns: str.

Effects: Calls str.unsetf(ios_base::skipws).

Returns: str.

Effects: Calls str.setf(ios_base::uppercase).

Returns: str.

Effects: Calls str.unsetf(ios_base::uppercase).

Returns: str.

Effects: Calls str.setf(ios_base::unitbuf).

Returns: str.

Effects: Calls str.unsetf(ios_base::unitbuf).

Returns: str.

Effects: Calls str.setf(ios_base::internal, ios_base::adjustfield).

Returns: str.

Effects: Calls str.setf(ios_base::left, ios_base::adjustfield).

Returns: str.

Effects: Calls str.setf(ios_base::right, ios_base::adjustfield).

Returns: str.

Effects: Calls str.setf(ios_base::dec, ios_base::basefield).

Returns: str305.

Effects: Calls str.setf(ios_base::hex, ios_base::basefield).

Returns: str.

Effects: Calls str.setf(ios_base::oct, ios_base::basefield).

Returns: str.

Effects: Calls str.setf(ios_base::fixed, ios_base::floatfield).

Returns: str.

Effects: Calls str.setf(ios_base::scientific, ios_base::floatfield).

Returns: str.

Effects: Calls str.setf(ios_base::fixed | ios_base::scientific, ios_base::floatfield).

Returns: str.

Effects: Calls str.unsetf(ios_base::floatfield).

Returns: str.

Returns: error_code(static_cast<int>(e), iostream_category()).

Returns: error_condition(static_cast<int>(e), iostream_category()).

Returns: A reference to an object of a type derived from class error_category.

The object's default_error_condition and equivalent virtual functions shall behave as specified for the class error_category. The object's name virtual function shall return a pointer to the string "iostream".

Effects: Constructs an object of class basic_streambuf<charT,traits> and initializes:306

• (1.1)

  all its pointer member objects to null pointers,

• (1.2)

  the getloc() member to a copy the global locale, locale(), at the time of construction.

Remarks: Once the getloc() member is initialized, results of calling locale member functions, and of members of facets so obtained, can safely be cached until the next time the member imbue is called.

Effects: Constructs a copy of rhs.

Postconditions:

• (4.1)

  eback() == rhs.eback()

• (4.2)

  gptr() == rhs.gptr()

• (4.3)

  egptr() == rhs.egptr()

• (4.4)

  pbase() == rhs.pbase()

• (4.5)

  pptr() == rhs.pptr()

• (4.6)

  epptr() == rhs.epptr()

• (4.7)

  getloc() == rhs.getloc()

Effects: None.

Effects: None. This member function does not behave as an unformatted input function (as described in [istream.unformatted], paragraph 1).

Returns: The number of characters extracted by the last unformatted input member function called for the object.

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1). After constructing a sentry object, extracts a character c, if one is available. Otherwise, the function calls setstate(failbit), which may throw ios_base::failure ([iostate.flags]),

Returns: c if available, otherwise traits::eof().

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1). After constructing a sentry object, extracts a character, if one is available, and assigns it to c.318 Otherwise, the function calls setstate(failbit) (which may throw ios_base::failure ([iostate.flags])).

Returns: *this.

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1). After constructing a sentry object, extracts characters and stores them into successive locations of an array whose first element is designated by s.319 Characters are extracted and stored until any of the following occurs:

• (8.1)

  n is less than one or n - 1 characters are stored;

• (8.2)

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

• (8.3)

  traits::eq(c, delim) for the next available input character c (in which case c is not extracted).

If the function stores no characters, it calls setstate(failbit) (which may throw ios_base::failure ([iostate.flags])). In any case, if n is greater than zero it then stores a null character into the next successive location of the array.

Returns: *this.

Effects: Calls get(s,n,widen('\n'))

Returns: Value returned by the call.

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1). After constructing a sentry object, extracts characters and inserts them in the output sequence controlled by sb. Characters are extracted and inserted until any of the following occurs:

• (13.1)

  end-of-file occurs on the input sequence;

• (13.2)

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

• (13.3)

  traits::eq(c, delim) for the next available input character c (in which case c is not extracted);

• (13.4)

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

If the function inserts no characters, it calls setstate(failbit), which may throw ios_base::failure ([iostate.flags]).

Returns: *this.

Effects: Calls get(sb, widen('\n'))

Returns: Value returned by the call.

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1). After constructing a sentry object, extracts characters and stores them into successive locations of an array whose first element is designated by s.320 Characters are extracted and stored until one of the following occurs:

1. 1.

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

2. 2.

   traits::eq(c, delim) for the next available input character c (in which case the input character is extracted but not stored);321

3. 3.

   n is less than one or n - 1 characters are stored (in which case the function calls setstate(failbit)).

These conditions are tested in the order shown.322

If the function extracts no characters, it calls setstate(failbit) (which may throw ios_base::failure ([iostate.flags])).323

In any case, if n is greater than zero, it then stores a null character (using charT()) into the next successive location of the array.

Returns: *this.

[ Example:

#include <iostream>

int main() {
  using namespace std;
  const int line_buffer_size = 100;

  char buffer[line_buffer_size];
  int line_number = 0;
  while (cin.getline(buffer, line_buffer_size, '\n') || 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_base::failbit);
    } else {
      count--;                        // Don't include newline in count
      cout << "Line " << ++line_number;
    }
    cout << " (" << count << " chars): " << buffer << endl;
  }
}

 — end example ]

Returns: getline(s,n,widen('\n'))

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1). After constructing a sentry object, extracts characters and discards them. Characters are extracted until any of the following occurs:

• (25.1)

  if n != numeric_limits<streamsize>::max() ([limits]), n characters are extracted

• (25.2)

  end-of-file occurs on the input sequence (in which case the function calls setstate(eofbit), which may throw ios_base::failure ([iostate.flags]));

• (25.3)

  traits::eq_int_type(traits::to_int_type(c), delim) for the next available input character c (in which case c is extracted).

Remarks: The last condition will never occur if traits::eq_int_type(delim, traits::eof()).

Returns: *this.

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1). After constructing a sentry object, reads but does not extract the current input character.

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

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1). After constructing a sentry object, if !good() calls setstate(failbit) which may throw an exception, and return. Otherwise extracts characters and stores them into successive locations of an array whose first element is designated by s.324 Characters are extracted and stored until either of the following occurs:

• (30.1)

  n characters are stored;

• (30.2)

  end-of-file occurs on the input sequence (in which case the function calls setstate(failbit | eofbit), which may throw ios_base::failure ([iostate.flags])).

Returns: *this.

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1). After constructing a sentry object, if !good() calls setstate(failbit) which may throw an exception, and return. Otherwise extracts characters and stores them into successive locations of an array whose first element is designated by s. If rdbuf()->in_avail() == -1, calls setstate(eofbit) (which may throw ios_base::failure ([iostate.flags])), and extracts no characters;

• (32.1)

  If rdbuf()->in_avail() == 0, extracts no characters

• (32.2)

  If rdbuf()->in_avail() > 0, extracts min(rdbuf()->in_avail(),n)).

Returns: The number of characters extracted.

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1), except that the function first clears eofbit. After constructing a sentry object, if !good() calls setstate(failbit) which may throw an exception, and return. If rdbuf() is not null, calls rdbuf->sputbackc(). If rdbuf() is null, or if sputbackc() returns traits::eof(), calls setstate(badbit) (which may throw ios_base::failure ([iostate.flags])). [ Note: This function extracts no characters, so the value returned by the next call to gcount() is 0.  — end note ]

Returns: *this.

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1), except that the function first clears eofbit. After constructing a sentry object, if !good() calls setstate(failbit) which may throw an exception, and return. If rdbuf() is not null, calls rdbuf()->sungetc(). If rdbuf() is null, or if sungetc() returns traits::eof(), calls setstate(badbit) (which may throw ios_base::failure ([iostate.flags])). [ Note: This function extracts no characters, so the value returned by the next call to gcount() is 0.  — end note ]

Returns: *this.

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1), except that it does not count the number of characters extracted and does not affect the value returned by subsequent calls to gcount(). After constructing a sentry object, if rdbuf() is a null pointer, returns -1 . Otherwise, calls rdbuf()->pubsync() and, if that function returns -1 calls setstate(badbit) (which may throw ios_base::failure ([iostate.flags]), and returns -1. Otherwise, returns zero.

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1), except that it does not count the number of characters extracted and does not affect the value returned by subsequent calls to gcount().

Returns: After constructing a sentry object, if fail() != false, returns pos_type(-1) to indicate failure. Otherwise, returns rdbuf()->pubseekoff(0, cur, in).

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1), except that the function first clears eofbit, it does not count the number of characters extracted, and it does not affect the value returned by subsequent calls to gcount(). After constructing a sentry object, if fail() != true, executes rdbuf()->pubseekpos(pos, ios_base::in). In case of failure, the function calls setstate(failbit) (which may throw ios_base::failure).

Returns: *this.

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1), except that it does not count the number of characters extracted and does not affect the value returned by subsequent calls to gcount(). After constructing a sentry object, if fail() != true, executes rdbuf()->pubseekoff(off, dir, ios_base::in). In case of failure, the function calls setstate(failbit) (which may throw ios_base::failure).

Returns: *this.

Effects: Behaves as an unformatted input function (as described in [istream.unformatted], paragraph 1), except that it does not count the number of characters extracted and does not affect the value returned by subsequent calls to is.gcount(). After constructing a sentry object extracts characters as long as the next available character c is whitespace or until there are no more characters in the sequence. Whitespace characters are distinguished with the same criterion as used by sentry::sentry ([istream::sentry]). If ws stops extracting characters because there are no more available it sets eofbit, but not failbit.

Returns: is.

Effects: is >> x

Returns: is

Effects: Constructs an object of class basic_ostream, assigning initial values to the base class by calling basic_ios<charT,traits>::init(sb) ([basic.ios.cons]).

Postcondition: rdbuf() == sb.

virtual ~basic_ostream();

Effects: Destroys an object of class basic_ostream.

Remarks: Does not perform any operations on rdbuf().

Effects: Move constructs from the rvalue rhs. This is accomplished by default constructing the base class and calling basic_ios<charT, traits>::move(rhs) to initialize the base class.

Effects: swap(rhs).

Returns: *this.

Effects: Calls basic_ios<charT, traits>::swap(rhs).

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

If, after any preparation is completed, os.good() is true, ok_ == true otherwise, ok_ == false. During preparation, the constructor may call setstate(failbit) (which may throw ios_base::failure ([iostate.flags]))326

If ((os.flags() & ios_base::unitbuf) && !uncaught_exception() && os.good()) is true, calls os.rdbuf()->pubsync(). If that function returns -1, sets badbit in os.rdstate() without propagating an exception.

Effects: Returns ok_.

Returns: If fail() != false, returns pos_type(-1) to indicate failure. Otherwise, returns rdbuf()->pubseekoff(0, cur, out). basic_ostream<charT,traits>& seekp(pos_type pos);

Effects: If fail() != true, executes rdbuf()->pubseekpos(pos, ios_base::out). In case of failure, the function calls setstate(failbit) (which may throw ios_base::failure).

Returns: *this.

Effects: If fail() != true, executes rdbuf()->pubseekoff(off, dir, ios_base::out).

Returns: *this.

Effects: Behaves as an unformatted output function (as described in [ostream.unformatted], paragraph 1). After constructing a sentry object, inserts the character c, if possible.331

Otherwise, calls setstate(badbit) (which may throw ios_base::failure ([iostate.flags])).

Returns: *this.

Effects: Behaves as an unformatted output function (as described in [ostream.unformatted], paragraph 1). After constructing a sentry object, obtains characters to insert from successive locations of an array whose first element is designated by s.332 Characters are inserted until either of the following occurs:

• (5.1)

  n characters are inserted;

• (5.2)

  inserting in the output sequence fails (in which case the function calls setstate(badbit), which may throw ios_base::failure ([iostate.flags])).

Returns: *this.

Effects: Behaves as an unformatted output function (as described in [ostream.formatted.reqmts], paragraph 1). If rdbuf() is not a null pointer, constructs a sentry object. If this object returns true when converted to a value of type bool the function calls rdbuf()->pubsync(). If that function returns -1 calls setstate(badbit) (which may throw ios_base::failure ([iostate.flags])). Otherwise, if the sentry object returns false, does nothing.

Returns: *this.

Effects: Calls os.put(os.widen('\n')), then os.flush().

Returns: os.

Effects: Inserts a null character into the output sequence: calls os.put(charT()).

Returns: os.

Effects: Calls os.flush().

Returns: os.

Effects: os << x

Returns: os

Effects: Constructs an object of class basic_stringbuf, initializing the base class with basic_streambuf() ([streambuf.cons]), and initializing mode with which.

Postcondition: str() == "".

Effects: Constructs an object of class basic_stringbuf, initializing the base class with basic_streambuf() ([streambuf.cons]), and initializing mode with which. Then calls str(s).

Effects: Move constructs from the rvalue rhs. It is implementation-defined whether the sequence pointers in *this (eback(), gptr(), egptr(), pbase(), pptr(), epptr()) obtain the values which rhs had. Whether they do or not, *this and rhs reference separate buffers (if any at all) after the construction. The openmode, locale and any other state of rhs is also copied.

Postconditions: Let rhs_p refer to the state of rhs just prior to this construction and let rhs_a refer to the state of rhs just after this construction.

• (5.1)

  str() == rhs_p.str()

• (5.2)

  gptr() - eback() == rhs_p.gptr() - rhs_p.eback()

• (5.3)

  egptr() - eback() == rhs_p.egptr() - rhs_p.eback()

• (5.4)

  pptr() - pbase() == rhs_p.pptr() - rhs_p.pbase()

• (5.5)

  epptr() - pbase() == rhs_p.epptr() - rhs_p.pbase()

• (5.6)

  if (eback()) eback() != rhs_a.eback()

• (5.7)

  if (gptr()) gptr() != rhs_a.gptr()

• (5.8)

  if (egptr()) egptr() != rhs_a.egptr()

• (5.9)

  if (pbase()) pbase() != rhs_a.pbase()

• (5.10)

  if (pptr()) pptr() != rhs_a.pptr()

• (5.11)

  if (epptr()) epptr() != rhs_a.epptr()

Effects: After the move assignment *this has the observable state it would have had if it had been move constructed from rhs (see [stringbuf.cons]).

Returns: *this.

Effects: Exchanges the state of *this and rhs.

Effects: x.swap(y).

Returns: A basic_string object whose content is equal to the basic_stringbuf underlying character sequence. If the basic_stringbuf was created only in input mode, the resultant basic_string contains the character sequence in the range [eback(),egptr()). If the basic_stringbuf was created with which & ios_base::out being true then the resultant basic_string contains the character sequence in the range [pbase(),high_mark), where high_mark represents the position one past the highest initialized character in the buffer. Characters can be initialized by writing to the stream, by constructing the basic_stringbuf with a basic_string, or by calling the str(basic_string) member function. In the case of calling the str(basic_string) member function, all characters initialized prior to the call are now considered uninitialized (except for those characters re-initialized by the new basic_string). Otherwise the basic_stringbuf has been created in neither input nor output mode and a zero length basic_string is returned.

Effects: Copies the content of s into the basic_stringbuf underlying character sequence and initializes the input and output sequences according to mode.

Postconditions: If mode & ios_base::out is true, pbase() points to the first underlying character and epptr() >= pbase() + s.size() holds; in addition, if mode & ios_base::ate is true, pptr() == pbase() + s.size() holds, otherwise pptr() == pbase() is true. If mode & ios_base::in is true, eback() points to the first underlying character, and both gptr() == eback() and egptr() == eback() + s.size() hold.

Returns: If the input sequence has a read position available, returns traits::to_int_type(*gptr()). Otherwise, returns traits::eof(). Any character in the underlying buffer which has been initialized is considered to be part of the input sequence.

Effects: Puts back the character designated by c to the input sequence, if possible, in one of three ways:

• (2.1)

  If traits::eq_int_type(c,traits::eof()) returns false and if the input sequence has a putback position available, and if traits::eq(to_char_type(c),gptr()[-1]) returns true, assigns gptr() - 1 to gptr().

  Returns: c.

• (2.2)

  If traits::eq_int_type(c,traits::eof()) returns false and if the input sequence has a putback position available, and if mode & ios_base::out is nonzero, assigns c to *-- gptr().

  Returns: c.

• (2.3)

  If traits::eq_int_type(c,traits::eof()) returns true and if the input sequence has a putback position available, assigns gptr() - 1 to gptr().

  Returns: traits::not_eof(c).

Returns: traits::eof() to indicate failure.

Remarks: If the function can succeed in more than one of these ways, it is unspecified which way is chosen.

Effects: Appends the character designated by c to the output sequence, if possible, in one of two ways:

• (5.1)

  If traits::eq_int_type(c,traits::eof()) returns false and if either the output sequence has a write position available or the function makes a write position available (as described below), the function calls sputc(c ).

  Signals success by returning c.

• (5.2)

  If traits::eq_int_type(c,traits::eof()) returns true, there is no character to append.

  Signals success by returning a value other than traits::eof().

Remarks: The function can alter the number of write positions available as a result of any call.

Returns: traits::eof() to indicate failure.

The function can make a write position available only if (mode & ios_base::out) != 0. To make a write position available, the function reallocates (or initially allocates) an array object with a sufficient number of elements to hold the current array object (if any), plus at least one additional write position. If (mode & ios_base::in) != 0, the function alters the read end pointer egptr() to point just past the new write position.

Effects: Alters the stream position within one of the controlled sequences, if possible, as indicated in Table [tab:iostreams.seekoff.positioning].

For a sequence to be positioned, if its next pointer (either gptr() or pptr()) is a null pointer and the new offset newoff is nonzero, the positioning operation fails. Otherwise, the function determines newoff as indicated in Table [tab:iostreams.newoff.values].

If (newoff + off) < 0, or if newoff + off refers to an uninitialized character (as defined in [stringbuf.members] paragraph 1), the positioning operation fails. Otherwise, the function assigns xbeg + newoff + off to the next pointer xnext.

Returns: pos_type(newoff), constructed from the resultant offset newoff (of type off_type), that stores the resultant stream position, if possible. If the positioning operation fails, or if the constructed object cannot represent the resultant stream position, the return value is pos_type(off_type(-1)).

Effects: Equivalent to seekoff(off_type(sp), ios_base::beg, which).

Returns: sp to indicate success, or pos_type(off_type(-1)) to indicate failure.

Effects: implementation-defined, except that setbuf(0,0) has no effect.

Returns: this.

Effects: Constructs an object of class basic_istringstream<charT, traits>, initializing the base class with basic_istream(&sb) and initializing sb with basic_stringbuf<charT, traits, Allocator>(which | ios_base::in)) ([stringbuf.cons]).

Effects: Constructs an object of class basic_istringstream<charT, traits>, initializing the base class with basic_istream(&sb) and initializing sb with basic_stringbuf<charT, traits, Allocator>(str, which | ios_base::in)) ([stringbuf.cons]).