|
|
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
|
[ ]>
|
[ ]>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ISO C++
|
ISO C++
|
|
|
|
|
library
|
library
|
|
|
|
|
|
|
|
|
|
|
Input and Output
|
Input and Output
|
Input and Output
|
Input and Output
|
|
|
|
|
|
|
|
|
|
|
Iostream Objects
|
Iostream Objects
|
|
|
To minimize the time you have to wait on the compiler, it's good to
|
To minimize the time you have to wait on the compiler, it's good to
|
only include the headers you really need. Many people simply include
|
only include the headers you really need. Many people simply include
|
<iostream> when they don't need to -- and that can penalize
|
<iostream> when they don't need to -- and that can penalize
|
your runtime as well. Here are some tips on which header to use
|
your runtime as well. Here are some tips on which header to use
|
for which situations, starting with the simplest.
|
for which situations, starting with the simplest.
|
|
|
<iosfwd> should be included whenever you simply
|
<iosfwd> should be included whenever you simply
|
need the name of an I/O-related class, such as
|
need the name of an I/O-related class, such as
|
"ofstream" or "basic_streambuf". Like the name
|
"ofstream" or "basic_streambuf". Like the name
|
implies, these are forward declarations. (A word to all you fellow
|
implies, these are forward declarations. (A word to all you fellow
|
old school programmers: trying to forward declare classes like
|
old school programmers: trying to forward declare classes like
|
"class istream;" won't work. Look in the iosfwd header if
|
"class istream;" won't work. Look in the iosfwd header if
|
you'd like to know why.) For example,
|
you'd like to know why.) For example,
|
|
|
|
|
#include <iosfwd>
|
#include <iosfwd>
|
|
|
class MyClass
|
class MyClass
|
{
|
{
|
....
|
....
|
std::ifstream& input_file;
|
std::ifstream& input_file;
|
};
|
};
|
|
|
extern std::ostream& operator<< (std::ostream&, MyClass&);
|
extern std::ostream& operator<< (std::ostream&, MyClass&);
|
|
|
<ios> declares the base classes for the entire
|
<ios> declares the base classes for the entire
|
I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the
|
I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the
|
counting types std::streamoff and std::streamsize, the file
|
counting types std::streamoff and std::streamsize, the file
|
positioning type std::fpos, and the various manipulators like
|
positioning type std::fpos, and the various manipulators like
|
std::hex, std::fixed, std::noshowbase, and so forth.
|
std::hex, std::fixed, std::noshowbase, and so forth.
|
|
|
The ios_base class is what holds the format flags, the state flags,
|
The ios_base class is what holds the format flags, the state flags,
|
and the functions which change them (setf(), width(), precision(),
|
and the functions which change them (setf(), width(), precision(),
|
etc). You can also store extra data and register callback functions
|
etc). You can also store extra data and register callback functions
|
through ios_base, but that has been historically underused. Anything
|
through ios_base, but that has been historically underused. Anything
|
which doesn't depend on the type of characters stored is consolidated
|
which doesn't depend on the type of characters stored is consolidated
|
here.
|
here.
|
|
|
The template class basic_ios is the highest template class in the
|
The template class basic_ios is the highest template class in the
|
hierarchy; it is the first one depending on the character type, and
|
hierarchy; it is the first one depending on the character type, and
|
holds all general state associated with that type: the pointer to the
|
holds all general state associated with that type: the pointer to the
|
polymorphic stream buffer, the facet information, etc.
|
polymorphic stream buffer, the facet information, etc.
|
|
|
<streambuf> declares the template class
|
<streambuf> declares the template class
|
basic_streambuf, and two standard instantiations, streambuf and
|
basic_streambuf, and two standard instantiations, streambuf and
|
wstreambuf. If you need to work with the vastly useful and capable
|
wstreambuf. If you need to work with the vastly useful and capable
|
stream buffer classes, e.g., to create a new form of storage
|
stream buffer classes, e.g., to create a new form of storage
|
transport, this header is the one to include.
|
transport, this header is the one to include.
|
|
|
<istream>/<ostream> are
|
<istream>/<ostream> are
|
the headers to include when you are using the >>/<<
|
the headers to include when you are using the >>/<<
|
interface, or any of the other abstract stream formatting functions.
|
interface, or any of the other abstract stream formatting functions.
|
For example,
|
For example,
|
|
|
|
|
#include <istream>
|
#include <istream>
|
|
|
std::ostream& operator<< (std::ostream& os, MyClass& c)
|
std::ostream& operator<< (std::ostream& os, MyClass& c)
|
{
|
{
|
return os << c.data1() << c.data2();
|
return os << c.data1() << c.data2();
|
}
|
}
|
|
|
The std::istream and std::ostream classes are the abstract parents of
|
The std::istream and std::ostream classes are the abstract parents of
|
the various concrete implementations. If you are only using the
|
the various concrete implementations. If you are only using the
|
interfaces, then you only need to use the appropriate interface header.
|
interfaces, then you only need to use the appropriate interface header.
|
|
|
<iomanip> provides "extractors and inserters
|
<iomanip> provides "extractors and inserters
|
that alter information maintained by class ios_base and its derived
|
that alter information maintained by class ios_base and its derived
|
classes," such as std::setprecision and std::setw. If you need
|
classes," such as std::setprecision and std::setw. If you need
|
to write expressions like os << setw(3); or
|
to write expressions like os << setw(3); or
|
is >> setbase(8); , you must include <iomanip>.
|
is >> setbase(8); , you must include <iomanip>.
|
|
|
<sstream>/<fstream>
|
<sstream>/<fstream>
|
declare the six stringstream and fstream classes. As they are the
|
declare the six stringstream and fstream classes. As they are the
|
standard concrete descendants of istream and ostream, you will already
|
standard concrete descendants of istream and ostream, you will already
|
know about them.
|
know about them.
|
|
|
Finally, <iostream> provides the eight standard
|
Finally, <iostream> provides the eight standard
|
global objects (cin, cout, etc). To do this correctly, this header
|
global objects (cin, cout, etc). To do this correctly, this header
|
also provides the contents of the <istream> and <ostream>
|
also provides the contents of the <istream> and <ostream>
|
headers, but nothing else. The contents of this header look like
|
headers, but nothing else. The contents of this header look like
|
|
|
|
|
#include <ostream>
|
#include <ostream>
|
#include <istream>
|
#include <istream>
|
|
|
namespace std
|
namespace std
|
{
|
{
|
extern istream cin;
|
extern istream cin;
|
extern ostream cout;
|
extern ostream cout;
|
....
|
....
|
|
|
// this is explained below
|
// this is explained below
|
static ios_base::Init __foo; // not its real name
|
static ios_base::Init __foo; // not its real name
|
}
|
}
|
|
|
Now, the runtime penalty mentioned previously: the global objects
|
Now, the runtime penalty mentioned previously: the global objects
|
must be initialized before any of your own code uses them; this is
|
must be initialized before any of your own code uses them; this is
|
guaranteed by the standard. Like any other global object, they must
|
guaranteed by the standard. Like any other global object, they must
|
be initialized once and only once. This is typically done with a
|
be initialized once and only once. This is typically done with a
|
construct like the one above, and the nested class ios_base::Init is
|
construct like the one above, and the nested class ios_base::Init is
|
specified in the standard for just this reason.
|
specified in the standard for just this reason.
|
|
|
How does it work? Because the header is included before any of your
|
How does it work? Because the header is included before any of your
|
code, the __foo object is constructed before any of
|
code, the __foo object is constructed before any of
|
your objects. (Global objects are built in the order in which they
|
your objects. (Global objects are built in the order in which they
|
are declared, and destroyed in reverse order.) The first time the
|
are declared, and destroyed in reverse order.) The first time the
|
constructor runs, the eight stream objects are set up.
|
constructor runs, the eight stream objects are set up.
|
|
|
The static keyword means that each object file compiled
|
The static keyword means that each object file compiled
|
from a source file containing <iostream> will have its own
|
from a source file containing <iostream> will have its own
|
private copy of __foo. There is no specified order
|
private copy of __foo. There is no specified order
|
of construction across object files (it's one of those pesky NP
|
of construction across object files (it's one of those pesky NP
|
problems that make life so interesting), so one copy in each object
|
problems that make life so interesting), so one copy in each object
|
file means that the stream objects are guaranteed to be set up before
|
file means that the stream objects are guaranteed to be set up before
|
any of your code which uses them could run, thereby meeting the
|
any of your code which uses them could run, thereby meeting the
|
requirements of the standard.
|
requirements of the standard.
|
|
|
The penalty, of course, is that after the first copy of
|
The penalty, of course, is that after the first copy of
|
__foo is constructed, all the others are just wasted
|
__foo is constructed, all the others are just wasted
|
processor time. The time spent is merely for an increment-and-test
|
processor time. The time spent is merely for an increment-and-test
|
inside a function call, but over several dozen or hundreds of object
|
inside a function call, but over several dozen or hundreds of object
|
files, that time can add up. (It's not in a tight loop, either.)
|
files, that time can add up. (It's not in a tight loop, either.)
|
|
|
The lesson? Only include <iostream> when you need to use one of
|
The lesson? Only include <iostream> when you need to use one of
|
the standard objects in that source file; you'll pay less startup
|
the standard objects in that source file; you'll pay less startup
|
time. Only include the header files you need to in general; your
|
time. Only include the header files you need to in general; your
|
compile times will go down when there's less parsing work to do.
|
compile times will go down when there's less parsing work to do.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Stream Buffers
|
Stream Buffers
|
|
|
|
|
Derived streambuf Classes
|
Derived streambuf Classes
|
|
|
|
|
|
|
Creating your own stream buffers for I/O can be remarkably easy.
|
Creating your own stream buffers for I/O can be remarkably easy.
|
If you are interested in doing so, we highly recommend two very
|
If you are interested in doing so, we highly recommend two very
|
excellent books:
|
excellent books:
|
Standard C++
|
Standard C++
|
IOStreams and Locales by Langer and Kreft, ISBN 0-201-18395-1, and
|
IOStreams and Locales by Langer and Kreft, ISBN 0-201-18395-1, and
|
The C++ Standard Library
|
The C++ Standard Library
|
by Nicolai Josuttis, ISBN 0-201-37926-0. Both are published by
|
by Nicolai Josuttis, ISBN 0-201-37926-0. Both are published by
|
Addison-Wesley, who isn't paying us a cent for saying that, honest.
|
Addison-Wesley, who isn't paying us a cent for saying that, honest.
|
|
|
Here is a simple example, io/outbuf1, from the Josuttis text. It
|
Here is a simple example, io/outbuf1, from the Josuttis text. It
|
transforms everything sent through it to uppercase. This version
|
transforms everything sent through it to uppercase. This version
|
assumes many things about the nature of the character type being
|
assumes many things about the nature of the character type being
|
used (for more information, read the books or the newsgroups):
|
used (for more information, read the books or the newsgroups):
|
|
|
|
|
#include <iostream>
|
#include <iostream>
|
#include <streambuf>
|
#include <streambuf>
|
#include <locale>
|
#include <locale>
|
#include <cstdio>
|
#include <cstdio>
|
|
|
class outbuf : public std::streambuf
|
class outbuf : public std::streambuf
|
{
|
{
|
protected:
|
protected:
|
/* central output function
|
/* central output function
|
* - print characters in uppercase mode
|
* - print characters in uppercase mode
|
*/
|
*/
|
virtual int_type overflow (int_type c) {
|
virtual int_type overflow (int_type c) {
|
if (c != EOF) {
|
if (c != EOF) {
|
// convert lowercase to uppercase
|
// convert lowercase to uppercase
|
c = std::toupper(static_cast<char>(c),getloc());
|
c = std::toupper(static_cast<char>(c),getloc());
|
|
|
// and write the character to the standard output
|
// and write the character to the standard output
|
if (putchar(c) == EOF) {
|
if (putchar(c) == EOF) {
|
return EOF;
|
return EOF;
|
}
|
}
|
}
|
}
|
return c;
|
return c;
|
}
|
}
|
};
|
};
|
|
|
int main()
|
int main()
|
{
|
{
|
// create special output buffer
|
// create special output buffer
|
outbuf ob;
|
outbuf ob;
|
// initialize output stream with that output buffer
|
// initialize output stream with that output buffer
|
std::ostream out(&ob);
|
std::ostream out(&ob);
|
|
|
out << "31 hexadecimal: "
|
out << "31 hexadecimal: "
|
<< std::hex << 31 << std::endl;
|
<< std::hex << 31 << std::endl;
|
return 0;
|
return 0;
|
}
|
}
|
|
|
Try it yourself! More examples can be found in 3.1.x code, in
|
Try it yourself! More examples can be found in 3.1.x code, in
|
include/ext/*_filebuf.h , and in this article by James Kanze:
|
include/ext/*_filebuf.h , and in this article by James Kanze:
|
Filtering
|
Filtering
|
Streambufs.
|
Streambufs.
|
|
|
|
|
|
|
|
|
|
|
Buffering
|
Buffering
|
First, are you sure that you understand buffering? Chaptericularly
|
First, are you sure that you understand buffering? Chaptericularly
|
the fact that C++ may not, in fact, have anything to do with it?
|
the fact that C++ may not, in fact, have anything to do with it?
|
|
|
The rules for buffering can be a little odd, but they aren't any
|
The rules for buffering can be a little odd, but they aren't any
|
different from those of C. (Maybe that's why they can be a bit
|
different from those of C. (Maybe that's why they can be a bit
|
odd.) Many people think that writing a newline to an output
|
odd.) Many people think that writing a newline to an output
|
stream automatically flushes the output buffer. This is true only
|
stream automatically flushes the output buffer. This is true only
|
when the output stream is, in fact, a terminal and not a file
|
when the output stream is, in fact, a terminal and not a file
|
or some other device -- and that may not even be true
|
or some other device -- and that may not even be true
|
since C++ says nothing about files nor terminals. All of that is
|
since C++ says nothing about files nor terminals. All of that is
|
system-dependent. (The "newline-buffer-flushing only occurring
|
system-dependent. (The "newline-buffer-flushing only occurring
|
on terminals" thing is mostly true on Unix systems, though.)
|
on terminals" thing is mostly true on Unix systems, though.)
|
|
|
Some people also believe that sending endl down an
|
Some people also believe that sending endl down an
|
output stream only writes a newline. This is incorrect; after a
|
output stream only writes a newline. This is incorrect; after a
|
newline is written, the buffer is also flushed. Perhaps this
|
newline is written, the buffer is also flushed. Perhaps this
|
is the effect you want when writing to a screen -- get the text
|
is the effect you want when writing to a screen -- get the text
|
out as soon as possible, etc -- but the buffering is largely
|
out as soon as possible, etc -- but the buffering is largely
|
wasted when doing this to a file:
|
wasted when doing this to a file:
|
|
|
|
|
output << "a line of text" << endl;
|
output << "a line of text" << endl;
|
output << some_data_variable << endl;
|
output << some_data_variable << endl;
|
output << "another line of text" << endl;
|
output << "another line of text" << endl;
|
The proper thing to do in this case to just write the data out
|
The proper thing to do in this case to just write the data out
|
and let the libraries and the system worry about the buffering.
|
and let the libraries and the system worry about the buffering.
|
If you need a newline, just write a newline:
|
If you need a newline, just write a newline:
|
|
|
|
|
output << "a line of text\n"
|
output << "a line of text\n"
|
<< some_data_variable << '\n'
|
<< some_data_variable << '\n'
|
<< "another line of text\n";
|
<< "another line of text\n";
|
I have also joined the output statements into a single statement.
|
I have also joined the output statements into a single statement.
|
You could make the code prettier by moving the single newline to
|
You could make the code prettier by moving the single newline to
|
the start of the quoted text on the last line, for example.
|
the start of the quoted text on the last line, for example.
|
|
|
If you do need to flush the buffer above, you can send an
|
If you do need to flush the buffer above, you can send an
|
endl if you also need a newline, or just flush the buffer
|
endl if you also need a newline, or just flush the buffer
|
yourself:
|
yourself:
|
|
|
|
|
output << ...... << flush; // can use std::flush manipulator
|
output << ...... << flush; // can use std::flush manipulator
|
output.flush(); // or call a member fn
|
output.flush(); // or call a member fn
|
On the other hand, there are times when writing to a file should
|
On the other hand, there are times when writing to a file should
|
be like writing to standard error; no buffering should be done
|
be like writing to standard error; no buffering should be done
|
because the data needs to appear quickly (a prime example is a
|
because the data needs to appear quickly (a prime example is a
|
log file for security-related information). The way to do this is
|
log file for security-related information). The way to do this is
|
just to turn off the buffering before any I/O operations at
|
just to turn off the buffering before any I/O operations at
|
all have been done (note that opening counts as an I/O operation):
|
all have been done (note that opening counts as an I/O operation):
|
|
|
|
|
std::ofstream os;
|
std::ofstream os;
|
std::ifstream is;
|
std::ifstream is;
|
int i;
|
int i;
|
|
|
os.rdbuf()->pubsetbuf(0,0);
|
os.rdbuf()->pubsetbuf(0,0);
|
is.rdbuf()->pubsetbuf(0,0);
|
is.rdbuf()->pubsetbuf(0,0);
|
|
|
os.open("/foo/bar/baz");
|
os.open("/foo/bar/baz");
|
is.open("/qux/quux/quuux");
|
is.open("/qux/quux/quuux");
|
...
|
...
|
os << "this data is written immediately\n";
|
os << "this data is written immediately\n";
|
is >> i; // and this will probably cause a disk read
|
is >> i; // and this will probably cause a disk read
|
Since all aspects of buffering are handled by a streambuf-derived
|
Since all aspects of buffering are handled by a streambuf-derived
|
member, it is necessary to get at that member with rdbuf() .
|
member, it is necessary to get at that member with rdbuf() .
|
Then the public version of setbuf can be called. The
|
Then the public version of setbuf can be called. The
|
arguments are the same as those for the Standard C I/O Library
|
arguments are the same as those for the Standard C I/O Library
|
function (a buffer area followed by its size).
|
function (a buffer area followed by its size).
|
|
|
A great deal of this is implementation-dependent. For example,
|
A great deal of this is implementation-dependent. For example,
|
streambuf does not specify any actions for its own
|
streambuf does not specify any actions for its own
|
setbuf() -ish functions; the classes derived from
|
setbuf() -ish functions; the classes derived from
|
streambuf each define behavior that "makes
|
streambuf each define behavior that "makes
|
sense" for that class: an argument of (0,0) turns off buffering
|
sense" for that class: an argument of (0,0) turns off buffering
|
for filebuf but does nothing at all for its siblings
|
for filebuf but does nothing at all for its siblings
|
stringbuf and strstreambuf , and specifying
|
stringbuf and strstreambuf , and specifying
|
anything other than (0,0) has varying effects.
|
anything other than (0,0) has varying effects.
|
User-defined classes derived from streambuf can
|
User-defined classes derived from streambuf can
|
do whatever they want. (For filebuf and arguments for
|
do whatever they want. (For filebuf and arguments for
|
(p,s) other than zeros, libstdc++ does what you'd expect:
|
(p,s) other than zeros, libstdc++ does what you'd expect:
|
the first s bytes of p are used as a buffer,
|
the first s bytes of p are used as a buffer,
|
which you must allocate and deallocate.)
|
which you must allocate and deallocate.)
|
|
|
A last reminder: there are usually more buffers involved than
|
A last reminder: there are usually more buffers involved than
|
just those at the language/library level. Kernel buffers, disk
|
just those at the language/library level. Kernel buffers, disk
|
buffers, and the like will also have an effect. Inspecting and
|
buffers, and the like will also have an effect. Inspecting and
|
changing those are system-dependent.
|
changing those are system-dependent.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Memory Based Streams
|
Memory Based Streams
|
|
|
Compatibility With strstream
|
Compatibility With strstream
|
|
|
|
|
Stringstreams (defined in the header <sstream> )
|
Stringstreams (defined in the header <sstream> )
|
are in this author's opinion one of the coolest things since
|
are in this author's opinion one of the coolest things since
|
sliced time. An example of their use is in the Received Wisdom
|
sliced time. An example of their use is in the Received Wisdom
|
section for Sect1 21 (Strings),
|
section for Sect1 21 (Strings),
|
describing how to
|
describing how to
|
format strings.
|
format strings.
|
|
|
The quick definition is: they are siblings of ifstream and ofstream,
|
The quick definition is: they are siblings of ifstream and ofstream,
|
and they do for std::string what their siblings do for
|
and they do for std::string what their siblings do for
|
files. All that work you put into writing << and
|
files. All that work you put into writing << and
|
>> functions for your classes now pays off
|
>> functions for your classes now pays off
|
again! Need to format a string before passing the string
|
again! Need to format a string before passing the string
|
to a function? Send your stuff via << to an
|
to a function? Send your stuff via << to an
|
ostringstream. You've read a string as input and need to parse it?
|
ostringstream. You've read a string as input and need to parse it?
|
Initialize an istringstream with that string, and then pull pieces
|
Initialize an istringstream with that string, and then pull pieces
|
out of it with >> . Have a stringstream and need to
|
out of it with >> . Have a stringstream and need to
|
get a copy of the string inside? Just call the str()
|
get a copy of the string inside? Just call the str()
|
member function.
|
member function.
|
|
|
This only works if you've written your
|
This only works if you've written your
|
<< />> functions correctly, though,
|
<< />> functions correctly, though,
|
and correctly means that they take istreams and ostreams as
|
and correctly means that they take istreams and ostreams as
|
parameters, not ifstreams and ofstreams. If they
|
parameters, not ifstreams and ofstreams. If they
|
take the latter, then your I/O operators will work fine with
|
take the latter, then your I/O operators will work fine with
|
file streams, but with nothing else -- including stringstreams.
|
file streams, but with nothing else -- including stringstreams.
|
|
|
If you are a user of the strstream classes, you need to update
|
If you are a user of the strstream classes, you need to update
|
your code. You don't have to explicitly append ends to
|
your code. You don't have to explicitly append ends to
|
terminate the C-style character array, you don't have to mess with
|
terminate the C-style character array, you don't have to mess with
|
"freezing" functions, and you don't have to manage the
|
"freezing" functions, and you don't have to manage the
|
memory yourself. The strstreams have been officially deprecated,
|
memory yourself. The strstreams have been officially deprecated,
|
which means that 1) future revisions of the C++ Standard won't
|
which means that 1) future revisions of the C++ Standard won't
|
support them, and 2) if you use them, people will laugh at you.
|
support them, and 2) if you use them, people will laugh at you.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File Based Streams
|
File Based Streams
|
|
|
|
|
Copying a File
|
Copying a File
|
|
|
|
|
|
|
So you want to copy a file quickly and easily, and most important,
|
So you want to copy a file quickly and easily, and most important,
|
completely portably. And since this is C++, you have an open
|
completely portably. And since this is C++, you have an open
|
ifstream (call it IN) and an open ofstream (call it OUT):
|
ifstream (call it IN) and an open ofstream (call it OUT):
|
|
|
|
|
#include <fstream>
|
#include <fstream>
|
|
|
std::ifstream IN ("input_file");
|
std::ifstream IN ("input_file");
|
std::ofstream OUT ("output_file");
|
std::ofstream OUT ("output_file");
|
Here's the easiest way to get it completely wrong:
|
Here's the easiest way to get it completely wrong:
|
|
|
|
|
OUT << IN;
|
OUT << IN;
|
For those of you who don't already know why this doesn't work
|
For those of you who don't already know why this doesn't work
|
(probably from having done it before), I invite you to quickly
|
(probably from having done it before), I invite you to quickly
|
create a simple text file called "input_file" containing
|
create a simple text file called "input_file" containing
|
the sentence
|
the sentence
|
|
|
|
|
The quick brown fox jumped over the lazy dog.
|
The quick brown fox jumped over the lazy dog.
|
surrounded by blank lines. Code it up and try it. The contents
|
surrounded by blank lines. Code it up and try it. The contents
|
of "output_file" may surprise you.
|
of "output_file" may surprise you.
|
|
|
Seriously, go do it. Get surprised, then come back. It's worth it.
|
Seriously, go do it. Get surprised, then come back. It's worth it.
|
|
|
The thing to remember is that the basic_[io]stream classes
|
The thing to remember is that the basic_[io]stream classes
|
handle formatting, nothing else. In chaptericular, they break up on
|
handle formatting, nothing else. In chaptericular, they break up on
|
whitespace. The actual reading, writing, and storing of data is
|
whitespace. The actual reading, writing, and storing of data is
|
handled by the basic_streambuf family. Fortunately, the
|
handled by the basic_streambuf family. Fortunately, the
|
operator<< is overloaded to take an ostream and
|
operator<< is overloaded to take an ostream and
|
a pointer-to-streambuf, in order to help with just this kind of
|
a pointer-to-streambuf, in order to help with just this kind of
|
"dump the data verbatim" situation.
|
"dump the data verbatim" situation.
|
|
|
Why a pointer to streambuf and not just a streambuf? Well,
|
Why a pointer to streambuf and not just a streambuf? Well,
|
the [io]streams hold pointers (or references, depending on the
|
the [io]streams hold pointers (or references, depending on the
|
implementation) to their buffers, not the actual
|
implementation) to their buffers, not the actual
|
buffers. This allows polymorphic behavior on the chapter of the buffers
|
buffers. This allows polymorphic behavior on the chapter of the buffers
|
as well as the streams themselves. The pointer is easily retrieved
|
as well as the streams themselves. The pointer is easily retrieved
|
using the rdbuf() member function. Therefore, the easiest
|
using the rdbuf() member function. Therefore, the easiest
|
way to copy the file is:
|
way to copy the file is:
|
|
|
|
|
OUT << IN.rdbuf();
|
OUT << IN.rdbuf();
|
So what was happening with OUT<<IN? Undefined
|
So what was happening with OUT<<IN? Undefined
|
behavior, since that chaptericular << isn't defined by the Standard.
|
behavior, since that chaptericular << isn't defined by the Standard.
|
I have seen instances where it is implemented, but the character
|
I have seen instances where it is implemented, but the character
|
extraction process removes all the whitespace, leaving you with no
|
extraction process removes all the whitespace, leaving you with no
|
blank lines and only "Thequickbrownfox...". With
|
blank lines and only "Thequickbrownfox...". With
|
libraries that do not define that operator, IN (or one of IN's
|
libraries that do not define that operator, IN (or one of IN's
|
member pointers) sometimes gets converted to a void*, and the output
|
member pointers) sometimes gets converted to a void*, and the output
|
file then contains a perfect text representation of a hexadecimal
|
file then contains a perfect text representation of a hexadecimal
|
address (quite a big surprise). Others don't compile at all.
|
address (quite a big surprise). Others don't compile at all.
|
|
|
Also note that none of this is specific to o*f*streams.
|
Also note that none of this is specific to o*f*streams.
|
The operators shown above are all defined in the parent
|
The operators shown above are all defined in the parent
|
basic_ostream class and are therefore available with all possible
|
basic_ostream class and are therefore available with all possible
|
descendants.
|
descendants.
|
|
|
|
|
|
|
|
|
|
|
Binary Input and Output
|
Binary Input and Output
|
|
|
|
|
The first and most important thing to remember about binary I/O is
|
The first and most important thing to remember about binary I/O is
|
that opening a file with ios::binary is not, repeat
|
that opening a file with ios::binary is not, repeat
|
not, the only thing you have to do. It is not a silver
|
not, the only thing you have to do. It is not a silver
|
bullet, and will not allow you to use the <</>>
|
bullet, and will not allow you to use the <</>>
|
operators of the normal fstreams to do binary I/O.
|
operators of the normal fstreams to do binary I/O.
|
|
|
Sorry. Them's the breaks.
|
Sorry. Them's the breaks.
|
|
|
This isn't going to try and be a complete tutorial on reading and
|
This isn't going to try and be a complete tutorial on reading and
|
writing binary files (because "binary"
|
writing binary files (because "binary"
|
covers a lot of ground), but we will try and clear
|
covers a lot of ground), but we will try and clear
|
up a couple of misconceptions and common errors.
|
up a couple of misconceptions and common errors.
|
|
|
First, ios::binary has exactly one defined effect, no more
|
First, ios::binary has exactly one defined effect, no more
|
and no less. Normal text mode has to be concerned with the newline
|
and no less. Normal text mode has to be concerned with the newline
|
characters, and the runtime system will translate between (for
|
characters, and the runtime system will translate between (for
|
example) '\n' and the appropriate end-of-line sequence (LF on Unix,
|
example) '\n' and the appropriate end-of-line sequence (LF on Unix,
|
CRLF on DOS, CR on Macintosh, etc). (There are other things that
|
CRLF on DOS, CR on Macintosh, etc). (There are other things that
|
normal mode does, but that's the most obvious.) Opening a file in
|
normal mode does, but that's the most obvious.) Opening a file in
|
binary mode disables this conversion, so reading a CRLF sequence
|
binary mode disables this conversion, so reading a CRLF sequence
|
under Windows won't accidentally get mapped to a '\n' character, etc.
|
under Windows won't accidentally get mapped to a '\n' character, etc.
|
Binary mode is not supposed to suddenly give you a bitstream, and
|
Binary mode is not supposed to suddenly give you a bitstream, and
|
if it is doing so in your program then you've discovered a bug in
|
if it is doing so in your program then you've discovered a bug in
|
your vendor's compiler (or some other chapter of the C++ implementation,
|
your vendor's compiler (or some other chapter of the C++ implementation,
|
possibly the runtime system).
|
possibly the runtime system).
|
|
|
Second, using << to write and >> to
|
Second, using << to write and >> to
|
read isn't going to work with the standard file stream classes, even
|
read isn't going to work with the standard file stream classes, even
|
if you use skipws during reading. Why not? Because
|
if you use skipws during reading. Why not? Because
|
ifstream and ofstream exist for the purpose of formatting,
|
ifstream and ofstream exist for the purpose of formatting,
|
not reading and writing. Their job is to interpret the data into
|
not reading and writing. Their job is to interpret the data into
|
text characters, and that's exactly what you don't want to happen
|
text characters, and that's exactly what you don't want to happen
|
during binary I/O.
|
during binary I/O.
|
|
|
Third, using the get() and put()/write() member
|
Third, using the get() and put()/write() member
|
functions still aren't guaranteed to help you. These are
|
functions still aren't guaranteed to help you. These are
|
"unformatted" I/O functions, but still character-based.
|
"unformatted" I/O functions, but still character-based.
|
(This may or may not be what you want, see below.)
|
(This may or may not be what you want, see below.)
|
|
|
Notice how all the problems here are due to the inappropriate use
|
Notice how all the problems here are due to the inappropriate use
|
of formatting functions and classes to perform something
|
of formatting functions and classes to perform something
|
which requires that formatting not be done? There are a
|
which requires that formatting not be done? There are a
|
seemingly infinite number of solutions, and a few are listed here:
|
seemingly infinite number of solutions, and a few are listed here:
|
|
|
|
|
|
|
Derive your own fstream-type classes and write your own
|
Derive your own fstream-type classes and write your own
|
<</>> operators to do binary I/O on whatever data
|
<</>> operators to do binary I/O on whatever data
|
types you're using.
|
types you're using.
|
|
|
|
|
This is a Bad Thing, because while
|
This is a Bad Thing, because while
|
the compiler would probably be just fine with it, other humans
|
the compiler would probably be just fine with it, other humans
|
are going to be confused. The overloaded bitshift operators
|
are going to be confused. The overloaded bitshift operators
|
have a well-defined meaning (formatting), and this breaks it.
|
have a well-defined meaning (formatting), and this breaks it.
|
|
|
|
|
|
|
|
|
Build the file structure in memory, then
|
Build the file structure in memory, then
|
mmap() the file and copy the
|
mmap() the file and copy the
|
structure.
|
structure.
|
|
|
|
|
|
|
Well, this is easy to make work, and easy to break, and is
|
Well, this is easy to make work, and easy to break, and is
|
pretty equivalent to using ::read() and
|
pretty equivalent to using ::read() and
|
::write() directly, and makes no use of the
|
::write() directly, and makes no use of the
|
iostream library at all...
|
iostream library at all...
|
|
|
|
|
|
|
|
|
Use streambufs, that's what they're there for.
|
Use streambufs, that's what they're there for.
|
|
|
|
|
While not trivial for the beginner, this is the best of all
|
While not trivial for the beginner, this is the best of all
|
solutions. The streambuf/filebuf layer is the layer that is
|
solutions. The streambuf/filebuf layer is the layer that is
|
responsible for actual I/O. If you want to use the C++
|
responsible for actual I/O. If you want to use the C++
|
library for binary I/O, this is where you start.
|
library for binary I/O, this is where you start.
|
|
|
|
|
|
|
How to go about using streambufs is a bit beyond the scope of this
|
How to go about using streambufs is a bit beyond the scope of this
|
document (at least for now), but while streambufs go a long way,
|
document (at least for now), but while streambufs go a long way,
|
they still leave a couple of things up to you, the programmer.
|
they still leave a couple of things up to you, the programmer.
|
As an example, byte ordering is completely between you and the
|
As an example, byte ordering is completely between you and the
|
operating system, and you have to handle it yourself.
|
operating system, and you have to handle it yourself.
|
|
|
Deriving a streambuf or filebuf
|
Deriving a streambuf or filebuf
|
class from the standard ones, one that is specific to your data
|
class from the standard ones, one that is specific to your data
|
types (or an abstraction thereof) is probably a good idea, and
|
types (or an abstraction thereof) is probably a good idea, and
|
lots of examples exist in journals and on Usenet. Using the
|
lots of examples exist in journals and on Usenet. Using the
|
standard filebufs directly (either by declaring your own or by
|
standard filebufs directly (either by declaring your own or by
|
using the pointer returned from an fstream's rdbuf() )
|
using the pointer returned from an fstream's rdbuf() )
|
is certainly feasible as well.
|
is certainly feasible as well.
|
|
|
One area that causes problems is trying to do bit-by-bit operations
|
One area that causes problems is trying to do bit-by-bit operations
|
with filebufs. C++ is no different from C in this respect: I/O
|
with filebufs. C++ is no different from C in this respect: I/O
|
must be done at the byte level. If you're trying to read or write
|
must be done at the byte level. If you're trying to read or write
|
a few bits at a time, you're going about it the wrong way. You
|
a few bits at a time, you're going about it the wrong way. You
|
must read/write an integral number of bytes and then process the
|
must read/write an integral number of bytes and then process the
|
bytes. (For example, the streambuf functions take and return
|
bytes. (For example, the streambuf functions take and return
|
variables of type int_type .)
|
variables of type int_type .)
|
|
|
Another area of problems is opening text files in binary mode.
|
Another area of problems is opening text files in binary mode.
|
Generally, binary mode is intended for binary files, and opening
|
Generally, binary mode is intended for binary files, and opening
|
text files in binary mode means that you now have to deal with all of
|
text files in binary mode means that you now have to deal with all of
|
those end-of-line and end-of-file problems that we mentioned before.
|
those end-of-line and end-of-file problems that we mentioned before.
|
|
|
|
|
An instructive thread from comp.lang.c++.moderated delved off into
|
An instructive thread from comp.lang.c++.moderated delved off into
|
this topic starting more or less at
|
this topic starting more or less at
|
this
|
this
|
post and continuing to the end of the thread. (The subject heading is "binary iostreams" on both comp.std.c++
|
post and continuing to the end of the thread. (The subject heading is "binary iostreams" on both comp.std.c++
|
and comp.lang.c++.moderated.) Take special note of the replies by James Kanze and Dietmar Kühl.
|
and comp.lang.c++.moderated.) Take special note of the replies by James Kanze and Dietmar Kühl.
|
|
|
Briefly, the problems of byte ordering and type sizes mean that
|
Briefly, the problems of byte ordering and type sizes mean that
|
the unformatted functions like ostream::put() and
|
the unformatted functions like ostream::put() and
|
istream::get() cannot safely be used to communicate
|
istream::get() cannot safely be used to communicate
|
between arbitrary programs, or across a network, or from one
|
between arbitrary programs, or across a network, or from one
|
invocation of a program to another invocation of the same program
|
invocation of a program to another invocation of the same program
|
on a different platform, etc.
|
on a different platform, etc.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Interacting with C
|
Interacting with C
|
|
|
|
|
|
|
Using FILE* and file descriptors
|
Using FILE* and file descriptors
|
|
|
See the extensions for using
|
See the extensions for using
|
FILE and file descriptors with
|
FILE and file descriptors with
|
ofstream and
|
ofstream and
|
ifstream.
|
ifstream.
|
|
|
|
|
|
|
|
|
Performance
|
Performance
|
|
|
Pathetic Performance? Ditch C.
|
Pathetic Performance? Ditch C.
|
|
|
It sounds like a flame on C, but it isn't. Really. Calm down.
|
It sounds like a flame on C, but it isn't. Really. Calm down.
|
I'm just saying it to get your attention.
|
I'm just saying it to get your attention.
|
|
|
Because the C++ library includes the C library, both C-style and
|
Because the C++ library includes the C library, both C-style and
|
C++-style I/O have to work at the same time. For example:
|
C++-style I/O have to work at the same time. For example:
|
|
|
|
|
#include <iostream>
|
#include <iostream>
|
#include <cstdio>
|
#include <cstdio>
|
|
|
std::cout << "Hel";
|
std::cout << "Hel";
|
std::printf ("lo, worl");
|
std::printf ("lo, worl");
|
std::cout << "d!\n";
|
std::cout << "d!\n";
|
|
|
This must do what you think it does.
|
This must do what you think it does.
|
|
|
Alert members of the audience will immediately notice that buffering
|
Alert members of the audience will immediately notice that buffering
|
is going to make a hash of the output unless special steps are taken.
|
is going to make a hash of the output unless special steps are taken.
|
|
|
The special steps taken by libstdc++, at least for version 3.0,
|
The special steps taken by libstdc++, at least for version 3.0,
|
involve doing very little buffering for the standard streams, leaving
|
involve doing very little buffering for the standard streams, leaving
|
most of the buffering to the underlying C library. (This kind of
|
most of the buffering to the underlying C library. (This kind of
|
thing is tricky to get right.)
|
thing is tricky to get right.)
|
The upside is that correctness is ensured. The downside is that
|
The upside is that correctness is ensured. The downside is that
|
writing through cout can quite easily lead to awful
|
writing through cout can quite easily lead to awful
|
performance when the C++ I/O library is layered on top of the C I/O
|
performance when the C++ I/O library is layered on top of the C I/O
|
library (as it is for 3.0 by default). Some patches have been applied
|
library (as it is for 3.0 by default). Some patches have been applied
|
which improve the situation for 3.1.
|
which improve the situation for 3.1.
|
|
|
However, the C and C++ standard streams only need to be kept in sync
|
However, the C and C++ standard streams only need to be kept in sync
|
when both libraries' facilities are in use. If your program only uses
|
when both libraries' facilities are in use. If your program only uses
|
C++ I/O, then there's no need to sync with the C streams. The right
|
C++ I/O, then there's no need to sync with the C streams. The right
|
thing to do in this case is to call
|
thing to do in this case is to call
|
|
|
|
|
#include any of the I/O headers such as ios, iostream, etc
|
#include any of the I/O headers such as ios, iostream, etc
|
|
|
std::ios::sync_with_stdio(false);
|
std::ios::sync_with_stdio(false);
|
|
|
You must do this before performing any I/O via the C++ stream objects.
|
You must do this before performing any I/O via the C++ stream objects.
|
Once you call this, the C++ streams will operate independently of the
|
Once you call this, the C++ streams will operate independently of the
|
(unused) C streams. For GCC 3.x, this means that cout and
|
(unused) C streams. For GCC 3.x, this means that cout and
|
company will become fully buffered on their own.
|
company will become fully buffered on their own.
|
|
|
Note, by the way, that the synchronization requirement only applies to
|
Note, by the way, that the synchronization requirement only applies to
|
the standard streams (cin , cout ,
|
the standard streams (cin , cout ,
|
cerr ,
|
cerr ,
|
clog , and their wide-character counterchapters). File stream
|
clog , and their wide-character counterchapters). File stream
|
objects that you declare yourself have no such requirement and are fully
|
objects that you declare yourself have no such requirement and are fully
|
buffered.
|
buffered.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|