This header declares some classes and other types for performing I/O
with external files, as well as member functions for opening and
closing files and testing whether a file is open. Under this header,
class names are shown as they would appear in a typical object
declaration, and member functions are presented in "typical usage"
format.
In each of the three groupings immediately above, the first form
just declares a file stream object, while the other two both declare a
file stream object and open a physical file attached to that object.
However, if the first form is used to declare a file stream object,
then the actual file has to be opened later via a call to the open
function, which is what the two forms shown below provide.
- anyFileStream.open(c_string_value)
- Connect the file stream object anyFileStream with the
physical file whose name is in the C-string c_string_value,
open it in a default mode which will depend on the actual class type
of anyFileStream, and return the this pointer if successful
or a NULL pointer if unsuccessful
- anyFileStream.open(c_string_value, openmode_value)
- Connect the file stream object anyFileStream with the
physical file whose name is in the C-string c_string_value,
open it in a mode determined by openmode_value, and return
the this pointer if successful or a NULL pointer if
unsuccessful [See under <ios> for the definition of
the openmode type.]
- anyFileStream.is_open()
- Return true if the file stream object
anyFileStream is open, and otherwise false
- anyFileStream.close()
- Close the physical file associated with the file stream object
anyFileStream, and disconnect the two
<iomanip>
This header declares the I/O manipulators that take parameters. They
are presented in "typical usage" format.
The following three manipulators provide one mechanism for setting
(or "unsetting") the format-state flags. There are member functions
under <ios> that accomplish the same purpose.
- setbase(int_value)
- Set the base (or conversion radix) for a stream to
int_value, which must be one of the following values, since
any other value will be interpreted as 0: 10 (for decimal), 8 (for
octal), or 16 (for hex)
- setiosflags(fmtflags_value)
- Set the format-state flags specified explicitly in
fmtflags_value and leave the remaining flags unchanged
(equivalent to stream.setf(fmtflags_value) under
<ios>) [See <ios> as well for the
definition of the fmtflags type.]
- resetiosflags(fmtflags_value)
- Clear the format-state flags specified explicitly in
fmtflags_value and leave the remaining flags unchanged
(equivalent to stream.unsetf(fmtflags_value) under
<ios>) [See <ios> as well for the
definition of the fmtflags type.]
The next three manipulators provide one mechanism for setting the
format-state parameters. There are member functions under
<ios> that accomplish the same purpose.
- setfill(int_value)
- Set the "fill" format-state parameter that determines the "fill
character" when numerical values are output to the character whose
internal integer code is int_value
- setprecision(int_value)
- Set the "precision" format-state parameter to int_value
places for floating-point values
- setw(int_value)
- Set the "width" format-state parameter to int_value
<ios>
This header declares the classes, types, and manipulators that form
the foundation of the C++ I/O library. A class called ios_base
is the base class for all I/O stream classes, and a class template
called basic_ios derives from ios_base and declares
the behavior that is common to all I/O streams.
All manipulators and member functions in this subsection are
presented in "typical usage" format.
The types in the following list are referred to in various places
later under this header and elsewhere on this web page. When you
encounter such a reference (as the type of a function parameter, say),
you may want to look back here at one of these type definitions to
verify that a parameter of that type makes sense for that function (for
example).
This list gives only a high-level description of each
typedef, which is further constrained by the fact that each
actual type is implementation-defined. For further information, check
this site's page on
C++
Input/Output. The ellipsis (...) that appears in each list item is
the placeholder for the actual type name.
- fmtflags
- An implementation-defined integer, enumerated, or bitmask type
that represents formatting flags for I/O [Constant values of this
type are: boolalpha, dec, fixed,
hex, internal, left, oct,
right, scientific, showbase,
showpoint, showpos, skipws,
unitbuf, uppercase, adjustfield,
basefield, floatfield]
- iostate
- An implementation-defined integer, enumerated, or bitmask type
that represents the status (error state, if you like) of an I/O
stream [Constant values of this type are: badbit,
eofbit, failbit, goodbit =
iostate(0)]
- openmode
- An implementation-defined integer, enumerated, or bitmask type
that defines the mode for opening a file [Constant values of this
type are: app, ate, binary, in,
out, trunc]
- seekdir
- An implementation-defined enumerated type that specifies the
origin for seeking (moving the "read pointer" or "write pointer") to
a new file position [Constant values of this type are: beg,
cur, end]
- streamoff
- An implementation-defined type that represents a signed offset in
a stream [Values of type streammoff may be converted to
values of type streamsize without losing information.]
- streamsize
- An implementation-defined signed integral type used to represent
the size of various stream entities, such as the number of characters
to read or write in an I/O operation [Values of type
streamsize may be converted to values of type
streamoff without losing information.]
The following is a list of parameterless manipulators available from
this header.
- left
- Left-justify all output
- right
- Right-justify all output
- internal
- Left-justify sign or base indicator, and right-justify rest of
number
- dec
- Display integers in base 10 (decimal) format
- oct
- Display integers in base 8 (octal) format
- hex
- Display integers in base 16 (hexadecimal) format
- fixed
- Use fixed point notation when displaying floating-point numbers
(the usual convention)
- scientific
- Use exponential (i.e., scientific) notation when displaying
floating-point numbers
- showbase
noshowbase
- Show (or don't show) base indicator when displaying integer
output
- showpoint
noshowpoint
- Show (or don't show) decimal point when displaying floating-point
numbers (default is 6 significant digits)
- showpos
noshowpos
- Show (or don't show) a leading plus sign (+) when displaying
positive numbers
- uppercase
nouppercase
- Use (or don't use) uppercase E when displaying
exponential numbers, and uppercase letters when displaying
hexadecimal numbers
- boolalpha
noboolalpha
- Use (or don't use) textual rather than numerical format to read
and write boolean values (i.e., use, or don't use, true and
false rather than 1 and 0)
- skipws
noskipws
- Skip (or don't skip) whitespace on input
- unitbuf
nounitbuf
- Flush (or don't flush) output buffer after each insertion (which
really has nothing to do with formatting)
- stream.clear()
- Clear all stream error flags
- stream.good()
- Return true if no error has occurred (i.e., the next
three functions all return false)
- stream.eof()
- Return true if end-of-file has been encountered while
attempting an input operation
- stream.fail()
- Return true if an input or output operation failed
- stream.bad()
- Return true if input or output error was so severe that
recovery is unlikely
- stream.flags()
- Return a value of type fmtflags that contains the
current values of all format-state flags
- stream.flags(fmtflags_value)
- Return a value of type fmtflags that contains the
current values of all format-state flags, set all flags in
fmtflags_value, and clear all flags not mentioned in
fmtflags_value
- stream.setf(fmtflags_value)
- Set format-state flags specified in fmtflags_value,
leave all other format-state flags unchanged, and return a value of
type fmtflags that contains the previous state of all
flags
- stream.setf(fmtflags_value, fmtflags_group)
- Set format-state flags specified in fmtflags_value as the
new flags for the flag group identified by fmtflags_group,
leave all other format-state flags unchanged, and return a value of
type fmtflags that contains the previous state of all
flags
Typical uses of the two-parameter version of this function look
like this:
stream.setf(ios::left, ios::adjustfield)
stream.setf(0, ios::floatfield)
That last version clears all flags in the
ios::floatfield bit field.
- stream.unsetf(fmtflags_value)
- Clear format-state flags specified in fmtflags_value and
leave all other format-state flags unchanged
- stream.fill()
- Return current fill character format-state parameter value as a
value of type char
- stream.fill(char_value)
- Return current fill character format-state parameter value as a
value of type char, and set fill character format-state
parameter to new value in char_value
- stream.precision()
- Return current precision format-state parameter value as a value
of type streamsize
- stream.precision(streamsize_value)
- Return current precision format-state parameter value as a value
of type streamsize, and set precision format-state parameter
to new value in streamsize_value
- stream.width()
- Return current fieldwidth format-state parameter value as a value
of type streamsize
- stream.width(streamsize_value)
- Return current fieldwidth format-state parameter value as a value
of type streamsize, and set fieldwidth format-state
parameter to new value in streamsize_value
<iosfwd>
This header provides forward declarations of the various I/O-related
classes and templates, but can be ignored by most programmers most of
the time. In any case, this header is included by
<ios>.
<iostream>
This header declares the following four "standard stream objects".
They are all initialized and "set up for business" before the main
program begins, and are not destroyed during normal program execution,
so they can be used throughout the life of a program. You can tell from
the class of each object which member functions are available for use
with that object by checking the class type of the object and looking
under the header containing that class heading elsewhere in this
subsection of the current web page.
- extern istream cin
- The "standard input stream"
- extern ostream cout
- The "standard output stream"
- extern ostream cerr
- The "standard error stream"
- extern ostream clog
- The "standard log stream"
<istream>
This header declares the input stream classes and templates, and one
input manipulator. In addition to the member functions given below, the
extraction operator, operator>>, is of course overloaded
to permit reading primitive values into variables, as well as the
reading of characters into C-style string variables and C++ string
objects.
- istream inStream;
- Declare an istream object that can be used for reading
input
- iostream ioStream;
- Declare an istream object that can be used for reading
input and/or writing output
- ws
- A manipulator that causes whitespace characters to be
skipped
- inStream.peek()
- Return integer code of next character to be read without changing
stream position (i.e., without actually reading the character and
removing it from the stream), or return the integer code for
end-of-file if there is no such character
- inStream.ignore()
- Ignore the next character in the stream, if there is one, and
return *this
- inStream.ignore(positive_integer_value)
- Ignore positive_integer_value characters, or all
characters up to the end-of-file, whichever comes first, and return
*this
- inStream.ignore(positive_integer_value,
char_delimiter_value)
- Ignore positive_integer_value characters, or all
characters up to, and including, the character in
character_delimiter_value, whichever comes first, and return
*this [The most generally useful form of this function looks
something like this: inStream.ignore(80,
'\n'), which is often used to ignore everything on the
rest of a line of input.]
- inStream.get()
- Read and return the integer code of the next single character
from inStream, or return the integer code for end-of-file if
there are no more characters to be read
- inStream.get(char_variable)
- Read the next single character from inStream into
char_variable, and return *this
- inStream.putback(char_value)
- Try to put the character in char_value back into
inStream so that it will be the next character read from the
input stream, and return *this
- inStream.unget(char_value)
- Same as inStream.putback(char_value) (see immediately
above)
In the following list, note that the difference between
get() and getline() is simply that get()
leaves the delimiter in the input stream, while getline()
removes it. Also, a technical point that can cause some confusion if it
actually occurs, and should thus be noted, is this: In the case of
getline(), if the maximum number of characters to be read is
exactly the same as the number of characters available before the
delimiter, then the delimiter is not actually "encountered", and is
therefore left in the input stream on such an occasion. The +1
in the n+1 parameter value can be thought of as an allowance
for the extra space to accommodate the terminating null character
('\0') that the C-style string variable (into which the
characters are being read) must contain.
- inStream.get(c_string_variable, n+1)
- Read up to n characters (or up to the newline character,
whichever comes first) into c_string_variable
- inStream.get(c_string_variable, n+1, char_delimiter_value)
- Read up to n characters (or up to the first occurrence
of char_delimiter_value, whichever comes first) into
c_string_variable
- inStream.getline(c_string_variable, n+1)
- Read up to n characters (or up to the newline character,
whichever comes first) into c_string_variable
- inStream.getline(c_string_variable, n+1,
char_delimiter_value)
- Read up to n characters (or up to the first occurrence
of char_delimiter_value, whichever comes first) into
c_string_variable
- inStream.read(c_string_variable, streamsize_value)
- Read up to streamsize_value characters, place them in
c_string_variable, and return *this [Note that no
null character is appended to c_string_variable.]
- inStream.gcount()
- Return the number of characters returned from the stream by the
most recent call to an unformatted member function (get(),
getline(), ignore(), peek(),
putback(), read() or unget())
- inStream.tellg()
- Return current position in an input stream as a value of type
streamoff [The name tellg is short for "tell get",
i.e., "tell" the position at which you may "get" a value.]
- inStream.seekg(streamoff_value)
- Move the "read pointer" in an input stream to the explicit
position, or "offset" (measured by default from the beginning of the
stream) specified by streamoff_value [The name
seekg is short for "seek get", i.e., "seek a (new) position
at which you may "get" a value.]
- inStream.seekg(streamoff_value, seekdir_value)
- Move the "read pointer" in an input stream in a direction
determined by seekdir_value and a distance specified by
streamoff_value
<ostream>
This header declares the output stream class templates,
specializations and manipulators. See <fstream> for
derived classes that write to files, <sstream> for
derived classes that write to strings, and <ios> for
base-class declarations. In addition to the member functions given
below, the insertion operator, operator<<, is of course
overloaded to permit output of primitive values, as well as C-style
strings and C++ string objects.
- ostream outStream;
- Declare an ostream object that can be used for writing
output
- endl
- Insert newline and flush the output stream
- ends
- Insert a null character
- flush
- Flush an output stream
- outStream.flush()
- Flush the output buffer and return *this
- outStream.put(char_value)
- Write the character in char_value to the stream and
return *this
- outStream.write(c_string_value, streamsize_value)
- Write streamsize_value characters from
c_string_value to the output stream and return
*this
- outStream.tellp()
- Return current position in an output stream as a value of type
streamoff [The name tellp is short for "tell put",
i.e., "tell the position at which you may "put", or write, a
value.]
- outStream.seekp(streamoff_value)
- Move the "write pointer" in an output stream to the explicit
position, or "offset" (measured by default from the beginning of the
stream) specified by streamoff_value [The name
seekp is short for "seek put", i.e., "seek" a (new) position
at which you may "put", or write, a value.]
- outStream.seekp(streamoff_value, seekdir_value)
- Move the "write pointer" in an output stream in a direction
determined by seekdir_value and a distance specified by
streamoff_value
<sstream>
This header declares classes, templates and other types for reading
from and writing to string objects in memory in the same manner as
reading from and writing to files.
The following declarations parallel the analogous declarations for
file streams under <fstream>. In each case a string
buffer is created in memory, which can then be used for input and/or
output, as the case may be.
- istringstream inStringStream;
- Declare an istringstream object which is initially
empty, but which can be used for input (after something is placed in
it, of course)
- istringstream inStringStream(string_variable);
- Declare an istringstream object which has its buffer
initialized with the contents of string_variable and which
can be used for input
- ostringstream outStringStream;
- Declare an ostringstream object which is initially
empty, but which can be used for output
- ostringstream outStringStream(string_variable);
- Declare an ostringstream object which has its buffer
initialized with the contents of string_variable and which
can be used for output
- stringstream ioStringStream;
- Declare a stringstream object which is initially empty,
but which can be used for either input or output
- stringstream ioStringStream(string_variable);
- Declare a stringstream object which has its buffer
initialized with the contents of string_variable and which
can be used for either input or output
- anyStringStream.str()
- Return the contents of the string buffer associated with the
stream as a string value
- anyStringStream.str(string_variable)
- Deallocate the current buffer and replace it with the contents of
string_variable
<streambuf>
This header declares the basic_streambuf class template and
its streambuf specialization, which provides a stream buffer
object to manage low-level access to a sequence of characters. This
header is not normally needed in day-to-day programming.
<strstream>
This header declares classes, templates and other types for reading
from, and writing to, character arrays in memory, in the same manner as
reading from and writing to files. This header and its classes are
actually deprecated in the Standard, another hint that programmers
should really be using C++ string objects and the facilities from
<sstream> instead.