Name

ios_base class — Root class for I/O declarations

Synopsis

class ios_base{
public:
  class failure;
  typedef  . . .  fmtflags;
  typedef  . . .  iostate;
  typedef  . . .  io_state;
  typedef  . . .  openmode;
  typedef  . . .  open_mode;
  typedef  . . .  seekdir;
  typedef  . . .  seek_dir;
  typedef  . . .  streamoff;
  typedef  . . .  streampos;
  class Init;

  // Destructor
  virtual ~ios_base(  );
  // Formatting
  fmtflags flags(  ) const;
  fmtflags flags(fmtflags fmtfl);
  fmtflags setf(fmtflags fmtfl);
  fmtflags setf(fmtflags fmtfl, fmtflags mask);
  void unsetf(fmtflags mask);
  streamsize precision(  ) const;
  streamsize precision(streamsize prec);
  streamsize width(  ) const;
  streamsize width(streamsize wide);
  // Locales
  locale imbue(const locale& loc);
  locale getloc(  ) const;
  // Storage
  static int xalloc(  );
  long& iword(int index);
  void*& pword(int index);
  // Callbacks
  enum event { erase_event, imbue_event, copyfmt_event };
  typedef void (*event_callback)(event, ios_base&, int index);
  void register_callback(event_callback fn, int index);
  static bool sync_with_stdio(bool sync = true);
protected:
  ios_base(  );
private:
  ios_base(const ios_base&);
  ios_base& operator=(const ios_base&);
};

The ios_base class is the root class for all the I/O stream classes. It declares fundamental types that are used throughout the I/O library. It also has members to keep track of formatting for input and output, storing arbitrary information for derived classes, and registering functions to be called when something interesting happens to the stream object.

The io_state, open_mode, seek_dir, streamoff, and streampos types are deprecated and might not be included in a future revision of the C++ standard. The first three are integer types that are equivalent to iostate, openmode, and seekdir. (See their respective subsections later in this section for details.) The streamoff and streampos types have equivalent types at namespace scope. See streamoff later in this section and streampos in <iosfwd> for details.

The following are the member functions of ios_base:

ios_base

The default constructor is protected so you cannot accidentally declare an object of type ios_base. It does not initialize its members. That is left to the basic_ios::init function.

ios_base

The copy constructor is private and not defined so you cannot copy objects of type ios_base or its derived classes.

~ios_base

Calls every registered callback with the erase_event if the ios_base object has been properly initialized. See basic_ios::init.

ios_base& operator= (const ios_base&)

The assignment operator is private and not defined to prevent the assignment of ios_base objects or its derivatives.

fmtflags flags ( ) const, fmtflags flags (fmtflags fmtfl)

Returns the current format flags or sets the flags. When setting the flags, the previous flags are returned.

locale getloc ( ) const

Returns the stream's currently imbued locale.

locale imbue (const locale& loc)

Saves loc as the new locale and calls all registered callbacks with imbue_event. The new locale is stored before calling any callbacks, so if a callback function calls getloc, it gets the new locale.

long& iword (int index)

Returns a reference to a long integer that is stored in a private array, at index index. If iword has been called before with the same index, a reference to the array element is returned. Otherwise, the array is extended as needed so that index is a valid index, and the new entry is initialized to 0. A reference to the new element is returned.

The structure of the internal array is implementation-defined, and it might be a sparse array. The internal array grows as needed, and all prior values stored in the array are preserved, although the references might become invalid in any of the following situations:

If iword fails (perhaps because the internal array cannot grow), it returns a reference to a valid long& with a value that is initially 0. If the member function is called for an object whose class derives from basic_ios<>, badbit is set (which might throw ios_base::failure).

See the xalloc member function to learn how to obtain a suitable index.

streamsize precision ( ) const, streamsize precision (streamsize prec)

Returns or sets the precision (places after the decimal point) used to format floating-point numbers for output. When setting a new precision, the previous precision is returned.

void*& pword (int index)

Returns a reference to a void* that is stored in a private array, at index index. If pword has been called before with the same index, a reference to the array element is returned. Otherwise, the array is extended as needed so that index is a valid index, and the new entry is initialized to a null pointer. A reference to the new element is returned.

The structure of the internal array is implementation-defined, and it might be a sparse array. The internal array grows as needed, and all prior values stored in the array are preserved, although the references might become invalid in any of the following situations:

If pword fails (perhaps because the internal array cannot grow), it returns a reference to a valid void*& with a value that is initially 0. If the object derives from basic_ios<>, badbit is set (which might throw ios_base::failure).

See the xalloc member function to learn how to obtain a suitable index.

void register_callback (event_callback fn, int index)

Registers a function fn to be called when one of three events occurs for the ios_base object:

Each callback function is registered with an integer index. The index is passed to the callback function. Functions are called in the opposite order of registration. The callback function must not throw exceptions.

For example, suppose a program stores some debugging information with each stream. It allocates a struct and stores a pointer to the struct in the stream's pword array. When copyfmt is called, the debugging information should also be copied. Example 13-14 shows how to use callbacks to make sure the memory is managed properly.

fmtflags setf (fmtflags addflags)

Sets the addflags bits of the formatting flags. It is equivalent to calling flags(flags( ) | addflags).

fmtflags setf (fmtflags newflags, fmtflags mask)

Clears the mask bits from the formatting flags and then sets the newflags & mask bits. It is equivalent to calling flags((flags( ) & ~mask) | (newflags & mask)). The two-argument version of setf is most often used with multiple-choice flags (e.g., setf(ios_base::dec, ios_base::basefield)).

static bool sync_with_stdio (bool sync = true)

Determines whether the standard C++ I/O objects are synchronized with the C I/O functions. Initially, they are synchronized.

Copying information associated with streams

If you call sync_with_stdio(false) after any I/O has been performed, the behavior is implementation-defined.

void unsetf (fmtflags mask)

Clears the mask bits from the formatting flags. It is equivalent to calling flags(flags( ) & ~mask).

streamsize width ( ) const, streamsize width (streamsize wide)

Returns or sets the minimum field width. When setting the width, the previous width is returned.

static int xalloc ( )

Returns a unique integer, suitable for use as an index to the iword or pword functions. You can think of ios_base as having a static integer data member, xalloc_index, and xalloc is implemented so it returns xalloc_index ++.