1 // Input streams -*- C++ -*-
3 // Copyright (C) 1997, 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
5 // This file is part of the GNU ISO C++ Library. This library is free
6 // software; you can redistribute it and/or modify it under the
7 // terms of the GNU General Public License as published by the
8 // Free Software Foundation; either version 2, or (at your option)
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 // GNU General Public License for more details.
16 // You should have received a copy of the GNU General Public License along
17 // with this library; see the file COPYING. If not, write to the Free
18 // Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307,
21 // As a special exception, you may use this file as part of a free software
22 // library without restriction. Specifically, if other files instantiate
23 // templates or use macros or inline functions from this file, or you compile
24 // this file and link it with other files to produce an executable, this
25 // file does not by itself cause the resulting executable to be covered by
26 // the GNU General Public License. This exception does not however
27 // invalidate any other reasons why the executable file might be covered by
28 // the GNU General Public License.
31 // ISO C++ 14882: 27.6.1 Input streams
35 * This is a Standard C++ Library header. You should @c #include this header
36 * in your programs, rather than any of the "st[dl]_*.h" implementation files.
40 #define _CPP_ISTREAM 1
42 #pragma GCC system_header
45 #include <limits> // For numeric_limits
49 // [27.6.1.1] Template class basic_istream
51 * @brief Controlling input.
53 * This is the base class for all input streams. It provides text
54 * formatting of all builtin types, and communicates with any class
55 * derived from basic_streambuf to do the actual input.
57 template<typename _CharT
, typename _Traits
>
58 class basic_istream
: virtual public basic_ios
<_CharT
, _Traits
>
61 // Types (inherited from basic_ios (27.4.4)):
62 typedef _CharT char_type
;
63 typedef typename
_Traits::int_type int_type
;
64 typedef typename
_Traits::pos_type pos_type
;
65 typedef typename
_Traits::off_type off_type
;
66 typedef _Traits traits_type
;
68 // Non-standard Types:
69 typedef basic_streambuf
<_CharT
, _Traits
> __streambuf_type
;
70 typedef basic_ios
<_CharT
, _Traits
> __ios_type
;
71 typedef basic_istream
<_CharT
, _Traits
> __istream_type
;
72 typedef istreambuf_iterator
<_CharT
, _Traits
> __istreambuf_iter
;
73 typedef num_get
<_CharT
, __istreambuf_iter
> __numget_type
;
74 typedef ctype
<_CharT
> __ctype_type
;
80 * The number of characters extracted in the previous unformatted
81 * function; see gcount().
87 // [27.6.1.1.1] constructor/destructor
89 * @brief Base constructor.
91 * This ctor is almost never called by the user directly, rather from
92 * derived classes' initialization lists, which pass a pointer to
93 * their own stream buffer.
96 basic_istream(__streambuf_type
* __sb
)
99 _M_gcount
= streamsize(0);
103 * @brief Base destructor.
105 * This does very little apart from providing a virtual base dtor.
109 { _M_gcount
= streamsize(0); }
111 // [27.6.1.1.2] prefix/suffix
115 // [27.6.1.2] formatted input
116 // [27.6.1.2.3] basic_istream::operator>>
119 * @brief Interface for manipulators.
121 * Manuipulators such as @c std::ws and @c std::dec use these
122 * functions in constructs like "std::cin >> std::ws". For more
123 * information, see the iomanip header.
126 operator>>(__istream_type
& (*__pf
)(__istream_type
&));
129 operator>>(__ios_type
& (*__pf
)(__ios_type
&));
132 operator>>(ios_base
& (*__pf
)(ios_base
&));
135 // [27.6.1.2.2] arithmetic extractors
137 * @name Arithmetic Extractors
139 * All the @c operator>> functions (aka <em>formatted input
140 * functions</em>) have some common behavior. Each starts by
141 * constructing a temporary object of type std::basic_istream::sentry
142 * with the second argument (noskipws) set to false. This has several
143 * effects, concluding with the setting of a status flag; see the
144 * sentry documentation for more.
146 * If the sentry status is good, the function tries to extract
147 * whatever data is appropriate for the type of the argument.
149 * If an exception is thrown during extraction, ios_base::badbit
150 * will be turned on in the stream's error state without causing an
151 * ios_base::failure to be thrown. The original exception will then
156 * @brief Basic arithmetic extractors
157 * @param A variable of builtin type.
158 * @return @c *this if successful
160 * These functions use the stream's current locale (specifically, the
161 * @c num_get facet) to parse the input data.
164 operator>>(bool& __n
);
167 operator>>(short& __n
);
170 operator>>(unsigned short& __n
);
173 operator>>(int& __n
);
176 operator>>(unsigned int& __n
);
179 operator>>(long& __n
);
182 operator>>(unsigned long& __n
);
184 #ifdef _GLIBCPP_USE_LONG_LONG
186 operator>>(long long& __n
);
189 operator>>(unsigned long long& __n
);
193 operator>>(float& __f
);
196 operator>>(double& __f
);
199 operator>>(long double& __f
);
202 operator>>(void*& __p
);
205 * @brief Extracting into another streambuf.
206 * @param sb A pointer to a streambuf
208 * This function behaves like one of the basic arithmetic extractors,
209 * in that it also constructs a sentry onject and has the same error
212 * If @a sb is NULL, the stream will set failbit in its error state.
214 * Characters are extracted from this stream and inserted into the
215 * @a sb streambuf until one of the following occurs:
217 * - the input stream reaches end-of-file,
218 * - insertion into the output buffer fails (in this case, the
219 * character that would have been inserted is not extracted), or
220 * - an exception occurs (and in this case is caught)
222 * If the function inserts no characters, failbit is set.
225 operator>>(__streambuf_type
* __sb
);
228 // [27.6.1.3] unformatted input
230 * @brief Character counting
231 * @return The number of characters extracted by the previous
232 * unformatted input function dispatched for this stream.
236 { return _M_gcount
; }
239 * @name Unformatted Input Functions
241 * All the unformatted input functions have some common behavior.
242 * Each starts by constructing a temporary object of type
243 * std::basic_istream::sentry with the second argument (noskipws)
244 * set to true. This has several effects, concluding with the
245 * setting of a status flag; see the sentry documentation for more.
247 * If the sentry status is good, the function tries to extract
248 * whatever data is appropriate for the type of the argument.
250 * The number of characters extracted is stored for later retrieval
253 * If an exception is thrown during extraction, ios_base::badbit
254 * will be turned on in the stream's error state without causing an
255 * ios_base::failure to be thrown. The original exception will then
260 * @brief Simple extraction.
261 * @return A character, or eof().
263 * Tries to extract a character. If none are available, sets failbit
264 * and returns traits::eof().
270 * @brief Simple extraction.
271 * @param c The character in which to store data.
274 * Tries to extract a character and store it in @a c. If none are
275 * available, sets failbit and returns traits::eof().
277 * @note This function is not overloaded on signed char and
284 * @brief Simple multiple-character extraction.
285 * @param s Pointer to an array.
286 * @param n Maximum number of characters to store in @a s.
287 * @param delim A "stop" character.
290 * Characters are extracted and stored into @a s until one of the
293 * - @c n-1 characters are stored
294 * - the input sequence reaches EOF
295 * - the next character equals @a delim, in which case the character
298 * If no characters are stored, failbit is set in the stream's error
301 * In any case, a null character is stored into the next location in
304 * @note This function is not overloaded on signed char and
308 get(char_type
* __s
, streamsize __n
, char_type __delim
);
311 * @brief Simple multiple-character extraction.
312 * @param s Pointer to an array.
313 * @param n Maximum number of characters to store in @a s.
316 * Returns @c get(s,n,widen('\n')).
318 inline __istream_type
&
319 get(char_type
* __s
, streamsize __n
)
320 { return this->get(__s
, __n
, this->widen('\n')); }
323 * @brief Extraction into another streambuf.
324 * @param sb A streambuf in which to store data.
325 * @param delim A "stop" character.
328 * Characters are extracted and inserted into @a sb until one of the
331 * - the input sequence reaches EOF
332 * - insertion into the output buffer fails (in this case, the
333 * character that would have been inserted is not extracted)
334 * - the next character equals @a delim (in this case, the character
336 * - an exception occurs (and in this case is caught)
338 * If no characters are stored, failbit is set in the stream's error
342 get(__streambuf_type
& __sb
, char_type __delim
);
345 * @brief Extraction into another streambuf.
346 * @param sb A streambuf in which to store data.
349 * Returns @c get(sb,widen('\n')).
351 inline __istream_type
&
352 get(__streambuf_type
& __sb
)
353 { return this->get(__sb
, this->widen('\n')); }
356 * @brief String extraction.
357 * @param s A character array in which to store the data.
358 * @param n Maximum number of characters to extract.
359 * @param delim A "stop" character.
362 * Extracts and stores characters into @a s until one of the
363 * following happens. Note that these criteria are required to be
364 * tested in the order listed here, to allow an input line to exactly
365 * fill the @a s array without setting failbit.
367 * -# the input sequence reaches end-of-file, in which case eofbit
368 * is set in the stream error state
369 * -# the next character equals @c delim, in which case the character
370 * is extracted (and therefore counted in @c gcount()) but not stored
371 * -# @c n-1 characters are stored, in which case failbit is set
372 * in the stream error state
374 * If no characters are extracted, failbit is set. (An empty line of
375 * input should therefore not cause failbit to be set.)
377 * In any case, a null character is stored in the next location in
381 getline(char_type
* __s
, streamsize __n
, char_type __delim
);
384 * @brief String extraction.
385 * @param s A character array in which to store the data.
386 * @param n Maximum number of characters to extract.
389 * Returns @c getline(s,n,widen('\n')).
391 inline __istream_type
&
392 getline(char_type
* __s
, streamsize __n
)
393 { return this->getline(__s
, __n
, this->widen('\n')); }
396 * @brief Discarding characters
397 * @param n Number of characters to discard.
398 * @param delim A "stop" character.
401 * Extracts characters and throws them away until one of the
403 * - if @a n @c != @c std::numeric_limits<int>::max(), @a n
404 * characters are extracted
405 * - the input sequence reaches end-of-file
406 * - the next character equals @a delim (in this case, the character
407 * is extracted); note that this condition will never occur if
408 * @a delim equals @c traits::eof().
411 ignore(streamsize __n
= 1, int_type __delim
= traits_type::eof());
414 * @brief Looking ahead in the stream
415 * @return The next character, or eof().
417 * If, after constructing the sentry object, @c good() is false,
418 * returns @c traits::eof(). Otherwise reads but does not extract
419 * the next input character.
425 * @brief Extraction without delimiters.
426 * @param s A character array.
427 * @param n Maximum number of characters to store.
430 * If the stream state is @c good(), extracts characters and stores
431 * them into @a s until one of the following happens:
432 * - @a n characters are stored
433 * - the input sequence reaches end-of-file, in which case the error
434 * state is set to @c failbit|eofbit.
436 * @note This function is not overloaded on signed char and
440 read(char_type
* __s
, streamsize __n
);
443 * @brief Extraction until the buffer is exhausted, but no more.
444 * @param s A character array.
445 * @param n Maximum number of characters to store.
446 * @return The number of characters extracted.
448 * Extracts characters and stores them into @a s depending on the
449 * number of characters remaining in the streambuf's buffer,
450 * @c rdbuf()->in_avail(), called @c A here:
451 * - if @c A @c == @c -1, sets eofbit and extracts no characters
452 * - if @c A @c == @c 0, extracts no characters
453 * - if @c A @c > @c 0, extracts @c min(A,n)
455 * The goal is to empty the current buffer, and to not request any
456 * more from the external input sequence controlled by the streambuf.
459 readsome(char_type
* __s
, streamsize __n
);
462 * @brief Unextracting a single character.
463 * @param c The character to push back into the input stream.
466 * If @c rdbuf() is not null, calls @c rdbuf()->sputbackc(c).
468 * If @c rdbuf() is null or if @c sputbackc() fails, sets badbit in
471 * @note Since no characters are extracted, the next call to
472 * @c gcount() will return 0, as required by DR 60.
475 * FIXME We don't comply with DR 60 here, _M_gcount is untouched.
479 putback(char_type __c
);
482 * @brief Unextracting the previous character.
485 * If @c rdbuf() is not null, calls @c rdbuf()->sungetc(c).
487 * If @c rdbuf() is null or if @c sungetc() fails, sets badbit in
490 * @note Since no characters are extracted, the next call to
491 * @c gcount() will return 0, as required by DR 60.
497 * @brief Synchronizing the stream buffer.
498 * @return 0 on success, -1 on failure
500 * If @c rdbuf() is a null pointer, returns -1.
502 * Otherwise, calls @c rdbuf()->pubsync(), and if that returns -1,
503 * sets badbit and returns -1.
505 * Otherwise, returns 0.
507 * @note This function does not count the number of characters
508 * extracted, if any, and therefore does not affect the next
509 * call to @c gcount().
511 * FIXME We don't comply with DR 60 here, _M_gcount is zeroed.
518 * @brief Getting the current read position.
519 * @return A file position object.
521 * If @c fail() is not false, returns @c pos_type(-1) to indicate
522 * failure. Otherwise returns @c rdbuf()->pubseekoff(0,cur,in).
524 * @note This function does not count the number of characters
525 * extracted, if any, and therefore does not affect the next
526 * call to @c gcount().
532 * @brief Changing the current read position.
533 * @param pos A file position object.
536 * If @c fail() is not true, calls @c rdbuf()->pubseekpos(pos). If
537 * that function fails, sets failbit.
539 * @note This function does not count the number of characters
540 * extracted, if any, and therefore does not affect the next
541 * call to @c gcount().
543 * FIXME We don't comply with DR 60 here, _M_gcount is zeroed.
550 * @brief Changing the current read position.
551 * @param off A file offset object.
552 * @param dir The direction in which to seek.
555 * If @c fail() is not true, calls @c rdbuf()->pubseekoff(off,dir).
556 * If that function fails, sets failbit.
558 * @note This function does not count the number of characters
559 * extracted, if any, and therefore does not affect the next
560 * call to @c gcount().
562 * FIXME We don't comply with DR 60 here, _M_gcount is zeroed.
566 seekg(off_type
, ios_base::seekdir
);
571 * @brief Performs setup work for input streams.
573 * Objects of this class are created before all of the standard
574 * extractors are run. It is responsible for "exception-safe prefix and
575 * suffix operations," although only prefix actions are currently required
576 * by the standard. Additional actions may be added by the
577 * implementation, and we list them in
578 * http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/howto.html#5
579 * under [27.6] notes.
581 template<typename _CharT
, typename _Traits
>
582 class basic_istream
<_CharT
, _Traits
>::sentry
585 /// Easy access to dependant types.
586 typedef _Traits traits_type
;
587 typedef basic_streambuf
<_CharT
, _Traits
> __streambuf_type
;
588 typedef basic_istream
<_CharT
, _Traits
> __istream_type
;
589 typedef typename
__istream_type::__ctype_type __ctype_type
;
590 typedef typename
_Traits::int_type __int_type
;
593 * @brief The constructor performs all the work.
594 * @param is The input stream to guard.
595 * @param noskipws Whether to consume whitespace or not.
597 * If the stream state is good (@a is.good() is true), then the
598 * following actions are performed, otherwise the sentry state is
599 * false ("not okay") and failbit is set in the stream state.
601 * The sentry's preparatory actions are:
603 * -# if the stream is tied to an output stream, @c is.tie()->flush()
604 * is called to synchronize the output sequence
605 * -# if @a noskipws is false, and @c ios_base::skipws is set in
606 * @c is.flags(), the sentry extracts and discards whitespace
607 * characters from the stream. The currently imbued locale is
608 * used to determine whether each character is whitespace.
610 * If the stream state is still good, then the sentry state becomes
614 sentry(basic_istream
<_CharT
, _Traits
>& __is
, bool __noskipws
= false);
617 * @brief Quick status checking.
618 * @return The sentry state.
620 * For ease of use, sentries may be converted to booleans. The
621 * return value is that of the sentry state (true == okay).
623 operator bool() { return _M_ok
; }
629 // [27.6.1.2.3] character extraction templates
632 * @brief Character extractors
633 * @param in An input stream.
634 * @param c A character reference.
637 * Behaves like one of the formatted arithmetic extractors described in
638 * std::basic_istream. After constructing a sentry object with good
639 * status, this function extracts a character (if one is available) and
640 * stores it in @a c. Otherwise, sets failbit in the input stream.
642 template<typename _CharT
, typename _Traits
>
643 basic_istream
<_CharT
, _Traits
>&
644 operator>>(basic_istream
<_CharT
, _Traits
>& __in
, _CharT
& __c
);
646 template<class _Traits
>
647 basic_istream
<char, _Traits
>&
648 operator>>(basic_istream
<char, _Traits
>& __in
, unsigned char& __c
)
649 { return (__in
>> reinterpret_cast<char&>(__c
)); }
651 template<class _Traits
>
652 basic_istream
<char, _Traits
>&
653 operator>>(basic_istream
<char, _Traits
>& __in
, signed char& __c
)
654 { return (__in
>> reinterpret_cast<char&>(__c
)); }
659 * @brief Character string extractors
660 * @param in An input stream.
661 * @param s A pointer to a character array.
664 * Behaves like one of the formatted arithmetic extractors described in
665 * std::basic_istream. After constructing a sentry object with good
666 * status, this function extracts up to @c n characters and stores them
667 * into the array starting at @a s. @c n is defined as:
669 * - if @c width() is greater than zero, @c n is width()
670 * - otherwise @c n is "the number of elements of the largest array of
671 * @c char_type that can store a terminating @c eos." [27.6.1.2.3]/6
673 * Characters are extracted and stored until one of the following happens:
674 * - @c n-1 characters are stored
676 * - the next character is whitespace according to the current locale
677 * - the next character is a null byte (i.e., @c charT() )
679 * @c width(0) is then called for the input stream.
681 * If no characters are extracted, sets failbit.
683 template<typename _CharT
, typename _Traits
>
684 basic_istream
<_CharT
, _Traits
>&
685 operator>>(basic_istream
<_CharT
, _Traits
>& __in
, _CharT
* __s
);
687 template<class _Traits
>
688 basic_istream
<char,_Traits
>&
689 operator>>(basic_istream
<char,_Traits
>& __in
, unsigned char* __s
)
690 { return (__in
>> reinterpret_cast<char*>(__s
)); }
692 template<class _Traits
>
693 basic_istream
<char,_Traits
>&
694 operator>>(basic_istream
<char,_Traits
>& __in
, signed char* __s
)
695 { return (__in
>> reinterpret_cast<char*>(__s
)); }
698 // 27.6.1.5 Template class basic_iostream
700 * @brief Merging istream and ostream capabilities.
702 * This class multiply inherits from the input and output stream classes
703 * simply to provide a single interface.
705 template<typename _CharT
, typename _Traits
>
707 : public basic_istream
<_CharT
, _Traits
>,
708 public basic_ostream
<_CharT
, _Traits
>
711 #ifdef _GLIBCPP_RESOLVE_LIB_DEFECTS
712 // 271. basic_iostream missing typedefs
713 // Types (inherited):
714 typedef _CharT char_type
;
715 typedef typename
_Traits::int_type int_type
;
716 typedef typename
_Traits::pos_type pos_type
;
717 typedef typename
_Traits::off_type off_type
;
718 typedef _Traits traits_type
;
721 // Non-standard Types:
722 typedef basic_istream
<_CharT
, _Traits
> __istream_type
;
723 typedef basic_ostream
<_CharT
, _Traits
> __ostream_type
;
726 * @brief Constructor does nothing.
728 * Both of the parent classes are initialized with the same
729 * streambuf pointer passed to this constructor.
732 basic_iostream(basic_streambuf
<_CharT
, _Traits
>* __sb
)
733 : __istream_type(__sb
), __ostream_type(__sb
)
737 * @brief Destructor does nothing.
740 ~basic_iostream() { }
743 // [27.6.1.4] standard basic_istream manipulators
745 * @brief Quick and easy way to eat whitespace
747 * This manipulator extracts whitespace characters, stopping when the
748 * next character is non-whitespace, or when the input sequence is empty.
749 * If the sequence is empty, @c eofbit is set in the stream, but not
752 * The current locale is used to distinguish whitespace characters.
758 * std::cin >> std::ws >> mc;
760 * will skip leading whitespace before calling operator>> on cin and your
761 * object. Note that the same effect can be achieved by creating a
762 * std::basic_istream::sentry inside your definition of operator>>.
764 template<typename _CharT
, typename _Traits
>
765 basic_istream
<_CharT
, _Traits
>&
766 ws(basic_istream
<_CharT
, _Traits
>& __is
);
769 #ifdef _GLIBCPP_NO_TEMPLATE_EXPORT
772 #ifdef _GLIBCPP_FULLY_COMPLIANT_HEADERS
773 # include <bits/istream.tcc>
776 #endif /* _CPP_ISTREAM */