Miroirs/cppannotations
1
0
Fork 0
mirror of https://gitlab.com/fbb-git/cppannotations synced 2024-11-16 07:48:44 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

WIP on IOstreams

Browse source 
git-svn-id: https://cppannotations.svn.sourceforge.net/svnroot/cppannotations/trunk@261 f6dd340e-d3f9-0310-b409-bdd246841980
This commit is contained in:
Frank B. Brokken 2009-10-22 14:59:49 +00:00
parent f8d4cbd9e7
commit 4af5bc87fd
9 changed files with 123 additions and 123 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
yo/iostreams.yo
View file

@ -23,8 +23,6 @@ includefile(iostreams/ios)
lsubsubsect(FORMATFLAGS)(Formatting flags)
includefile(iostreams/flags)
COMMENT( >>>>>>>>>>> NEXT <<<<<<<<<<<<<)
sect(Output)
includefile(iostreams/output)
@ -40,6 +38,8 @@ includefile(iostreams/output)
subsubsect(`ostream' flushing)
includefile(iostreams/ostreamflush)
COMMENT( >>>>>>>>>>> NEXT <<<<<<<<<<<<<)
lsubsect(OFSTREAM)(Output to files: the class `ofstream')
includefile(iostreams/ofstream)

4
yo/iostreams/examples/isopen.cc
View file

@ -7,11 +7,11 @@
{
ofstream of;
cout << "of's open state: " << boolalpha << of.is_open() << endl;
cout << "of's open state: " << boolalpha << of.is_open() << '\n';
of.open("/dev/null"); // on Unix systems
cout << "of's open state: " << of.is_open() << endl;
cout << "of's open state: " << of.is_open() << '\n';
}
/*
Generated output:

12
yo/iostreams/flags.yo
View file

@ -223,12 +223,12 @@ in section ref(IOS)). Example:
combination with memory-streams (cf. section ref(OSTRINGSTREAM)).
)
ithtq(flush)(std::flush)
(manipulator flushing the stream. Often flushing the stream is not
required and doing so would needlessly slow down I/O processing. Consequently,
using tt(flush) should be avoided unless it is explicitly required to do
so. Note that streams are automatically flushed when the program terminates or
when a stream is `tied' to another stream (cf. tt(tie) in section
ref(IOS)). Example:
(a stream may be flushed using this member. Often flushing the stream
is not required and doing so would needlessly slow down I/O
processing. Consequently, using tt(flush) should be avoided unless it is
explicitly required to do so. Note that streams are automatically flushed when
the program terminates or when a stream is `tied' to another stream
(cf. tt(tie) in section ref(IOS)). Example:
verb(
cout << "hello" << flush; // avoid if possible.
)

16
yo/iostreams/ofstream.yo
View file

@ -1,12 +1,14 @@
The ti(ofstream) class is derived from the tt(ostream) class: it has the same
capabilities as the tt(ostream) class, but can be used to i(access files) or
i(create files) for writing.
The hi(ofstream)tt(std::ofstream) class is derived from the tt(ostream) class:
it has the same capabilities as the tt(ostream) class, but can be used to
i(access files) or i(create files) for writing.
In order to use the tt(ofstream) class in bf(C++) sources, the
i(preprocessor directive) ti(#include <fstream>) must be given. After
including tt(fstream) hi(fstream: and cin, cout) the standard streams tt(cin),
tt(cout) and tt(cerr) are em(not) declared. If these latter objects are
needed too, then tt(iostream) should also be included.
ti(fstream) header file must be included. Including tt(fstream) will not
automatically make available the standard streams tt(cin), tt(cout) and
tt(cerr). Include ti(iostream) to declare these standard streams.
COMMENT( >>>>>>>>>>> NEXT <<<<<<<<<<<<<)
The following hi(ofstream constructors) constructors are available for
tt(ofstream) objects:

50
yo/iostreams/ostream.yo
View file

@ -1,30 +1,28 @@
The class ti(ostream) is the class defining basic output facilities. The
ti(cout), ti(clog) and ti(cerr) objects are all tt(ostream) objects. Note that
all facilities defined in the tt(ios) class, as far as output is concerned, is
available in the tt(ostream) class as well, due to the inheritance mechanism
(discussed in chapter ref(INHERITANCE)).
The class ti(ostream) defines basic output facilities. The ti(cout), ti(clog)
and ti(cerr) objects are all tt(ostream) objects. All facilities related to
output as defined by the tt(ios) class are also available in the tt(ostream)
class.
We can construct tt(ostream) objects using the following
emi(ostream constructor):
We may define tt(ostream) objects using the following
emi(ostream constructor):
itemization(
itt(ostream object(streambuf *sb)):
quote(this constructor can be used to construct a wrapper around
an existing tt(streambuf), which may be the interface to an existing file. See
chapter ref(CONCRETE) for examples.) What this boils down to is that it isn't
possible to construct a plain tt(ostream) object that can be used for
insertions. When tt(cout) or its friends are used, we are actually using a
predefined tt(ostream) object that has already been created for us, and
interfaces to, e.g., the standard output stream using a (also predefined)
tt(streambuf) object handling the actual interfacing.
itt(std::ostream object(std::streambuf *sb)):
quote(this constructor creates an tt(ostream) object which is a
wrapper around an existing tt(std::streambuf) object. It isn't possible to
define a plain tt(ostream) object (e.g., using tt(std::ostream out;)) that
can thereupon be used for insertions. When tt(cout) or its friends are used,
we are actually using a predefined tt(ostream) object that has already been
defined for us and interfaces to the standard output stream using a
(also predefined) tt(streambuf) object handling the actual interfacing.
Note that it em(is) possible to construct an tt(ostream) object passing it
a hi(std::ostream: constructed using a 0-pointer) 0-pointer as a
tt(streambuf). Such an object cannot be used for insertions (i.e., it will
raise its tt(ios::bad) flag when something is inserted into it), but since it
may be given a tt(streambuf) later, it may be preliminary constructed,
receiving its tt(streambuf) once it becomes available.
It em(is), however, possible to define an tt(ostream) object passing it
hi(ostream: define using 0-pointer) a 0-pointer. Such an object cannot be
used for insertions (i.e., it will raise its tt(ios::bad) flag when something
is inserted into it), but it may be given a tt(streambuf) later. Thus it may
be preliminary constructed, suspending its use until an appropriate
tt(streambuf) becomes available.
)
In order to use the tt(ostream) class in bf(C++) sources, the
ti(#include <ostream>) i(preprocessor directive) must be given. To use the
predefined tt(ostream) objects, the ti(#include <iostream>) preprocessor
directive must be given.
In order to define the tt(ostream) class in bf(C++) sources, the
ti(ostream) header file must be included. To use the predefined
tt(ostream) objects (tt(std::cin, std::cout) etc.) the ti(iostream) header
must be included.

27
yo/iostreams/ostreamflush.yo
View file

@ -1,20 +1,21 @@
Unless the ti(ios::unitbuf) flag has been set, information written to an
Unless the tt(ios::unitbuf) flag has been set, information written to an
tt(ostream) object is not immediately written to the physical stream. Rather,
an internal buffer is filled up during the write-operations, and when full it
an internal buffer is filled during the write-operations, and when full it
is flushed.
The i(internal buffer) can be flushed under program control:
The stream's i(internal buffer) can be flushed under program control:
itemization(
itht(ostream::flush())(ostream& ostream::flush()):
quote(
this member function writes any buffered information to the tt(ostream)
object. The call to tt(flush()) is implied when:
ithtq(flush)(ostream& ostream::flush()):
(any buffered information stored internally by the tt(ostream) object
is flushed to the device to which the tt(ostream) object interfaces. A stream
is flushed automatically when:
itemization(
it() The tt(ostream) object ceases to exist,
it() The tt(endl) or tt(flush) em(manipulators) (see section
ref(MANIPULATORS)) are inserted into the tt(ostream) object,
it() A stream derived from tt(ostream) (like tt(ofstream), see section
ref(OFSTREAM)) is closed.
)
it() the object ceases to exist;
it() the tt(endl) or tt(flush) em(manipulators) (see section
ref(FORMATFLAGS)) are inserted into an tt(ostream) object;
it() a stream supporting the ti(close)-operation is explicitly closed
(e.g., a tt(std::ofstream) object, cf. section ref(OFSTREAM)).
)
)
)

61
yo/iostreams/ostreamseek.yo
View file

@ -1,39 +1,38 @@
Although not every tt(ostream) object supports i(repositioning), they usually
do. This means that it is possible to rewrite a section of the stream which
was written earlier. Repositioning is frequently used in
emi(database applications) where it must be possible to access the
information in the database randomly.
was written earlier. Repositioning is frequently used in database applications
where it must be possible to access the information in the database at random.
The following members are available:
The current position can be obtained and modified using the following members:
itemization(
itht(ostream::tellp())(pos_type ostream::tellp()):
quote(this function returns the current (absolute) position where
the next write-operation to the stream will take place. For all practical
purposes a ti(pos_type) can be considered to be an tt(unsigned long).)
itht(ostream::seekp())
(ostream &ostream::seekp(off_type step, ios::seekdir org)):
quote(This member function can be used to reposition the
stream. The function expects an ti(off_type) tt(step), the stepsize in bytes
to go from tt(org). For all practical purposes an tt(off_type) can be
considered to be a tt(long).
The origin of the step, tt(org) is an ti(ios::seekdir) value. Possible
values are:
ithtq(tellp)(ios::pos_type ostream::tellp()):
(the current (absolute) position in the file where the next
write-operation to the stream will take place is returned.)
ithtq(seekp)
(ostream &ostream::seekp(ios::off_type step, ios::seekdir org))
(modifies a stream's actual position. The function expects an
ti(off_type) tt(step) representing the number of bytes the current stream
position is moved with respect to tt(org). The tt(step) value
may be negative, zero or positive.
The origin of the step, tt(org) is a value in the
hi(seekdir)tt(ios::seekdir) enumeration. Its values are:
itemization(
iti(ios::beg):
quote(tt(org) is interpreted as the stepsize relative to the
beginning of the stream. If tt(org) is not specified, tt(ios::beg) is
used. )
iti(ios::cur):
quote(tt(org) is interpreted as the stepsize relative to the
current position (as returned by tt(tellp()) of the stream).)
iti(ios::end):
quote(tt(org) is interpreted as the stepsize relative to the
current end position of the the stream.)
ithtq(beg)(ios::beg)
(the stepsize is computed relative to the beginning of the
stream. This value is used by default.
)
ithtq(cur)(ios::cur)
(the stepsize is computed relative to the current position of the
stream (as returned by tt(tellp)).
)
itttq(end)(ios::end)
(the stepsize is interpreted relative to the current end position
of the the stream.)
)
It is OK to i(seek beyond end of file)hi(write beyond end of file).
Writing bytes to a location beyond endOfFile() will pad the intermediate bytes
with i(ASCII-Z) values: i(null-bytes). It is em(not) allowed to
i(seek before the begining of a file).
Seeking before tt(ios::beg) will cause the ti(ios::fail) flag to be set.
It is OK to
hi(write beyond end of file)hi(seek beyond file boundaries) seek or write
beyond the last file position. Writing bytes to a location beyond endOfFile()
will pad the intermediate bytes with i(ASCII-Z) values: i(null-bytes).
Seeking before tt(ios::beg) raises the hi(fail)tt(ios::fail) flag.
)
)

48
yo/iostreams/ostreamwrite.yo
View file

@ -1,13 +1,13 @@
The class ti(ostream) supports both formatted and emi(binary output).
The emi(insertion operator) (lshift()) may be used to insert values in
a i(type safe) way into tt(ostream) objects. This is called
The emi(insertion operator) (lshift()) is used to insert values in
a type safe way into tt(ostream) objects. This is called
i(formatted output), as binary values which are stored in the computer's
memory are converted to human-readable i(ASCII) characters according to
certain formatting rules.
Note that the insertion operator points to the tt(ostream )object wherein the
information must be inserted. The normal associativity of lshift()
Note that the insertion operator points to the tt(ostream) object to
receive the information. The normal associativity of lshift()
remains unaltered, so when a statement like
verb(
cout << "hello " << "world";
@ -23,38 +23,40 @@ same tt(cout) object, is returned. Now, the statement is reduced to
The lshift() operator has a lot of (overloaded) variants, so many types of
variables can be inserted into tt(ostream) objects. There is an overloaded
lshift()-operator expecting an tt(int), a tt(double), a pointer, etc. etc..
For every part of the information that is inserted into the stream the operator
returns the tt(ostream) object into which the information so far was inserted,
and the next part of the information to be inserted is processed.
Each operator will return the tt(ostream) object into which the information so
far has been inserted, followed by the next insertion.
Streams do not have facilities for formatted output like bf(C)'s
ti(printf()) and ti(vprintf()) functions. Although it is not difficult to
implement these facilities in the world of streams, tt(printf())-like
Streams lack facilities for formatted output like bf(C)'s
ti(printf) and ti(vprintf) functions. Although it is not difficult to
implement these facilities in the world of streams, tt(printf)-like
functionality is hardly ever required in bf(C++) programs. Furthermore, as it
is potentially type-em(unsafe), it might be better to avoid this functionality
completely.
When hi(binary files) binary files must be written, normally no
text-formatting is used or required: an tt(int) value should be written as a
series of unaltered bytes, not as a series of i(ASCII) numeric characters 0 to
series of raw bytes, not as a series of i(ASCII) numeric characters 0 to
9. The following member functions of tt(ostream) objects may be used to
write `binary files':
itemization(
it() hi(ostream::put()) tt(ostream& ostream::put(char c)):
quote(This member function writes a single character to the output
stream. Since a character is a byte, this member function could also be used
for writing a single character to a hi(text files) text-file.)
it() hi(ostream::write())
tt(ostream& ostream::write(char const *buffer, int length)):
quote(This member function writes at most tt(length) bytes, stored
in the tt(char const *buffer) to the tt(ostream) object. The bytes are written
as they are stored in the buffer, no formatting is done whatsoever. Note that
the first argument is a tt(char const *): a em(type_cast) is required to write
any other type. For example, to write an tt(int) as an unformatted series of
byte-values:
ithtq(put)(ostream& ostream::put(char c))
(to write a single character to the output stream. Since a character
is a byte, this member function could also be used for writing a single
character to a text-file.
ithtq(write)(ostream& ostream::write(char const *buffer, int length))
(to write at most tt(length) bytes, stored in the tt(char const
*buffer) to the tt(ostream) object. Bytes are written as they are stored
in the buffer, no formatting is done whatsoever. Note that the first argument
is a tt(char const *): a em(type cast) is required to write any other
type. For example, to write an tt(int) as an unformatted series of
byte-values use:
verb(
int x;
out.write(reinterpret_cast<char const *>(&x), sizeof(int));
)
)
Also note that the bytes written by the above tt(write) call will be
written in an order depending on the emi(endian)em(-ness) of the underlying
hardware. Big-endian computers will write the most significant byte first,
little-endian computers will first write the least significant byte.
)

24
yo/iostreams/output.yo
View file

@ -1,17 +1,15 @@
In bf(C++) i(output) is primarily based on the ti(ostream) class. The
tt(ostream) class defines the basic operators and members for inserting
information into streams: the emi(insertion operator) (lshift()), and
special members like tt(ostream::write()) for writing unformatted information
to streams.
In bf(C++) output is primarily based on the hi(ostream)tt(std::ostream)
class. The tt(ostream) class defines the basic operators and members inserting
information into streams: the emi(insertion operator) (lshift()), and special
members like tt(write) writing unformatted information to streams.
From the class tt(ostream) several other classes are derived, all having the
functionality of the tt(ostream) class, and adding their own specialties. In
the next sections on `output' we will introduce:
The class tt(ostream) acts as em(base class) for several other classes, all
having the functionality of the tt(ostream) class, but adding their own
specialties. In the upcoming sections we will introduce:
itemization(
it() The class tt(ostream), offering the basic facilities for doing output;
it() The class ti(ofstream), allowing us to open files for writing
(comparable to bf(C)'s hi(fopen()) tt(fopen(filename, "w")));
it() The class tt(ostream), offering the basic output facilities;
it() The class ti(ofstream), allowing us to write files
(comparable to bf(C)'s hi(fopen) tt(fopen(filename, "w")));
it() The class ti(ostringstream), allowing us to write information to
memory rather than to files (streams) (comparable to bf(C)'s ti(sprintf())
function).
memory (comparable to bf(C)'s ti(sprintf) function).
)