Партнёры:
Хостинг:
NAME
istream - formatted and unformatted input
SYNOPSIS
#include <iostream.h>
typedef long streampos;
typedef long streamoff;
class unsafe_ios {
public:
// exported types
// stream operation mode
enum open_mode {
in = 0x01, // open for reading
out = 0x02, // open for writing
ate = 0x04, // seek to eof upon original open
app = 0x08, // append mode: all additions at eof
trunc = 0x10, // truncate file if already exists
nocreate = 0x20, // open fails if file doesn't exist
noreplace= 0x40 // open fails if file already exists
};
// stream seek direction
enum seek_dir { beg=0, cur=1, end=2 };
// formatting flags
enum {
skipws = 0x0001, // skip whitespace on input
left = 0x0002, // left-adjust output
right = 0x0004, // right-adjust output
internal = 0x0008, // padding after sign or base indicator
dec = 0x0010, // decimal conversion
oct = 0x0020, // octal conversion
hex = 0x0040, // hexidecimal conversion
showbase = 0x0080, // use base indicator on output
showpoint = 0x0100, // force decimal point (floating output)
uppercase = 0x0200, // upper-case hex output
showpos = 0x0400, // add '+' to positive integers
scientific= 0x0800, // use 1.2345E2 floating notation
fixed = 0x1000, // use 123.45 floating notation
unitbuf = 0x2000, // flush all streams after insertion
stdio = 0x4000 // flush stdout, stderr after insertion
};
// see ios(3C++) for remainder ...
};
class unsafe_istream : virtual public unsafe_ios {
public:
// exported functions
// unformatted input functions
unsafe_istream& read(char* ptr, int count);
unsafe_istream& read(unsigned char* ptr, int count);
unsafe_istream& get(char* ptr, int count, char delim='\n');
unsafe_istream& get(streambuf& sbuf, char delim='\n');
unsafe_istream& get(char& ch);
unsafe_istream& get(unsigned char& ch);
unsafe_istream& get_line (char *ptr, int count, char delim='\n');
unsafe_istream& get_line (unsigned char *ptr, int count, char delim='\n');
int get();
int peek();
unsafe_istream& ignore(int count=1, int delim=EOF);
unsafe_istream& putback(char ch);
// wide character
unsafe_istream& get(wchar_t* wptr, int count, wchar_t wdelim=L'\n');
unsafe_istream& get(wchar_t& wc);
unsafe_istream& getline(wchar_t* wptr, int count, wchar_t wdelim=L'\n');
unsafe_istream& wignore(count=1, wdelim=WEOF);
// other functions
int ipfx(int noform=0);
int wipfx(int noform=0); // wide character ipfx
unsafe_istream& seekg(streampos pos);
unsafe_istream& seekg(streamoff offset, unsafe_ios::seek_dir dir);
streampos tellg();
int sync();
int gcount();
public:
// exported operator functions
unsafe_istream& operator>> (char* buf);
unsafe_istream& operator>> (unsigned char* buf);
unsafe_istream& operator>> (char&);
unsafe_istream& operator>> (unsigned char&);
unsafe_istream& operator>> (short&);
unsafe_istream& operator>> (int&);
unsafe_istream& operator>> (long&);
unsafe_istream& operator>> (unsigned short&);
unsafe_istream& operator>> (unsigned int&);
unsafe_istream& operator>> (unsigned long&);
unsafe_istream& operator>> (float&);
unsafe_istream& operator>> (double&);
unsafe_istream& operator>> (streambuf* sbufp);
unsafe_istream& operator>> (unsafe_istream& (*manip)(unsafe_istream&));
unsafe_istream& operator>> (unsafe_ios& (*manip)(unsafe_ios&) );
public:
// wide character
unsafe_istream& operator>>(wchar_t&);
unsafe_istream& operator>>(wchar_t*);
public:
// exported constructors
unsafe_istream(streambuf* sbuf);
};
class istream : virtual public ios, public unsafe_istream {
public:
//exported functions
// unformatted input functions
istream& read(char* ptr, int count);
istream& read(unsigned char* ptr, int count);
istream& get(char* ptr, int count, char delim='\n');
istream& get(unsigned char* ptr,int count, char delim='\n');
istream& get(unsigned char& ch);
istream& get(char& ch);
istream& get(streambuf& sb, char delim ='\n');
istream& getline(char* ptr, int count, char delim='\n');
istream& getline(unsigned char* ptr, int count, char delim='\n');
int get();
int peek();
istream& ignore(int len=1,int delim=EOF);
istream& putback(char ch);
// wide character
istream& get(wchar_t* wptr, int count, wchar_t wdelim=L'\n');
istream& get(wchar_t& wc);
istream& getline(wchar_t* wptr, int count, wchar_t wdelim=L'\n');
istream& wignore(int count=1, wchar_t wdelim=WEOF);
wint_t peekw();
// other functions
int ipfx(int noform=0);
istream& seekg(streampos pos);
istream& seekg(streamoff offset, seek_dir dir);
streampos tellg();
int sync();
int gcount();
public:
// exported operator functions
istream& operator>>(char*);
istream& operator>>(unsigned char*);
istream& operator>>(char&);
istream& operator>>(unsigned char&);
istream& operator>>(short&);
istream& operator>>(int&);
istream& operator>>(long&);
istream& operator>>(unsigned short&);
istream& operator>>(unsigned int&);
istream& operator>>(unsigned long&);
istream& operator>>(float&);
istream& operator>>(double&);
istream& operator>>(streambuf*);
istream& operator>>(istream& (*)(istream&));
istream& operator>>(ios& (*)(ios&));
public:
// wide character
istream& operator>>(wchar_t&);
istream& operator>>(wchar_t*);
public:
// exported constructors
istream(streambuf*);
};
class istream_withassign : public istream {
public:
istream_withassign();
istream_withassign& operator= (istream&);
istream_withassign& operator= (streambuf*);
};
extern istream_withassign cin;
ios& dec(ios&);
ios& hex(ios&);
ios& oct(ios&);
istream& ws(istream&);
unsafe_ios& dec(unsafe_ios&) ;
unsafe_ios& hex(unsafe_ios&) ;
unsafe_ios& oct(unsafe_ios&) ;
unsafe_istream& ws(unsafe_istream&) ;
DESCRIPTION
Class istream supports formatted and unformatted extraction
(input) of data from an associated streambuf.
The istream object and its member functions are protected
against access by multiple threads by mutex locks. The
unsafe_istream object and its member functions do not imple-
ment mutex locking. Aside from this difference, the func-
tionality of istream and unsafe_istream and their respective
member functions is identical. For more information on mt-
safety, mutex locks and how these relate to iostreams
objects, see the "MT-Safe libC Programmers Guide".
ENVIRONMENT
The discussion about thread safety applies only to Solaris
2.x. On Solaris 1.x the ``safe'' and ``unsafe'' functions
behave identically. The wide character functions discussed
are supported only on Solaris 2.x.
Constructors and Assignment
istream(sbufp)
Associates the streambuf pointed to by sbufp with the
stream and initializes the ios state.
istream_withassign()
Performs no initialization.
istream_withassign isw = sbufp
Associates the streambuf pointed to by sbufp with isw
and completely initializes isw.
istream_withassign isw = istr
The streambuf associated with istr becomes associated
with isw and the constructor completely initializes
isw.
About wide character operations
Input functions that produce wide character results set
failbit if they encounter an illegal sequence of bytes. A
sequence of bytes is considered illegal if the input func-
tion cannot interpret it as multibyte encoding of characters
in the current locale.
Do not directly follow a multibyte input operation that may
peek ahead with a single-byte input operation. A single-
byte input operation is allowable after a seek (seekg).
streambufs need only support peeking one byte ahead, so mul-
tibyte input operations that peek may buffer "peeked" bytes
in the istream itself. seekg and tellg take account of any
such internal buffering.
Input prefix function
int i = istr.ipfx(noform)
Performs setup common to all extraction operations.
Formatted extractors call ipfx(0); unformatted extrac-
tors call ipfx(1). If the error state of istr is non-
zero, ipfx returns zero immediately. If a stream is
tied to istr (see tie in ios(3C++)) and noform is zero,
the tied stream is flushed. If the skipws flag is set
for the stream and noform is zero, leading whitespace
characters (as defined by iswhite, see ctype(3V)), are
skipped. Function ipfx returns zero if any error con-
dition is encountered, non-zero otherwise.
int i = istr.wipfx(noform)
Wide character extractors use wipfx in place of ipfx.
This is similar to ipfx(), but wipfx() skips over any
multibyte space as defined by iswspace where ipfx skips
over single-byte space characters. Furthermore wipfx()
sets ios::failbit if encounters an illegal sequence of
bytes. This function is not in the proposed ANSI ios-
treams interface, so avoid calling it directly from
application code.
Formatted input (extraction) functions
These call ipfx(0). If it returns zero, no further action
takes place. Otherwise, leading whitespace will be stripped
if ios::skipws is set. If only whitespace is left in the
istream, no characters will then remain and the ios::failbit
will be set. Wide character formatted input functions call
wipfx(0) and return with no further action if it returns
zero.
istr >> sbufp
Extracts characters from istr and inserts them into the
streambuf pointed to by sbufp. This function always
returns a reference to istr. You can use this function
to copy a stream efficiently, but you should be sure
that neither stream is tied. For example:
#include <iostream.h>
main()
{ // copy cin to cout
cin.tie(0);
cout.tie(0);
cin >> cout.rdbuf(); // see ios(3C++) for rdbuf
return 0;
}
istr >> x
Extracts characters from istr and converts them accord-
ing to the type of x. If ipfx returns zero, no charac-
ters are extracted and x is unchanged. Any errors
encountered are recorded in the error state of istr.
In general, ios::failbit means that the next available
characters were not suitable for the type; for example,
leading letters for a numeric type, or leading whi-
tespace for any type. The offending characters are not
extracted. In general, ios::badbit means that no char-
acters could be extracted; for example, attempting to
extract past the end of file. These functions always
return a reference to istr. User-written functions
should be of the form
istream& operator>> (istream&, SomeType)
and should conform to these principles.
The type of x and the format state of the istream (see
ios(3C++) determine the details of the extraction and
conversion. These functions do not change the state of
the istream, except that the width variable is reset to
zero after each formatted extraction. The predefined
formatted extractors are as follows:
char&, unsigned char&
Extracts one character and stores it in x.
wchar_t&
Extracts one multibyte character and stores it in x as
a wide character if wipfx(0) succeeds and it does not
encounter end-of- file. Sets ios::failbit if it
encounters an illegal sequence of bytes.
short&, unsigned short&
int&, unsigned int&
long&, unsigned long&
Extracts characters and converts them to an integral
value according to the conversion base in the istream's
format flags, and stores the value in x. The first
character may be a plus (`+') or minus (`-') sign. The
characters are then treated as decimal, octal, or hexa-
decimal, if the ios::basfield flags are dec, oct, or
hex, respectively. If none of these flags is set, the
number is interpreted in the same way as integer con-
stants in C++. That is, if the first two characters
are ``0x'' or ``0X'' the base is hex; otherwise, if the
first character is `0' the base is octal; otherwise the
base is decimal. Extraction (and thus conversion)
stops with the first non-digit, which is not extracted.
Valid digits are `0'-`7' for octal, `0'-`9' for
decimal, and `0'-`9', `a'-`f', `A'-`F' for hexadecimal.
The error flag ios::failbit is set if no valid digits
are encountered. A ``0x'' followed by a non-digit is
an error. In the case of an error, the value of x is
not changed.
float&, double&
Extracts characters and converts them to a floating-
point value according to the C++ rules for floating-
point constants, and stores the value in x. The error
flag ios::failbit is set if the characters extracted do
not begin a well-formed floating-point number; some
characters may be extracted in this case, depending on
at what point the error is detected. In the case of an
error, the value of x is not changed.
char*, unsigned char*
Extracts characters and stores them in the array
pointed to by x until a whitespace character is encoun-
tered. The whitespace is not extracted (but ipfx may
have discarded leading whitespace). If the width for-
matting variable (see ios(3C++)) is non-zero, at most
width-1 characters are extracted. A terminating null
(0) is always stored in x, even when nothing is
extracted. The error flag ios::failbit is set if no
characters are available for extraction.
wchar_t*
Behaves like the extractor for char* except it decodes
characters in multibyte representation into an array of
wide characters until it encounters a multibyte whi-
tespace character. In addition sets ios::failbit if it
encounters an illegal sequence of bytes.
Unformatted input (extraction) functions
These call ipfx(1). If it returns zero, no further action
takes place. Leading whitespace is not skipped, and no
conversions take place. Wide character input functions call
wipfx(1) in place of ipfx(1).
int c = istr.get()
Extracts the next character from istr and returns it.
Returns EOF if no more characters are available; never
sets ios::failbit.
istr.get(ch)
Extracts the next character from istr and stores it in
ch. Stores EOF if no more characters are available;
sets ios::failbit when attempting to extract beyond
EOF. This function always returns a reference to istr.
istr.get(ptr, count, delim)
Extracts characters from istr and stores them in the
char array beginning at ptr. Extraction stops after
count-1 characters have been extracted or when a char-
acter matching delim is encountered, whichever happens
first. If a delim character is encountered, it is not
extracted or stored. This function always stores a
terminating null (0) even if nothing is extracted. It
sets ios::failbit only if EOF is encountered before any
characters are stored. This function always returns a
reference to istr.
istr.get(sbuf, delim)
Extracts characters from istr and stores them in the
streambuf sbuf. Extraction stops when a character
matching delim (or EOF) is encountered, or when a store
into sbuf fails, whichever happens first. If a delim
character is encountered, it is not extracted or
stored. If delim is EOF, extraction stops only when
input is exhausted or when a store fails. This func-
tion sets ios::failbit only if a store into sbuf fails;
it always returns a reference to istr.
istr.get(wc)
Extracts the next character from istr and stores it in
wc in its wide character representation. Stores WEOF
if no more characters are available; sets ios::failbit
when attempting to extract beyond end of file or if it
encounters an illegal sequence of bytes. Returns a
reference to istr.
istr.get(wptr, count, wdelim)
Same as for single-byte characters, but wptr points to
an array of wchar_t and wdelim is of type wchar_t.
Sets ios::failbit if it encounters an illegal sequence
of bytes. Returns a reference to istr.
istr.getline(ptr, count, delim)
This function does the same thing as istr.get(ptr,
count, delim), except that delim, if encountered, is
extracted but not stored. Once count-1 characters have
been extracted, the next character is left in istr,
even if it is delim. This function always returns a
reference to istr.
istr.getline(wptr, count, wdelim)
As for single-byte characters, but wptr points to an
array of wchar_t and wdelim is of type wchar_t. Sets
ios::failbit if it encounters an illegal sequence of
bytes. Returns a reference to istr.
istr.ignore(count, delim)
Extracts characters from istr and discards them.
Extraction stops when a character matching delim is
encountered, when count characters have been extracted,
or when EOF is encountered, whichever happens first;
the delim character is extracted. If delim is EOF, all
of the input is discarded. This function always
returns a reference to istr.
istr.wignore(count=1, wdelim=WEOF)
As for ignore(), but if wdelim is not WEOF, count indi-
cates the number of multibyte characters to skip rather
than the number of bytes to skip. Even if wdelim is
WEOF, sets ios::failbit and stops if it encounters an
illegal sequence of bytes. Returns a reference to
istr.
istr.read(ptr, count)
Extracts characters from istr and stores them in the
char array beginning at ptr. Extraction stops after
count characters have been extracted or when EOF is
encountered, whichever happens first. This function
sets ios::failbit if EOF is encountered before count
characters are extracted; it always returns a reference
to istr. The number of characters extracted can be
found by calling istr.gcount(). (See below.)
Positioning functions
These deal with the get pointer of the streambuf associated
with an istream. See .BR sbufpub (3C++) for a complete dis-
cussion. Multibyte input operations may cause the get
pointer of the streambuf to differ from the value reported
by tellg(), but seeks done on the istream itself will still
coordinate correctly with all operations on the istream.
istr.seekg(pos)
Sets the position of the get pointer; returns istr.
istr.seekg(offset, dir)
Sets the position of the get pointer; returns istr.
streampos pos = istr.tellg()
Returns the current position of the get pointer. Mul-
tibyte input operations may cause the get pointer of
the streambuf to differ from the value reported by
tellg(), but seeks done on the istream rather than the
streambuf will still coordinate correctly with all
operations on the istream.
Miscellaneous functions
int i = istr.gcount()
Returns the number of characters extracted from istr by
the last unformatted input function. Note: Formatted
input functions might call unformatted functions, thus
changing the count. After an unformatted wide charac-
ter input function, gcount() returns the number of
(multibyte) characters extracted.
int i = istr.peek()
First calls istr.ipfx(1). If ipfx returns zero or if
istr is at EOF, it returns EOF. Otherwise, it returns
the next character without extracting it.
int i = istr.peekw()
Calls wipfx(1) and returns (wint_t)WEOF if that fails.
Sets ios::failbit and returns WEOF if it encounters an
illegal sequence of bytes. If successful, returns the
next character in the stream as a wide character
without moving past it.
istr.putback(ch)
If istr.fail() returns non-zero, this function returns
without doing anything. Otherwise, it attempts to back
up the streambuf associated with istr by pushing back
character ch. Because it does no extraction, it does
not call ipfx. It may fail, setting ios::failbit. In
general, c must match the character ahead of the
streambuf's get pointer (normally the last character
extracted) - input might be coming from a read-only
in-memory buffer.
int i = istr.sync()
Forces a correspondence between the internal data
structures and the external source of characters in an
implementation-defined manner. It calls the virtual
function istr.rdbuf()->sync(), which of course will
depend on the actual type of the buffer class. It
returns EOF on error.
Predefined Manipulators
A manipulator may be used apparently as an inserted or
extracted object, but many only change the state of the
stream. See manip(3C++) and ios(3C++) for more information.
Several manipulators are predefined for use with istreams.
istr >> manip
This is equivalent to the call manip(istr).
istr >> dec
This sets the conversion base of istr to 10.
istr >> oct
This sets the conversion base of istr to 8.
istr >> hex
This sets the conversion base of istr to 16.
istr >> ws
This extracts and discards consecutive whitespace char-
acters from istr.
SEE ALSO
ios.intro(3C++), ctype(3V), ios(3C++), manip(3C++),
sbufpub(3C++), stdiobuf(3C++), MT-Safe libC Programmer's
Guide, Iostreams Tutorial.
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |