1 // Iostreams base classes -*- C++ -*-
3 // Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
5 // Free Software Foundation, Inc.
7 // This file is part of the GNU ISO C++ Library. This library is free
8 // software; you can redistribute it and/or modify it under the
9 // terms of the GNU General Public License as published by the
10 // Free Software Foundation; either version 2, or (at your option)
13 // This library is distributed in the hope that it will be useful,
14 // but WITHOUT ANY WARRANTY; without even the implied warranty of
15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 // GNU General Public License for more details.
18 // You should have received a copy of the GNU General Public License along
19 // with this library; see the file COPYING. If not, write to the Free
20 // Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
23 // As a special exception, you may use this file as part of a free software
24 // library without restriction. Specifically, if other files instantiate
25 // templates or use macros or inline functions from this file, or you compile
26 // this file and link it with other files to produce an executable, this
27 // file does not by itself cause the resulting executable to be covered by
28 // the GNU General Public License. This exception does not however
29 // invalidate any other reasons why the executable file might be covered by
30 // the GNU General Public License.
33 * This is an internal header file, included by other library headers.
34 * You should not attempt to use it directly.
38 // ISO C++ 14882: 27.4 Iostreams base classes
44 #pragma GCC system_header
46 #include <ext/atomicity.h>
47 #include <bits/localefwd.h>
48 #include <bits/locale_classes.h>
49 #include <cstdio> // For SEEK_CUR, SEEK_END
51 _GLIBCXX_BEGIN_NAMESPACE(std
)
53 // The following definitions of bitmask types are enums, not ints,
54 // as permitted (but not required) in the standard, in order to provide
55 // better type safety in iostream calls. A side effect is that
56 // expressions involving them are no longer compile-time constants.
59 _S_boolalpha
= 1L << 0,
63 _S_internal
= 1L << 4,
67 _S_scientific
= 1L << 8,
68 _S_showbase
= 1L << 9,
69 _S_showpoint
= 1L << 10,
70 _S_showpos
= 1L << 11,
72 _S_unitbuf
= 1L << 13,
73 _S_uppercase
= 1L << 14,
74 _S_adjustfield
= _S_left
| _S_right
| _S_internal
,
75 _S_basefield
= _S_dec
| _S_oct
| _S_hex
,
76 _S_floatfield
= _S_scientific
| _S_fixed
,
77 _S_ios_fmtflags_end
= 1L << 16
81 operator&(_Ios_Fmtflags __a
, _Ios_Fmtflags __b
)
82 { return _Ios_Fmtflags(static_cast<int>(__a
) & static_cast<int>(__b
)); }
85 operator|(_Ios_Fmtflags __a
, _Ios_Fmtflags __b
)
86 { return _Ios_Fmtflags(static_cast<int>(__a
) | static_cast<int>(__b
)); }
89 operator^(_Ios_Fmtflags __a
, _Ios_Fmtflags __b
)
90 { return _Ios_Fmtflags(static_cast<int>(__a
) ^ static_cast<int>(__b
)); }
93 operator|=(_Ios_Fmtflags
& __a
, _Ios_Fmtflags __b
)
94 { return __a
= __a
| __b
; }
97 operator&=(_Ios_Fmtflags
& __a
, _Ios_Fmtflags __b
)
98 { return __a
= __a
& __b
; }
100 inline _Ios_Fmtflags
&
101 operator^=(_Ios_Fmtflags
& __a
, _Ios_Fmtflags __b
)
102 { return __a
= __a
^ __b
; }
105 operator~(_Ios_Fmtflags __a
)
106 { return _Ios_Fmtflags(~static_cast<int>(__a
)); }
117 _S_ios_openmode_end
= 1L << 16
121 operator&(_Ios_Openmode __a
, _Ios_Openmode __b
)
122 { return _Ios_Openmode(static_cast<int>(__a
) & static_cast<int>(__b
)); }
125 operator|(_Ios_Openmode __a
, _Ios_Openmode __b
)
126 { return _Ios_Openmode(static_cast<int>(__a
) | static_cast<int>(__b
)); }
129 operator^(_Ios_Openmode __a
, _Ios_Openmode __b
)
130 { return _Ios_Openmode(static_cast<int>(__a
) ^ static_cast<int>(__b
)); }
132 inline _Ios_Openmode
&
133 operator|=(_Ios_Openmode
& __a
, _Ios_Openmode __b
)
134 { return __a
= __a
| __b
; }
136 inline _Ios_Openmode
&
137 operator&=(_Ios_Openmode
& __a
, _Ios_Openmode __b
)
138 { return __a
= __a
& __b
; }
140 inline _Ios_Openmode
&
141 operator^=(_Ios_Openmode
& __a
, _Ios_Openmode __b
)
142 { return __a
= __a
^ __b
; }
145 operator~(_Ios_Openmode __a
)
146 { return _Ios_Openmode(~static_cast<int>(__a
)); }
154 _S_failbit
= 1L << 2,
155 _S_ios_iostate_end
= 1L << 16
159 operator&(_Ios_Iostate __a
, _Ios_Iostate __b
)
160 { return _Ios_Iostate(static_cast<int>(__a
) & static_cast<int>(__b
)); }
163 operator|(_Ios_Iostate __a
, _Ios_Iostate __b
)
164 { return _Ios_Iostate(static_cast<int>(__a
) | static_cast<int>(__b
)); }
167 operator^(_Ios_Iostate __a
, _Ios_Iostate __b
)
168 { return _Ios_Iostate(static_cast<int>(__a
) ^ static_cast<int>(__b
)); }
171 operator|=(_Ios_Iostate
& __a
, _Ios_Iostate __b
)
172 { return __a
= __a
| __b
; }
175 operator&=(_Ios_Iostate
& __a
, _Ios_Iostate __b
)
176 { return __a
= __a
& __b
; }
179 operator^=(_Ios_Iostate
& __a
, _Ios_Iostate __b
)
180 { return __a
= __a
^ __b
; }
183 operator~(_Ios_Iostate __a
)
184 { return _Ios_Iostate(~static_cast<int>(__a
)); }
191 _S_ios_seekdir_end
= 1L << 16
194 // 27.4.2 Class ios_base
196 * @brief The base of the I/O class hierarchy.
198 * This class defines everything that can be defined about I/O that does
199 * not depend on the type of characters being input or output. Most
200 * people will only see @c ios_base when they need to specify the full
201 * name of the various I/O flags (e.g., the openmodes).
207 // 27.4.2.1.1 Class ios_base::failure
208 /// These are thrown to indicate problems. Doc me.
209 class failure
: public exception
212 // _GLIBCXX_RESOLVE_LIB_DEFECTS
213 // 48. Use of non-existent exception constructor
215 failure(const string
& __str
) throw();
217 // This declaration is not useless:
218 // http://gcc.gnu.org/onlinedocs/gcc-4.3.2/gcc/Vague-Linkage.html
223 what() const throw();
229 // 27.4.2.1.2 Type ios_base::fmtflags
231 * @brief This is a bitmask type.
233 * @c "_Ios_Fmtflags" is implementation-defined, but it is valid to
234 * perform bitwise operations on these values and expect the Right
235 * Thing to happen. Defined objects of type fmtflags are:
255 typedef _Ios_Fmtflags fmtflags
;
257 /// Insert/extract @c bool in alphabetic rather than numeric format.
258 static const fmtflags boolalpha
= _S_boolalpha
;
260 /// Converts integer input or generates integer output in decimal base.
261 static const fmtflags dec
= _S_dec
;
263 /// Generate floating-point output in fixed-point notation.
264 static const fmtflags fixed
= _S_fixed
;
266 /// Converts integer input or generates integer output in hexadecimal base.
267 static const fmtflags hex
= _S_hex
;
269 /// Adds fill characters at a designated internal point in certain
270 /// generated output, or identical to @c right if no such point is
272 static const fmtflags internal
= _S_internal
;
274 /// Adds fill characters on the right (final positions) of certain
275 /// generated output. (I.e., the thing you print is flush left.)
276 static const fmtflags left
= _S_left
;
278 /// Converts integer input or generates integer output in octal base.
279 static const fmtflags oct
= _S_oct
;
281 /// Adds fill characters on the left (initial positions) of certain
282 /// generated output. (I.e., the thing you print is flush right.)
283 static const fmtflags right
= _S_right
;
285 /// Generates floating-point output in scientific notation.
286 static const fmtflags scientific
= _S_scientific
;
288 /// Generates a prefix indicating the numeric base of generated integer
290 static const fmtflags showbase
= _S_showbase
;
292 /// Generates a decimal-point character unconditionally in generated
293 /// floating-point output.
294 static const fmtflags showpoint
= _S_showpoint
;
296 /// Generates a + sign in non-negative generated numeric output.
297 static const fmtflags showpos
= _S_showpos
;
299 /// Skips leading white space before certain input operations.
300 static const fmtflags skipws
= _S_skipws
;
302 /// Flushes output after each output operation.
303 static const fmtflags unitbuf
= _S_unitbuf
;
305 /// Replaces certain lowercase letters with their uppercase equivalents
306 /// in generated output.
307 static const fmtflags uppercase
= _S_uppercase
;
309 /// A mask of left|right|internal. Useful for the 2-arg form of @c setf.
310 static const fmtflags adjustfield
= _S_adjustfield
;
312 /// A mask of dec|oct|hex. Useful for the 2-arg form of @c setf.
313 static const fmtflags basefield
= _S_basefield
;
315 /// A mask of scientific|fixed. Useful for the 2-arg form of @c setf.
316 static const fmtflags floatfield
= _S_floatfield
;
318 // 27.4.2.1.3 Type ios_base::iostate
320 * @brief This is a bitmask type.
322 * @c "_Ios_Iostate" is implementation-defined, but it is valid to
323 * perform bitwise operations on these values and expect the Right
324 * Thing to happen. Defined objects of type iostate are:
330 typedef _Ios_Iostate iostate
;
332 /// Indicates a loss of integrity in an input or output sequence (such
333 /// as an irrecoverable read error from a file).
334 static const iostate badbit
= _S_badbit
;
336 /// Indicates that an input operation reached the end of an input sequence.
337 static const iostate eofbit
= _S_eofbit
;
339 /// Indicates that an input operation failed to read the expected
340 /// characters, or that an output operation failed to generate the
341 /// desired characters.
342 static const iostate failbit
= _S_failbit
;
344 /// Indicates all is well.
345 static const iostate goodbit
= _S_goodbit
;
347 // 27.4.2.1.4 Type ios_base::openmode
349 * @brief This is a bitmask type.
351 * @c "_Ios_Openmode" is implementation-defined, but it is valid to
352 * perform bitwise operations on these values and expect the Right
353 * Thing to happen. Defined objects of type openmode are:
361 typedef _Ios_Openmode openmode
;
363 /// Seek to end before each write.
364 static const openmode app
= _S_app
;
366 /// Open and seek to end immediately after opening.
367 static const openmode ate
= _S_ate
;
369 /// Perform input and output in binary mode (as opposed to text mode).
370 /// This is probably not what you think it is; see
371 /// http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch27s02.html
372 static const openmode binary
= _S_bin
;
374 /// Open for input. Default for @c ifstream and fstream.
375 static const openmode in
= _S_in
;
377 /// Open for output. Default for @c ofstream and fstream.
378 static const openmode out
= _S_out
;
380 /// Open for input. Default for @c ofstream.
381 static const openmode trunc
= _S_trunc
;
383 // 27.4.2.1.5 Type ios_base::seekdir
385 * @brief This is an enumerated type.
387 * @c "_Ios_Seekdir" is implementation-defined. Defined values
388 * of type seekdir are:
390 * - cur, equivalent to @c SEEK_CUR in the C standard library.
391 * - end, equivalent to @c SEEK_END in the C standard library.
393 typedef _Ios_Seekdir seekdir
;
395 /// Request a seek relative to the beginning of the stream.
396 static const seekdir beg
= _S_beg
;
398 /// Request a seek relative to the current position within the sequence.
399 static const seekdir cur
= _S_cur
;
401 /// Request a seek relative to the current end of the sequence.
402 static const seekdir end
= _S_end
;
405 typedef int io_state
;
406 typedef int open_mode
;
407 typedef int seek_dir
;
409 typedef std::streampos streampos
;
410 typedef std::streamoff streamoff
;
414 * @brief The set of events that may be passed to an event callback.
416 * erase_event is used during ~ios() and copyfmt(). imbue_event is used
417 * during imbue(). copyfmt_event is used during copyfmt().
427 * @brief The type of an event callback function.
428 * @param event One of the members of the event enum.
429 * @param ios_base Reference to the ios_base object.
430 * @param int The integer provided when the callback was registered.
432 * Event callbacks are user defined functions that get called during
433 * several ios_base and basic_ios functions, specifically imbue(),
434 * copyfmt(), and ~ios().
436 typedef void (*event_callback
) (event
, ios_base
&, int);
439 * @brief Add the callback __fn with parameter __index.
440 * @param __fn The function to add.
441 * @param __index The integer to pass to the function when invoked.
443 * Registers a function as an event callback with an integer parameter to
444 * be passed to the function when invoked. Multiple copies of the
445 * function are allowed. If there are multiple callbacks, they are
446 * invoked in the order they were registered.
449 register_callback(event_callback __fn
, int __index
);
454 * ios_base data members (doc me)
456 streamsize _M_precision
;
459 iostate _M_exception
;
460 iostate _M_streambuf_state
;
463 // 27.4.2.6 Members for callbacks
464 // 27.4.2.6 ios_base callbacks
465 struct _Callback_list
468 _Callback_list
* _M_next
;
469 ios_base::event_callback _M_fn
;
471 _Atomic_word _M_refcount
; // 0 means one reference.
473 _Callback_list(ios_base::event_callback __fn
, int __index
,
474 _Callback_list
* __cb
)
475 : _M_next(__cb
), _M_fn(__fn
), _M_index(__index
), _M_refcount(0) { }
478 _M_add_reference() { __gnu_cxx::__atomic_add_dispatch(&_M_refcount
, 1); }
480 // 0 => OK to delete.
482 _M_remove_reference()
483 { return __gnu_cxx::__exchange_and_add_dispatch(&_M_refcount
, -1); }
486 _Callback_list
* _M_callbacks
;
489 _M_call_callbacks(event __ev
) throw();
492 _M_dispose_callbacks(void);
494 // 27.4.2.5 Members for iword/pword storage
499 _Words() : _M_pword(0), _M_iword(0) { }
502 // Only for failed iword/pword calls.
505 // Guaranteed storage.
506 // The first 5 iword and pword slots are reserved for internal use.
507 enum { _S_local_word_size
= 8 };
508 _Words _M_local_word
[_S_local_word_size
];
510 // Allocated storage.
515 _M_grow_words(int __index
, bool __iword
);
517 // Members for locale and locale caching.
518 locale _M_ios_locale
;
525 // 27.4.2.1.6 Class ios_base::Init
526 // Used to initialize standard streams. In theory, g++ could use
527 // -finit-priority to order this stuff correctly without going
528 // through these machinations.
531 friend class ios_base
;
537 static _Atomic_word _S_refcount
;
538 static bool _S_synced_with_stdio
;
541 // [27.4.2.2] fmtflags state functions
543 * @brief Access to format flags.
544 * @return The format control flags for both input and output.
551 * @brief Setting new format flags all at once.
552 * @param fmtfl The new flags to set.
553 * @return The previous format control flags.
555 * This function overwrites all the format flags with @a fmtfl.
558 flags(fmtflags __fmtfl
)
560 fmtflags __old
= _M_flags
;
566 * @brief Setting new format flags.
567 * @param fmtfl Additional flags to set.
568 * @return The previous format control flags.
570 * This function sets additional flags in format control. Flags that
571 * were previously set remain set.
574 setf(fmtflags __fmtfl
)
576 fmtflags __old
= _M_flags
;
582 * @brief Setting new format flags.
583 * @param fmtfl Additional flags to set.
584 * @param mask The flags mask for @a fmtfl.
585 * @return The previous format control flags.
587 * This function clears @a mask in the format flags, then sets
588 * @a fmtfl @c & @a mask. An example mask is @c ios_base::adjustfield.
591 setf(fmtflags __fmtfl
, fmtflags __mask
)
593 fmtflags __old
= _M_flags
;
595 _M_flags
|= (__fmtfl
& __mask
);
600 * @brief Clearing format flags.
601 * @param mask The flags to unset.
603 * This function clears @a mask in the format flags.
606 unsetf(fmtflags __mask
)
607 { _M_flags
&= ~__mask
; }
610 * @brief Flags access.
611 * @return The precision to generate on certain output operations.
613 * Be careful if you try to give a definition of "precision" here; see
618 { return _M_precision
; }
621 * @brief Changing flags.
622 * @param prec The new precision value.
623 * @return The previous value of precision().
626 precision(streamsize __prec
)
628 streamsize __old
= _M_precision
;
629 _M_precision
= __prec
;
634 * @brief Flags access.
635 * @return The minimum field width to generate on output operations.
637 * "Minimum field width" refers to the number of characters.
644 * @brief Changing flags.
645 * @param wide The new width value.
646 * @return The previous value of width().
649 width(streamsize __wide
)
651 streamsize __old
= _M_width
;
656 // [27.4.2.4] ios_base static members
658 * @brief Interaction with the standard C I/O objects.
659 * @param sync Whether to synchronize or not.
660 * @return True if the standard streams were previously synchronized.
662 * The synchronization referred to is @e only that between the standard
663 * C facilities (e.g., stdout) and the standard C++ objects (e.g.,
664 * cout). User-declared streams are unaffected. See
665 * http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt11ch28s02.html
668 sync_with_stdio(bool __sync
= true);
670 // [27.4.2.3] ios_base locale functions
672 * @brief Setting a new locale.
673 * @param loc The new locale.
674 * @return The previous locale.
676 * Sets the new locale for this stream, and then invokes each callback
680 imbue(const locale
& __loc
);
683 * @brief Locale access
684 * @return A copy of the current locale.
686 * If @c imbue(loc) has previously been called, then this function
687 * returns @c loc. Otherwise, it returns a copy of @c std::locale(),
688 * the global C++ locale.
692 { return _M_ios_locale
; }
695 * @brief Locale access
696 * @return A reference to the current locale.
698 * Like getloc above, but returns a reference instead of
703 { return _M_ios_locale
; }
705 // [27.4.2.5] ios_base storage functions
707 * @brief Access to unique indices.
708 * @return An integer different from all previous calls.
710 * This function returns a unique integer every time it is called. It
711 * can be used for any purpose, but is primarily intended to be a unique
712 * index for the iword and pword functions. The expectation is that an
713 * application calls xalloc in order to obtain an index in the iword and
714 * pword arrays that can be used without fear of conflict.
716 * The implementation maintains a static variable that is incremented and
717 * returned on each invocation. xalloc is guaranteed to return an index
718 * that is safe to use in the iword and pword arrays.
724 * @brief Access to integer array.
725 * @param __ix Index into the array.
726 * @return A reference to an integer associated with the index.
728 * The iword function provides access to an array of integers that can be
729 * used for any purpose. The array grows as required to hold the
730 * supplied index. All integers in the array are initialized to 0.
732 * The implementation reserves several indices. You should use xalloc to
733 * obtain an index that is safe to use. Also note that since the array
734 * can grow dynamically, it is not safe to hold onto the reference.
739 _Words
& __word
= (__ix
< _M_word_size
)
740 ? _M_word
[__ix
] : _M_grow_words(__ix
, true);
741 return __word
._M_iword
;
745 * @brief Access to void pointer array.
746 * @param __ix Index into the array.
747 * @return A reference to a void* associated with the index.
749 * The pword function provides access to an array of pointers that can be
750 * used for any purpose. The array grows as required to hold the
751 * supplied index. All pointers in the array are initialized to 0.
753 * The implementation reserves several indices. You should use xalloc to
754 * obtain an index that is safe to use. Also note that since the array
755 * can grow dynamically, it is not safe to hold onto the reference.
760 _Words
& __word
= (__ix
< _M_word_size
)
761 ? _M_word
[__ix
] : _M_grow_words(__ix
, false);
762 return __word
._M_pword
;
767 * Invokes each callback with erase_event. Destroys local storage.
769 * Note that the ios_base object for the standard streams never gets
770 * destroyed. As a result, any callbacks registered with the standard
771 * streams will not get invoked with erase_event (unless copyfmt is
779 // _GLIBCXX_RESOLVE_LIB_DEFECTS
780 // 50. Copy constructor and assignment operator of ios_base
782 ios_base(const ios_base
&);
785 operator=(const ios_base
&);
788 // [27.4.5.1] fmtflags manipulators
789 /// Calls base.setf(ios_base::boolalpha).
791 boolalpha(ios_base
& __base
)
793 __base
.setf(ios_base::boolalpha
);
797 /// Calls base.unsetf(ios_base::boolalpha).
799 noboolalpha(ios_base
& __base
)
801 __base
.unsetf(ios_base::boolalpha
);
805 /// Calls base.setf(ios_base::showbase).
807 showbase(ios_base
& __base
)
809 __base
.setf(ios_base::showbase
);
813 /// Calls base.unsetf(ios_base::showbase).
815 noshowbase(ios_base
& __base
)
817 __base
.unsetf(ios_base::showbase
);
821 /// Calls base.setf(ios_base::showpoint).
823 showpoint(ios_base
& __base
)
825 __base
.setf(ios_base::showpoint
);
829 /// Calls base.unsetf(ios_base::showpoint).
831 noshowpoint(ios_base
& __base
)
833 __base
.unsetf(ios_base::showpoint
);
837 /// Calls base.setf(ios_base::showpos).
839 showpos(ios_base
& __base
)
841 __base
.setf(ios_base::showpos
);
845 /// Calls base.unsetf(ios_base::showpos).
847 noshowpos(ios_base
& __base
)
849 __base
.unsetf(ios_base::showpos
);
853 /// Calls base.setf(ios_base::skipws).
855 skipws(ios_base
& __base
)
857 __base
.setf(ios_base::skipws
);
861 /// Calls base.unsetf(ios_base::skipws).
863 noskipws(ios_base
& __base
)
865 __base
.unsetf(ios_base::skipws
);
869 /// Calls base.setf(ios_base::uppercase).
871 uppercase(ios_base
& __base
)
873 __base
.setf(ios_base::uppercase
);
877 /// Calls base.unsetf(ios_base::uppercase).
879 nouppercase(ios_base
& __base
)
881 __base
.unsetf(ios_base::uppercase
);
885 /// Calls base.setf(ios_base::unitbuf).
887 unitbuf(ios_base
& __base
)
889 __base
.setf(ios_base::unitbuf
);
893 /// Calls base.unsetf(ios_base::unitbuf).
895 nounitbuf(ios_base
& __base
)
897 __base
.unsetf(ios_base::unitbuf
);
901 // [27.4.5.2] adjustfield manipulators
902 /// Calls base.setf(ios_base::internal, ios_base::adjustfield).
904 internal(ios_base
& __base
)
906 __base
.setf(ios_base::internal
, ios_base::adjustfield
);
910 /// Calls base.setf(ios_base::left, ios_base::adjustfield).
912 left(ios_base
& __base
)
914 __base
.setf(ios_base::left
, ios_base::adjustfield
);
918 /// Calls base.setf(ios_base::right, ios_base::adjustfield).
920 right(ios_base
& __base
)
922 __base
.setf(ios_base::right
, ios_base::adjustfield
);
926 // [27.4.5.3] basefield manipulators
927 /// Calls base.setf(ios_base::dec, ios_base::basefield).
929 dec(ios_base
& __base
)
931 __base
.setf(ios_base::dec
, ios_base::basefield
);
935 /// Calls base.setf(ios_base::hex, ios_base::basefield).
937 hex(ios_base
& __base
)
939 __base
.setf(ios_base::hex
, ios_base::basefield
);
943 /// Calls base.setf(ios_base::oct, ios_base::basefield).
945 oct(ios_base
& __base
)
947 __base
.setf(ios_base::oct
, ios_base::basefield
);
951 // [27.4.5.4] floatfield manipulators
952 /// Calls base.setf(ios_base::fixed, ios_base::floatfield).
954 fixed(ios_base
& __base
)
956 __base
.setf(ios_base::fixed
, ios_base::floatfield
);
960 /// Calls base.setf(ios_base::scientific, ios_base::floatfield).
962 scientific(ios_base
& __base
)
964 __base
.setf(ios_base::scientific
, ios_base::floatfield
);
968 _GLIBCXX_END_NAMESPACE
970 #endif /* _IOS_BASE_H */