|
STLdoc
STLdocumentation
|
|
STLdoc
STLdocumentation
|
Functions | |
| namespace std | _GLIBCXX_VISIBILITY (default) |
Nearly all of the I/O classes are parameterized on the type of characters they read and write. (The major exception is ios_base at the top of the hierarchy.) This is a change from pre-Standard streams, which were not templates.
For ease of use and compatibility, all of the basic_* I/O-related classes are given typedef names for both of the builtin character widths (wide and narrow). The typedefs are the same as the pre-Standard names, for example:
Because properly forward-declaring these classes can be difficult, you should not do it yourself. Instead, include the <iosfwd> header, which contains only declarations of all the I/O classes as well as the typedefs. Trying to forward-declare the typedefs themselves (e.g., class ostream;) is not valid ISO C++.
For more specific declarations, see http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch24.html
| namespace std _GLIBCXX_VISIBILITY | ( | default | ) |
Template class basic_ios, virtual base class for all stream classes.
| _CharT | Type of character stream. |
| _Traits | Traits for character type, defaults to char_traits<_CharT>. |
Most of the member functions called dispatched on stream objects (e.g., std::cout.foo(bar);) are consolidated in this class.
These are standard types. They permit a standardized way of referring to names of (or names dependent on) the template parameters, which are specific to the implementation.
These are non-standard types.
The quick-and-easy status check.
This allows you to write constructs such as if (!a_stream) ... and while (a_stream) ...
Returns the error state of the stream buffer.
See std::ios_base::iostate for the possible bit values. Most users will call one of the interpreting wrappers, e.g., good().
[Re]sets the error state.
| __state | The new state flag(s) to set. |
See std::ios_base::iostate for the possible bit values. Most users will not need to pass an argument.
Sets additional flags in the error state.
| __state | The additional state flag(s) to set. |
See std::ios_base::iostate for the possible bit values.
Fast error checking.
A wrapper around rdstate.
Fast error checking.
Note that other iostate flags may also be set.
Fast error checking.
Checking the badbit in fail() is historical practice. Note that other iostate flags may also be set.
Fast error checking.
Note that other iostate flags may also be set.
Throwing exceptions on errors.
This changes nothing in the stream. See the one-argument version of exceptions(iostate) for the meaning of the return value.
Throwing exceptions on errors.
| __except | The new exceptions mask. |
By default, error flags are set silently. You can set an exceptions mask for each stream; if a bit in the mask becomes set in the error flags, then an exception of type std::ios_base::failure is thrown.
If the error flag is already set when the exceptions mask is added, the exception is immediately thrown. Try running the following under GCC 3.1 or later:
Constructor performs initialization.
The parameter is passed by derived streams.
Empty.
The destructor does nothing. More specifically, it does not destroy the streambuf held by rdbuf().
Fetches the current tied stream.
A stream may be tied (or synchronized) to a second output stream. When this stream performs any I/O, the tied stream is first flushed. For example, std::cin is tied to std::cout.
Ties this stream to an output stream.
| __tiestr | The output stream. |
This sets up a new tie; see tie() for more.
Accessing the underlying buffer.
This does not change the state of the stream.
Changing the underlying buffer.
| __sb | The new stream buffer. |
Associates a new buffer with the current stream, and clears the error state.
Due to historical accidents which the LWG refuses to correct, the I/O library suffers from a design error: this function is hidden in derived classes by overrides of the zero-argument rdbuf(), which is non-virtual for hysterical raisins. As a result, you must use explicit qualifications to access this function via any derived class. For example:
Copies fields of __rhs into this.
| __rhs | The source values for the copies. |
All fields of __rhs are copied into this object except that rdbuf() and rdstate() remain unchanged. All values in the pword and iword arrays are copied. Before copying, each callback is invoked with erase_event. After copying, each (new) callback is invoked with copyfmt_event. The final step is to copy exceptions().
Retrieves the empty character.
It defaults to a space (' ') in the current locale.
Sets a new empty character.
| __ch | The new character. |
The fill character is used to fill out space when P+ characters have been requested (e.g., via setw), Q characters are actually used, and Q<P. It defaults to a space (' ') in the current locale.
Moves to a new locale.
| __loc | The new locale. |
Calls ios_base::imbue(loc), and if a stream buffer is associated with this stream, calls that buffer's pubimbue(loc).
Additional l10n notes are at http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
Squeezes characters.
| __c | The character to narrow. |
| __dfault | The character to narrow. |
Maps a character of char_type to a character of char, if possible.
Returns the result of
Additional l10n notes are at http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
Widens characters.
| __c | The character to widen. |
Maps a character of char to a character of char_type.
Returns the result of
Additional l10n notes are at http://gcc.gnu.org/onlinedocs/libstdc++/manual/localization.html
Empty.
The default constructor does nothing and is not normally accessible to users.
All setup is performed here.
This is called from the public constructor. It is not virtual and cannot be redefined.
The base of the I/O class hierarchy.
This class defines everything that can be defined about I/O that does not depend on the type of characters being input or output. Most people will only see ios_base when they need to specify the full name of the various I/O flags (e.g., the openmodes).
These are thrown to indicate problems with io.
27.4.2.1.1 Class ios_base::failure
This is a bitmask type.
_Ios_Fmtflags is implementation-defined, but it is valid to perform bitwise operations on these values and expect the Right Thing to happen. Defined objects of type fmtflags are:
Insert/extract bool in alphabetic rather than numeric format.
Converts integer input or generates integer output in decimal base.
Generate floating-point output in fixed-point notation.
Converts integer input or generates integer output in hexadecimal base.
Adds fill characters at a designated internal point in certain generated output, or identical to right if no such point is designated.
Adds fill characters on the right (final positions) of certain generated output. (I.e., the thing you print is flush left.)
Converts integer input or generates integer output in octal base.
Adds fill characters on the left (initial positions) of certain generated output. (I.e., the thing you print is flush right.)
Generates floating-point output in scientific notation.
Generates a prefix indicating the numeric base of generated integer output.
Generates a decimal-point character unconditionally in generated floating-point output.
Generates a + sign in non-negative generated numeric output.
Skips leading white space before certain input operations.
Flushes output after each output operation.
Replaces certain lowercase letters with their uppercase equivalents in generated output.
A mask of left|right|internal. Useful for the 2-arg form of setf.
A mask of dec|oct|hex. Useful for the 2-arg form of setf.
A mask of scientific|fixed. Useful for the 2-arg form of setf.
This is a bitmask type.
_Ios_Iostate is implementation-defined, but it is valid to perform bitwise operations on these values and expect the Right Thing to happen. Defined objects of type iostate are:
Indicates a loss of integrity in an input or output sequence (such as an irrecoverable read error from a file).
Indicates that an input operation reached the end of an input sequence.
Indicates that an input operation failed to read the expected characters, or that an output operation failed to generate the desired characters.
Indicates all is well.
This is a bitmask type.
_Ios_Openmode is implementation-defined, but it is valid to perform bitwise operations on these values and expect the Right Thing to happen. Defined objects of type openmode are:
Seek to end before each write.
Open and seek to end immediately after opening.
Perform input and output in binary mode (as opposed to text mode). This is probably not what you think it is; see http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch27s02.html
Open for input. Default for ifstream and fstream.
Open for output. Default for ofstream and fstream.
Open for input. Default for ofstream.
This is an enumerated type.
_Ios_Seekdir is implementation-defined. Defined values of type seekdir are:
SEEK_CUR in the C standard library.SEEK_END in the C standard library.Request a seek relative to the beginning of the stream.
Request a seek relative to the current position within the sequence.
Request a seek relative to the current end of the sequence.
The set of events that may be passed to an event callback.
erase_event is used during ~ios() and copyfmt(). imbue_event is used during imbue(). copyfmt_event is used during copyfmt().
The type of an event callback function.
| __e | One of the members of the event enum. |
| __b | Reference to the ios_base object. |
| __i | The integer provided when the callback was registered. |
Event callbacks are user defined functions that get called during several ios_base and basic_ios functions, specifically imbue(), copyfmt(), and ~ios().
Add the callback __fn with parameter __index.
| __fn | The function to add. |
| __index | The integer to pass to the function when invoked. |
Registers a function as an event callback with an integer parameter to be passed to the function when invoked. Multiple copies of the function are allowed. If there are multiple callbacks, they are invoked in the order they were registered.
Access to format flags.
Setting new format flags all at once.
| __fmtfl | The new flags to set. |
This function overwrites all the format flags with __fmtfl.
Setting new format flags.
| __fmtfl | Additional flags to set. |
This function sets additional flags in format control. Flags that were previously set remain set.
Setting new format flags.
| __fmtfl | Additional flags to set. |
| __mask | The flags mask for fmtfl. |
This function clears mask in the format flags, then sets fmtfl & mask. An example mask is ios_base::adjustfield.
Clearing format flags.
| __mask | The flags to unset. |
This function clears __mask in the format flags.
Flags access.
Be careful if you try to give a definition of precision here; see DR 189.
Changing flags.
| __prec | The new precision value. |
Flags access.
Minimum field width refers to the number of characters.
Changing flags.
| __wide | The new width value. |
Interaction with the standard C I/O objects.
| __sync | Whether to synchronize or not. |
The synchronization referred to is only that between the standard C facilities (e.g., stdout) and the standard C++ objects (e.g., cout). User-declared streams are unaffected. See http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch28s02.html
Setting a new locale.
| __loc | The new locale. |
Sets the new locale for this stream, and then invokes each callback with imbue_event.
Locale access
If imbue(loc) has previously been called, then this function returns loc. Otherwise, it returns a copy of std::locale(), the global C++ locale.
Locale access
Like getloc above, but returns a reference instead of generating a copy.
Access to unique indices.
This function returns a unique integer every time it is called. It can be used for any purpose, but is primarily intended to be a unique index for the iword and pword functions. The expectation is that an application calls xalloc in order to obtain an index in the iword and pword arrays that can be used without fear of conflict.
The implementation maintains a static variable that is incremented and returned on each invocation. xalloc is guaranteed to return an index that is safe to use in the iword and pword arrays.
Access to integer array.
| __ix | Index into the array. |
The iword function provides access to an array of integers that can be used for any purpose. The array grows as required to hold the supplied index. All integers in the array are initialized to 0.
The implementation reserves several indices. You should use xalloc to obtain an index that is safe to use. Also note that since the array can grow dynamically, it is not safe to hold onto the reference.
Access to void pointer array.
| __ix | Index into the array. |
The pword function provides access to an array of pointers that can be used for any purpose. The array grows as required to hold the supplied index. All pointers in the array are initialized to 0.
The implementation reserves several indices. You should use xalloc to obtain an index that is safe to use. Also note that since the array can grow dynamically, it is not safe to hold onto the reference.
Invokes each callback with erase_event. Destroys local storage.
Note that the ios_base object for the standard streams never gets destroyed. As a result, any callbacks registered with the standard streams will not get invoked with erase_event (unless copyfmt is used).
Calls base.setf(ios_base::boolalpha).
Calls base.unsetf(ios_base::boolalpha).
Calls base.setf(ios_base::showbase).
Calls base.unsetf(ios_base::showbase).
Calls base.setf(ios_base::showpoint).
Calls base.unsetf(ios_base::showpoint).
Calls base.setf(ios_base::showpos).
Calls base.unsetf(ios_base::showpos).
Calls base.setf(ios_base::skipws).
Calls base.unsetf(ios_base::skipws).
Calls base.setf(ios_base::uppercase).
Calls base.unsetf(ios_base::uppercase).
Calls base.setf(ios_base::unitbuf).
Calls base.unsetf(ios_base::unitbuf).
Calls base.setf(ios_base::internal, ios_base::adjustfield).
Calls base.setf(ios_base::left, ios_base::adjustfield).
Calls base.setf(ios_base::right, ios_base::adjustfield).
Calls base.setf(ios_base::dec, ios_base::basefield).
Calls base.setf(ios_base::hex, ios_base::basefield).
Calls base.setf(ios_base::oct, ios_base::basefield).
Calls base.setf(ios_base::fixed, ios_base::floatfield).
Calls base.setf(ios_base::scientific, ios_base::floatfield).
Provides a layer of compatibility for C/POSIX.
This GNU extension provides extensions for working with standard C FILE*'s and POSIX file descriptors. It must be instantiated by the user with the type of character used in the file stream, e.g., stdio_filebuf<char>.
deferred initialization
| __fd | An open file descriptor. |
| __mode | Same meaning as in a standard filebuf. |
| __size | Optimal or preferred size of internal buffer, in chars. |
This constructor associates a file stream buffer with an open POSIX file descriptor. The file descriptor will be automatically closed when the stdio_filebuf is closed/destroyed.
| __f | An open FILE*. |
| __mode | Same meaning as in a standard filebuf. |
| __size | Optimal or preferred size of internal buffer, in chars. Defaults to system's BUFSIZ. |
This constructor associates a file stream buffer with an open C FILE*. The FILE* will not be automatically closed when the stdio_filebuf is closed/destroyed.
Closes the external data stream if the file descriptor constructor was used.
Once associated with an external data stream, this function can be used to access the underlying POSIX file descriptor. Note that there is no way for the library to track what you do with the descriptor, so be careful.
This function can be used to access the underlying "C" file pointer. Note that there is no way for the library to track what you do with the file, so be careful.
Provides a layer of compatibility for C.
This GNU extension provides extensions for working with standard C FILE*'s. It must be instantiated by the user with the type of character used in the file stream, e.g., stdio_filebuf<char>.
This function can be used to access the underlying C file pointer. Note that there is no way for the library to track what you do with the file, so be careful.
The actual work of input and output (for files).
| _CharT | Type of character stream. |
| _Traits | Traits for character type, defaults to char_traits<_CharT>. |
This class associates both its input and output sequence with an external disk file, and maintains a joint file position for both sequences. Many of its semantics are described in terms of similar behavior in the Standard C Library's FILE streams.
Requirements on traits_type, specific to this class:
Place to stash in || out || in | out settings for current filebuf.
Pointer to the beginning of internal buffer.
Actual size of internal buffer. This number is equal to the size of the put area + 1 position, reserved for the overflow char of a full area.
_M_reading == false && _M_writing == false for uncommitted mode; _M_reading == true for read mode; _M_writing == true for write mode;
NB: _M_reading == true && _M_writing == true is unused.
Necessary bits for putback buffer management.
Buffer for external characters. Used for input when codecvt::always_noconv() == false. When valid, this corresponds to eback().
Size of buffer held by _M_ext_buf.
Pointers into the buffer held by _M_ext_buf that delimit a subsequence of bytes that have been read but not yet converted. When valid, _M_ext_next corresponds to egptr().
Initializes pback buffers, and moves normal buffers to safety. Assumptions: _M_in_cur has already been moved back
Deactivates pback buffer contents, and restores normal buffer. Assumptions: The pback buffer has only moved forward.
Does not open any files.
The default constructor initializes the parent class using its own default ctor.
The destructor closes the file first.
Returns true if the external file is open.
Opens an external file.
| __s | The name of the file. |
| __mode | The open mode flags. |
this on success, NULL on failureIf a file is already open, this function immediately fails. Otherwise it tries to open the file named __s using the flags given in __mode.
Table 92, adapted here, gives the relation between openmode combinations and the equivalent fopen() flags. (NB: lines app, in|out|app, in|app, binary|app, binary|in|out|app, and binary|in|app per DR 596) +———————————————————+ | ios_base Flag combination stdio equivalent | |binary in out trunc app | +———————————————————+ | + w | | + + a | | + a | | + + w | | + r | | + + r+ | | + + + w+ | | + + + a+ | | + + a+ | +———————————————————+ | + + wb | | + + + ab | | + + ab | | + + + wb | | + + rb | | + + + r+b | | + + + + w+b | | + + + + a+b | | + + + a+b | +———————————————————+
Closes the currently associated file.
this on success, NULL on failureIf no file is currently open, this function immediately fails.
If a put buffer area exists, overflow(eof) is called to flush all the characters. The file is then closed.
If any operations fail, this function also fails.
Manipulates the buffer.
| __s | Pointer to a buffer area. |
| __n | Size of __s. |
this If no file has been opened, and both __s and __n are zero, then the stream becomes unbuffered. Otherwise, __s is used as a buffer; see http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch25s02.html for more.
This function sets the pointers of the internal buffer, both get and put areas. Typically:
__off == egptr() - eback() upon underflow/uflow (read mode); __off == 0 upon overflow (write mode); __off == -1 upon open, setbuf, seekoff/pos (uncommitted mode).
NB: epptr() - pbase() == _M_buf_size - 1, since _M_buf_size reflects the actual allocated memory and the last cell is reserved for the overflow char of a full put area.
Controlling input for files.
| _CharT | Type of character stream. |
| _Traits | Traits for character type, defaults to char_traits<_CharT>. |
This class supports reading from named files, using the inherited functions from std::basic_istream. To control the associated sequence, an instance of std::basic_filebuf is used, which this page refers to as sb.
Default constructor.
Initializes sb using its default constructor, and passes &sb to the base class initializer. Does not open any files (you haven't given it a filename to open).
Create an input file stream.
| __s | Null terminated string specifying the filename. |
| __mode | Open file in specified mode (see std::ios_base). |
ios_base::in is automatically included in __mode.
Tip: When using std::string to hold the filename, you must use .c_str() before passing it to this constructor.
The destructor does nothing.
The file is closed by the filebuf object, not the formatting stream.
Accessing the underlying buffer.
This hides both signatures of std::basic_ios::rdbuf().
Wrapper to test for an open file.
rdbuf()->is_open() Opens an external file.
| __s | The name of the file. |
| __mode | The open mode flags. |
Calls std::basic_filebuf::open(s,__mode|in). If that function fails, failbit is set in the stream's error state.
Tip: When using std::string to hold the filename, you must use .c_str() before passing it to this constructor.
Close the file.
Calls std::basic_filebuf::close(). If that function fails, failbit is set in the stream's error state.
Controlling output for files.
| _CharT | Type of character stream. |
| _Traits | Traits for character type, defaults to char_traits<_CharT>. |
This class supports reading from named files, using the inherited functions from std::basic_ostream. To control the associated sequence, an instance of std::basic_filebuf is used, which this page refers to as sb.
Default constructor.
Initializes sb using its default constructor, and passes &sb to the base class initializer. Does not open any files (you haven't given it a filename to open).
Create an output file stream.
| __s | Null terminated string specifying the filename. |
| __mode | Open file in specified mode (see std::ios_base). |
ios_base::out | ios_base::trunc is automatically included in __mode.
Tip: When using std::string to hold the filename, you must use .c_str() before passing it to this constructor.
The destructor does nothing.
The file is closed by the filebuf object, not the formatting stream.
Accessing the underlying buffer.
This hides both signatures of std::basic_ios::rdbuf().
Wrapper to test for an open file.
rdbuf()->is_open() Opens an external file.
| __s | The name of the file. |
| __mode | The open mode flags. |
Calls std::basic_filebuf::open(__s,__mode|out|trunc). If that function fails, failbit is set in the stream's error state.
Tip: When using std::string to hold the filename, you must use .c_str() before passing it to this constructor.
Close the file.
Calls std::basic_filebuf::close(). If that function fails, failbit is set in the stream's error state.
Controlling input and output for files.
| _CharT | Type of character stream. |
| _Traits | Traits for character type, defaults to char_traits<_CharT>. |
This class supports reading from and writing to named files, using the inherited functions from std::basic_iostream. To control the associated sequence, an instance of std::basic_filebuf is used, which this page refers to as sb.
Default constructor.
Initializes sb using its default constructor, and passes &sb to the base class initializer. Does not open any files (you haven't given it a filename to open).
Create an input/output file stream.
| __s | Null terminated string specifying the filename. |
| __mode | Open file in specified mode (see std::ios_base). |
Tip: When using std::string to hold the filename, you must use .c_str() before passing it to this constructor.
The destructor does nothing.
The file is closed by the filebuf object, not the formatting stream.
Accessing the underlying buffer.
This hides both signatures of std::basic_ios::rdbuf().
Wrapper to test for an open file.
rdbuf()->is_open() Opens an external file.
| __s | The name of the file. |
| __mode | The open mode flags. |
Calls std::basic_filebuf::open(__s,__mode). If that function fails, failbit is set in the stream's error state.
Tip: When using std::string to hold the filename, you must use .c_str() before passing it to this constructor.
Close the file.
Calls std::basic_filebuf::close(). If that function fails, failbit is set in the stream's error state.
The actual work of input and output (for std::string).
| _CharT | Type of character stream. |
| _Traits | Traits for character type, defaults to char_traits<_CharT>. |
| _Alloc | Allocator type, defaults to allocator<_CharT>. |
This class associates either or both of its input and output sequences with a sequence of characters, which can be initialized from, or made available as, a std::basic_string. (Paraphrased from [27.7.1]/1.)
For this class, open modes (of type ios_base::openmode) have in set if the input sequence can be read, and out set if the output sequence can be written.
Place to stash in || out || in | out settings for current stringbuf.
Starts with an empty string buffer.
| __mode | Whether the buffer can read, or write, or both. |
The default constructor initializes the parent class using its own default ctor.
Starts with an existing string buffer.
| __str | A string to copy as a starting buffer. |
| __mode | Whether the buffer can read, or write, or both. |
This constructor initializes the parent class using its own default ctor.
Copying out the string buffer.
If the buffer is only created in input mode, the underlying character sequence is equal to the input sequence; otherwise, it is equal to the output sequence. [27.7.1.2]/1
Setting a new buffer.
| __s | The string to use as a new sequence. |
Deallocates any previous stored sequence, then copies s to use as a new one.
Manipulates the buffer.
| __s | Pointer to a buffer area. |
| __n | Size of __s. |
this If no buffer has already been created, and both __s and __n are non-zero, then __s is used as a buffer; see http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch25s02.html for more.
Controlling input for std::string.
| _CharT | Type of character stream. |
| _Traits | Traits for character type, defaults to char_traits<_CharT>. |
| _Alloc | Allocator type, defaults to allocator<_CharT>. |
This class supports reading from objects of type std::basic_string, using the inherited functions from std::basic_istream. To control the associated sequence, an instance of std::basic_stringbuf is used, which this page refers to as sb.
Default constructor starts with an empty string buffer.
| __mode | Whether the buffer can read, or write, or both. |
ios_base::in is automatically included in __mode.
Initializes sb using __mode|in, and passes &sb to the base class initializer. Does not allocate any buffer.
That's a lie. We initialize the base class with NULL, because the string class does its own memory management.
Starts with an existing string buffer.
| __str | A string to copy as a starting buffer. |
| __mode | Whether the buffer can read, or write, or both. |
ios_base::in is automatically included in mode.
Initializes sb using str and mode|in, and passes &sb to the base class initializer.
That's a lie. We initialize the base class with NULL, because the string class does its own memory management.
The destructor does nothing.
The buffer is deallocated by the stringbuf object, not the formatting stream.
Accessing the underlying buffer.
This hides both signatures of std::basic_ios::rdbuf().
Copying out the string buffer.
rdbuf()->str() Setting a new buffer.
| __s | The string to use as a new sequence. |
Calls rdbuf()->str(s).
Controlling output for std::string.
| _CharT | Type of character stream. |
| _Traits | Traits for character type, defaults to char_traits<_CharT>. |
| _Alloc | Allocator type, defaults to allocator<_CharT>. |
This class supports writing to objects of type std::basic_string, using the inherited functions from std::basic_ostream. To control the associated sequence, an instance of std::basic_stringbuf is used, which this page refers to as sb.
Default constructor starts with an empty string buffer.
| __mode | Whether the buffer can read, or write, or both. |
ios_base::out is automatically included in mode.
Initializes sb using mode|out, and passes &sb to the base class initializer. Does not allocate any buffer.
That's a lie. We initialize the base class with NULL, because the string class does its own memory management.
Starts with an existing string buffer.
| __str | A string to copy as a starting buffer. |
| __mode | Whether the buffer can read, or write, or both. |
ios_base::out is automatically included in mode.
Initializes sb using str and mode|out, and passes &sb to the base class initializer.
That's a lie. We initialize the base class with NULL, because the string class does its own memory management.
The destructor does nothing.
The buffer is deallocated by the stringbuf object, not the formatting stream.
Accessing the underlying buffer.
This hides both signatures of std::basic_ios::rdbuf().
Copying out the string buffer.
rdbuf()->str() Setting a new buffer.
| __s | The string to use as a new sequence. |
Calls rdbuf()->str(s).
Controlling input and output for std::string.
| _CharT | Type of character stream. |
| _Traits | Traits for character type, defaults to char_traits<_CharT>. |
| _Alloc | Allocator type, defaults to allocator<_CharT>. |
This class supports reading from and writing to objects of type std::basic_string, using the inherited functions from std::basic_iostream. To control the associated sequence, an instance of std::basic_stringbuf is used, which this page refers to as sb.
Default constructor starts with an empty string buffer.
| __m | Whether the buffer can read, or write, or both. |
Initializes sb using the mode from __m, and passes &sb to the base class initializer. Does not allocate any buffer.
That's a lie. We initialize the base class with NULL, because the string class does its own memory management.
Starts with an existing string buffer.
| __str | A string to copy as a starting buffer. |
| __m | Whether the buffer can read, or write, or both. |
Initializes sb using __str and __m, and passes &sb to the base class initializer.
That's a lie. We initialize the base class with NULL, because the string class does its own memory management.
The destructor does nothing.
The buffer is deallocated by the stringbuf object, not the formatting stream.
Accessing the underlying buffer.
This hides both signatures of std::basic_ios::rdbuf().
Copying out the string buffer.
rdbuf()->str() Setting a new buffer.
| __s | The string to use as a new sequence. |
Calls rdbuf()->str(s).
The actual work of input and output (interface).
| _CharT | Type of character stream. |
| _Traits | Traits for character type, defaults to char_traits<_CharT>. |
This is a base class. Derived stream buffers each control a pair of character sequences: one for input, and one for output.
Section [27.5.1] of the standard describes the requirements and behavior of stream buffer classes. That section (three paragraphs) is reproduced here, for simplicity and accuracy.
charT array object. The array object represents, 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:charT array, as described above; otherwise, xbeg and xend shall also be null.These are standard types. They permit a standardized way of referring to names of (or names dependent on) the template parameters, which are specific to the implementation.
This is a non-standard type.
< Start of get area.
< Current read area.
< End of get area.
< Start of put area.
< Current put area.
< End of put area.
Current locale setting.
Destructor deallocates no buffer space.
Entry point for imbue().
| __loc | The new locale. |
Calls the derived imbue(__loc).
Locale access.
If pubimbue(loc) has been called, then the most recent loc is returned. Otherwise the global locale in effect at the time of construction is returned.
Entry points for derived buffer functions.
The public versions of pubfoo dispatch to the protected derived foo member functions, passing the arguments (if any) and returning the result unchanged.
Alters the stream position.
| __off | Offset. |
| __way | Value for ios_base::seekdir. |
| __mode | Value for ios_base::openmode. |
Calls virtual seekoff function.
Alters the stream position.
| __sp | Position |
| __mode | Value for ios_base::openmode. |
Calls virtual seekpos function.
Calls virtual sync function.
Looking ahead into the stream.
If a read position is available, returns the number of characters available for reading before the buffer must be refilled. Otherwise returns the derived showmanyc().
Getting the next character.
Calls sbumpc(), and if that function returns traits::eof(), so does this function. Otherwise, sgetc().
Getting the next character.
If the input read position is available, returns that character and increments the read pointer, otherwise calls and returns uflow().
Getting the next character.
If the input read position is available, returns that character, otherwise calls and returns underflow(). Does not move the read position after fetching the character.
Entry point for xsgetn.
| __s | A buffer area. |
| __n | A count. |
Returns xsgetn(__s,__n). The effect is to fill __s[0] through __s[__n-1] with characters from the input sequence, if possible.
Pushing characters back into the input stream.
| __c | The character to push back. |
Similar to sungetc(), but __c is pushed onto the stream instead of the previous character. If successful, the next character fetched from the input stream will be __c.
Moving backwards in the input stream.
If a putback position is available, this function decrements the input pointer and returns that character. Otherwise, calls and returns pbackfail(). The effect is to unget the last character gotten.
Entry point for all single-character output functions.
| __c | A character to output. |
One of two public output functions.
If a write position is available for the output sequence (i.e., the buffer is not full), stores __c in that position, increments the position, and returns traits::to_int_type(__c). If a write position is not available, returns overflow(__c).
Entry point for all single-character output functions.
| __s | A buffer read area. |
| __n | A count. |
One of two public output functions.
Returns xsputn(__s,__n). The effect is to write __s[0] through __s[__n-1] to the output sequence, if possible.
Base constructor.
Only called from derived constructors, and sets up all the buffer data to zero, including the pointers described in the basic_streambuf class description. Note that, as a result,
Access to the get area.
These functions are only available to other protected functions, including derived classes.
Moving the read position.
| __n | The delta by which to move. |
This just advances the read position without returning any data.
Setting the three read area pointers.
| __gbeg | A pointer. |
| __gnext | A pointer. |
| __gend | A pointer. |
eback(), __gnext == gptr(), and __gend == egptr() Access to the put area.
These functions are only available to other protected functions, including derived classes.
Moving the write position.
| __n | The delta by which to move. |
This just advances the write position without returning any data.
Setting the three write area pointers.
| __pbeg | A pointer. |
| __pend | A pointer. |
pbase(), __pbeg == pptr(), and __pend == epptr() Changes translations.
| __loc | A new locale. |
Translations done during I/O which depend on the current locale are changed by this call. The standard adds, Between invocations of this function a class derived from streambuf can safely cache results of calls to locale functions and to members of facets so obtained.
Manipulates the buffer.
Each derived class provides its own appropriate behavior. See the next-to-last paragraph of http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch25s02.html for more on this function.
this.Alters the stream positions.
Each derived class provides its own appropriate behavior.
pos_type that represents an invalid stream position.Alters the stream positions.
Each derived class provides its own appropriate behavior.
pos_type that represents an invalid stream position.Synchronizes the buffer arrays with the controlled sequences.
Each derived class provides its own appropriate behavior, including the definition of failure.
Investigating the data available.
If it returns a positive value, then successive calls to underflow() will not return traits::eof() until at least that number of characters have been supplied. If showmanyc() returns -1, then calls to underflow() or uflow() will fail. [27.5.2.4.3]/1
eof() but that they will return immediately. showmanyc are es-how-many-see, not show-manic.Multiple character extraction.
| __s | A buffer area. |
| __n | Maximum number of characters to assign. |
Fills __s[0] through __s[__n-1] with characters from the input sequence, as if by sbumpc(). Stops when either __n characters have been copied, or when traits::eof() would be copied.
It is expected that derived classes provide a more efficient implementation by overriding this definition.
Fetches more data from the controlled sequence.
Informally, this function is called when the input buffer is exhausted (or does not exist, as buffering need not actually be done). If a buffer exists, it is refilled. In either case, the next available character is returned, or traits::eof() to indicate a null pending sequence.
For a formal definition of the pending sequence, see a good text such as Langer & Kreft, or [27.5.2.4.3]/7-14.
A functioning input streambuf can be created by overriding only this function (no buffer area will be used). For an example, see http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch25.html
Fetches more data from the controlled sequence.
Informally, this function does the same thing as underflow(), and in fact is required to call that function. It also returns the new character, like underflow() does. However, this function also moves the read position forward by one.
Tries to back up the input sequence.
| __c | The character to be inserted back into the sequence. |
gptr(), eback(), and pptr() are the same as for underflow().Multiple character insertion.
| __s | A buffer area. |
| __n | Maximum number of characters to write. |
Writes __s[0] through __s[__n-1] to the output sequence, as if by sputc(). Stops when either n characters have been copied, or when sputc() would return traits::eof().
It is expected that derived classes provide a more efficient implementation by overriding this definition.
Consumes data from the buffer; writes to the controlled sequence.
| __c | An additional character to consume. |
Informally, this function is called when the output buffer is full (or does not exist, as buffering need not actually be done). If a buffer exists, it is consumed, with some effect on the controlled sequence. (Typically, the buffer is written out to the sequence verbatim.) In either case, the character c is also written out, if __c is not eof().
For a formal definition of this function, see a good text such as Langer & Kreft, or [27.5.2.4.5]/3-7.
A functioning output streambuf can be created by overriding only this function (no buffer area will be used).
1.8.6