mirror of
https://gitlab.com/fbb-git/cppannotations
synced 2024-11-16 07:48:44 +01:00
87ea19cac2
git-svn-id: https://cppannotations.svn.sourceforge.net/svnroot/cppannotations/trunk@435 f6dd340e-d3f9-0310-b409-bdd246841980
122 lines
6.4 KiB
Text
122 lines
6.4 KiB
Text
The class tt(istream) supports both formatted and unformatted
|
|
emi(binary input). The emi(extraction operator) (ti(operator>>)) is
|
|
used to extract values in a i(type safe) way from tt(istream) objects. This
|
|
is called i(formatted input), whereby human-readable i(ASCII) characters are
|
|
converted, according to certain formatting rules, to binary values.
|
|
|
|
The extraction operator points to the objects or variables which receive new
|
|
values. The normal associativity of rshift() remains unaltered, so when a
|
|
statement like
|
|
verb(
|
|
cin >> x >> y;
|
|
)
|
|
is encountered, the leftmost two
|
|
operands are evaluated first (tt(cin) rshift() tt(x)), and an tt(istream &)
|
|
object, which is actually the same tt(cin) object, is returned. Now, the
|
|
statement is reduced to
|
|
verb(
|
|
cin >> y
|
|
)
|
|
and the tt(y) variable is extracted from tt(cin).
|
|
|
|
The rshift() operator has many (overloaded) variants and thus many types of
|
|
variables can be extracted from tt(istream) objects. There is an overloaded
|
|
rshift() available for the extraction of an tt(int), of a tt(double), of a
|
|
string, of an array of characters, possibly to a pointer, etc. etc.. String or
|
|
character array extraction hi(string extraction) hi(extracting strings)
|
|
by default first skips all white space characters, and will then extract all
|
|
consecutive non-white space characters. Once an extraction operator has been
|
|
processed the tt(istream) object from which the information was extracted is
|
|
returned and it can immediately be used for additional tt(istream)
|
|
operations that appear in the same expression.
|
|
|
|
Streams lack facilities for formatted input (as used by, e.g., bf(C)'s
|
|
ti(scanf) and ti(vscanf) functions). Although it is not difficult to add these
|
|
facilities to the world of streams, tt(scanf)-like functionality is hardly
|
|
ever required in bf(C++) programs. Furthermore, as it is potentially
|
|
type-em(unsafe), it might be better to avoid formatted input completely.
|
|
|
|
When hi(binary file) binary files must be read, the information should
|
|
normally not be formatted: an tt(int) value should be read as a series of
|
|
unaltered bytes, not as a series of i(ASCII) numeric characters 0 to 9. The
|
|
following member functions for reading information from tt(istream) objects
|
|
are available:
|
|
itemization(
|
|
ithtq(gcount)(int gcount() const)
|
|
(the number of characters read from the input stream
|
|
by the last unformatted input operation is returned.)
|
|
ithtq(get)(int get())
|
|
(the next available single character is returned
|
|
as an unsigned tt(char) value using an tt(int) return type.
|
|
endOfFile() is returned if no more character are available.)
|
|
ittq(istream &get(char &ch))
|
|
(the next single character read from the input stream is
|
|
stored in tt(ch). The member function returns the stream itself which may be
|
|
inspected to determine whether a character was obtained or not.)
|
|
ittq(istream& get(char *buffer, int len, char delim = '\n'))
|
|
(At most tt(len - 1) characters are read from the input
|
|
stream into the array starting at tt(buffer), which should be at least tt(len)
|
|
bytes long. Reading also stops when the delimiter tt(delim) is
|
|
encountered. However, the delimiter itself is em(not removed) from the input
|
|
stream.
|
|
|
|
Having stored the characters into tt(buffer), an ti(ASCII-Z) character is
|
|
written beyond the last character stored into the tt(buffer). The functions
|
|
tt(eof) and tt(fail) (see section ref(IOSTATES)) return 0 (tt(false)) if the
|
|
delimiter was encountered before reading tt(len - 1) characters or if the
|
|
delimiter was not encountered after reading tt(len - 1) characters.
|
|
It is OK to specifiy an tt(ASCII-Z) delimiter: this way strings
|
|
terminating in tt(ASCII-Z) characters may be read from a (binary) file.
|
|
)
|
|
ithtq(getline)
|
|
(istream& getline(char *buffer, int len, char delim = '\n'))
|
|
(this member function operates analogously to the tt(get) member
|
|
function, but tt(getline) removes tt(delim) from the stream if it is actually
|
|
encountered. The delimiter itself, if encountered, is em(not) stored in the
|
|
tt(buffer). If tt(delim) was em(not) found (before reading tt(len - 1)
|
|
characters) the tt(fail) member function, and possibly also tt(eof) returns
|
|
true. Realize that the tt(std::string) class also offers a function
|
|
tt(std::getline) which is generally preferred over this tt(getline) member
|
|
function that is described here (see section ref(STRINGMEMBERS)).
|
|
)
|
|
ithtq(ignore)
|
|
(istream& ignore())
|
|
(one character is skipped from the input stream.)
|
|
ittq(istream& ignore(int n))
|
|
(tt(n) characters are skipped from the input stream.)
|
|
ittq(istream& ignore(int n, int delim))
|
|
(at most tt(n) characters are skipped but skipping characters
|
|
stops after having removed tt(delim) from the input stream.)
|
|
ithtq(peek)(int peek())
|
|
(this function returns the next available input character,
|
|
but does not actually remove the character from the input stream. endOfFile()
|
|
is returned if no more characters are available.)
|
|
ithtq(putback)(istream& putback(char ch))
|
|
(The character tt(ch) is `pushed back' into the input stream, to
|
|
be read again as the next available character. endOfFile() is returned if this
|
|
is not allowed. Normally, it is OK to put back one character. Example:
|
|
verb(
|
|
string value;
|
|
cin >> value;
|
|
cin.putback('X');
|
|
// displays: X
|
|
cout << static_cast<char>(cin.get());
|
|
)
|
|
)
|
|
ithtq(read)(istream &read(char *buffer, int len))
|
|
(At most tt(len) bytes are read from the input stream into the
|
|
buffer. If endOfFile() is encountered first, fewer bytes are read, with the
|
|
member function tt(eof) returning tt(true). This function is commonly used
|
|
when reading em(binary) files. Section ref(IFSTREAM) contains an example in
|
|
which this member function is used. The member function tt(gcount()) may be
|
|
used to determine the number of characters that were retrieved by tt(read).
|
|
)
|
|
ithtq(readsome)(istream& readsome(char *buffer, int len))
|
|
(at most tt(len) bytes are read from the input stream into the
|
|
buffer. All available characters are read into the buffer, but if endOfFile()
|
|
is encountered, fewer bytes are read, without setting the tt(ios::eofbit)
|
|
or tt(ios::failbit).
|
|
)
|
|
ithtq(unget)(istream &unget())
|
|
(the last character that was read from the stream is put back.)
|
|
)
|