Apache C++ Standard Library Reference Guide

## ios_base

Library: Input/output

    Does not inherit

- Local Index
- Summary
- Synopsis
- Description
- Interface
- Member Types
- Protected Constructor
- Destructors
- Public Member Functions
- Class failure
- Class Init
- Nonmember Functions
- See Also
- Standards Conformance

### Local Index

#### Members

event event_callback failure() flags() fmtflags getloc() | imbue() iostate ios_base() iword() openmode precision() | pword() register_callback() seekdir setf() sync_with_stdio() unsetf() | what() width() xalloc() ~ios_base()

#### Non-Members

boolalpha() dec() fixed() hex() internal() left() | noboolalpha() noshowbase() noshowpoint() noshowpos() noskipws() nounitbuf() | nouppercase() oct() right() scientific() showbase() showpoint() | showpos() skipws() unitbuf() uppercase()

### Summary

Base class that defines member types and maintains data for classes that inherit from it

### Synopsis

    #include <ios>

    namespace std {
      class ios_base;
    }

### Description

The class ios_base defines several member types:

- A class failure derived from exception

- A class Init

- Three Bitmask Types: `fmtflags`, `iostate`, and `openmode`

- Two enumerated types: `seekdir` and `event`

It maintains several kinds of data:

- Control information that influences how to interpret (format) input sequences and how to generate (format) output sequences

- Locale object used within the stream classes

- Arrays of user data used for storage management

- A number of static constant data members

- Additional information that is stored by the program for its private use

### Interface

    namespace std {
        class ios_base {
        public:
          class failure;

          typedef T1 fmtflags;
          static const fmtflags boolalpha;
          static const fmtflags dec;
          static const fmtflags fixed;
          static const fmtflags hex;
          static const fmtflags internal;
          static const fmtflags left;
          static const fmtflags oct;
          static const fmtflags right;
          static const fmtflags scientific;
          static const fmtflags showbase;
          static const fmtflags showpoint;
          static const fmtflags showpos;
          static const fmtflags skipws;
          static const fmtflags unitbuf;
          static const fmtflags uppercase;
          static const fmtflags adjustfield;
          static const fmtflags basefield;
          static const fmtflags floatfield;

          typedef T2 iostate;
          static const iostate badbit;
          static const iostate eofbit;
          static const iostate failbit;
          static const iostate goodbit;

          typedef T3 openmode;
          static const openmode app;
          static const openmode ate;
          static const openmode binary;
          static const openmode in;
          static const openmode out;
          static const openmode trunc;
          static const openmode nocreate;
          static const openmode noreplace;

          enum T4 seekdir;
          static const seekdir beg;
          static const seekdir cur;
          static const seekdir end;

          class Init;

          fmtflags flags () const;
          fmtflags flags (fmtflags);
          fmtflags setf (fmtflags);
          fmtflags setf (fmtflags, fmtflags);
          void unsetf (fmtflags);

          streamsize precision () const;
          streamsize precision (streamsize);
          streamsize width () const;
          streamsize width (streamsize);

          locale imbue (const locale&);
          locale getloc () const;

          static int xalloc ();
          long&  iword (int);
          void*& pword (int);

          virtual ~ios_base();

          enum event { erase_event, imbue_event, copyfmt_event };
          typedef void (*event_callback)(event, ios_base&, int);
          void register_callback (event_call_back, int);

          static bool sync_with_stdio (bool = true);

        protected:
          ios_base();
      };

      ios_base& boolalpha (ios_base&);
      ios_base& noboolalpha (ios_base&);
      ios_base& showbase (ios_base&);
      ios_base& noshowbase (ios_base&);
      ios_base& showpoint (ios_base&);
      ios_base& noshowpoint (ios_base&);
      ios_base& showpos (ios_base&);
      ios_base& noshowpos (ios_base&);
      ios_base& skipws (ios_base&);
      ios_base& noskipws (ios_base&);
      ios_base& uppercase (ios_base&);
      ios_base& nouppercase (ios_base&);
      ios_base& internal (ios_base&);
      ios_base& left (ios_base&);
      ios_base& right (ios_base&);
      ios_base& dec (ios_base&);
      ios_base& hex (ios_base&);
      ios_base& oct (ios_base&);
      ios_base& fixed (ios_base&);
      ios_base& scientific (ios_base&);
      ios_base& unitbuf (ios_base&);
      ios_base& nounitbuf (ios_base&);
    }

### Member Types

    fmtflags

The type `fmtflags` is a bitmask type. See Bitmask Type for more information. Setting its elements has the following effects:

`showpos` | Generates a + sign in nonnegative generated numeric output.
`showbase` | Generates a prefix indicating the numeric base of generated integer output
`uppercase` | Replaces certain lowercase letters with their uppercase equivalents in generated output
`showpoint` | Generates a decimal-point character unconditionally in generated floating-point output
`boolalpha` | Inserts and extracts bool type in alphabetic format
`unitbuf` | Flushes output after each output operation
`internal` | Adds fill characters at a designated internal point in certain generated output. If no such point is designated, it's identical to `right`.
`left` | Adds fill characters on the right (final positions) of certain generated output
`right` | Adds fill characters on the left (initial positions) of certain generated output
`dec` | Converts integer input or generates integer output in decimal base
`hex` | Converts integer input or generates integer output in hexadecimal base
`oct` | Converts integer input or generates integer output in octal base
`fixed` | Generates floating-point output in fixed-point notation
`scientific` | Generates floating-point output in scientific notation
`skipws` | Skips leading white space before certain input operation.

The following constants are also defined:

`adjustfield` | `left | right | internal`
`basefield` | `dec | hex | oct`
`floatfield` | `scientific | fixed`

    iostate

The type `iostate` is a bitmask type. See Bitmask Types for more information. Setting its elements has the following effects:

`badbit` | Indicates a loss of integrity in an input or output sequence.
`eofbit` | Indicates that an input operation reached the end of an input sequence.
`failbit` | Indicates that an input operation failed to read the expected characters, or that an output operation failed to generate the desired characters.
`goodbit` | Initial stream state, no other bit is set.

    openmode

The type `openmode` is a bitmask type. See Bitmask Types for more information. Setting its elements has the following effects:

`app` | Attempts to seek to the end of the file immediately before each write. Each seek and the subsequent write are performed as a single atomic operation.
`ate` | Attempts to seek to the end of the file immediately after opening. The opening and the subsequent seek may be performed as two operations.
`binary` | Performs input and output in binary mode rather than text mode. In binary mode the stream treats the contents of the file as a sequence of bytes without interpreting in any special way, certain sequences of characters such as carriage returns and line feeds.
`in` | Opens for input.
`out` | Opens for output.
`trunc` | Attempts to truncate an existing file to 0 size immediately after opening. The file must be opened for output (i.e., with `out`). The opening and the subsequent truncation are performed as a single atomic operation.
`nocreate` | Successfully opens the file if and only if a file with that name already exists. The checking for the file's existence and its subsequent creation are performed as a single atomic operation.
`noreplace` | Successfully creates the file if and only if a file with that name does not already exist and the file is being opened for output (i.e., with `out`). The checking for the file's existence and its subsequent creation are performed as a single atomic operation.

> NOTE -- The nocreate and noreplace elements are not part of the C++ Standard, but are provided as an extension. See Appendix B, for a complete list of extensions of this implementation.

    seekdir

The type `seekdir` is an enumerated type. Setting its elements has the following effects:

`beg` | Requests a seek relative to the beginning of the stream.
`cur` | Requests a seek relative to the current position within the sequence.
`end` | Requests a seek relative to the current end of the sequence.

    event

Constants of the enumerated type `event` are passed as arguments to user-defined callback functions registered with the stream objects via `register_callback()`:

`erase_event` | The stream object is being erased.
`imbue_event` | A new locale is being imbued in the stream object.
`copyfmt_event` | The `copyfmt()` member function has been called on an object.

    event_callback

The type `event_callback` is the type of the callback function used as a parameter in the function `register_callback`. These functions allow you to use the `iword`, `pword` mechanism in an exception-safe environment.

### Protected Constructor

    ios_base();

The ios_base members have an indeterminate value after construction.

### Destructors

    virtual
    ~ios_base();

Destroys an object of class ios_base. Calls each registered callback pair `(fn, index)` as `(*fn)(erase_event,*this, index)` at such a time that any ios_base member function called from within `fn` has well-defined results.

### Public Member Functions

    fmtflags
    flags() const;

Returns the format control information for both input and output.

    fmtflags
    flags(fmtflags fmtfl);

Sets `flags()` to `fmtfl` and returns the previous value of `flags()`.

    fmtflags
    setf(fmtflags fmtfl);

Sets `flags()` to `(fmtfl | flags())` and returns the previous value of `flags()`.

    fmtflags
    setf(fmtflags fmtfl, fmtflags mask);

Clears `mask` in `flags()`, sets `(fmtfl & mask)` in `flags()`, and returns the previous value of `flags()`.

    void
    unsetf(fmtflags mask);

Clears `mask` in `flags()`.

    locale
    getloc() const;

Returns the imbued locale, which is used to perform locale-dependent input and output operations. The default locale, `locale::locale()`, is used if no other locale object has been imbued in the stream by a call to the `imbue` function.

    locale
    imbue(const locale& loc);

Saves the value returned by `getloc()`, then assigns `loc` to a private variable and calls each registered callback pair `(fn, index)` as `(*fn)(imbue_event,*this, index)`. It then returns the previously saved value.

    long&
    iword(int idx);

If `iarray` is a null pointer, allocates an array of `long`s of sufficient size, and stores a pointer to its first element in `iarray`. The function then extends the array pointed to by `iarray`, as necessary, to include the element `iarray[idx]`. Each newly allocated element of the array is initialized to `0`. The reference returned may become invalid after another call to the object's `iword()` member with a different index, after a call to its `copyfmt()` member, or when the object is destroyed. If the function fails, it sets `failbit`, which may throw an exception. On success, the function returns `iarray[idx]`; otherwise, a valid `long&` initialized to `0`.

    streamsize
    precision() const;

Returns the precision (number of digits after the decimal point) to generate on certain output conversions.

    streamsize
    precision(streamsize prec);

Saves the precision, then sets it to `prec` and returns the previously saved value.

    void*&
    pword(int idx);

If `parray` is a null pointer, allocates an array of `void*` of sufficient size, and stores a pointer to its first element in `parray`. The function then extends the array pointed at by `parray`, as necessary, to include the element `parray[idx]`. Each newly allocated element of the array is initialized to `0`. The reference returned may become invalid after another call to the object's `pword` member with a different index, after a call to its `copyfmt()` member, or when the object is destroyed. If the function fails, it sets `failbit`, which may throw an exception. On success, the function returns `parray[idx]`; otherwise, a valid `void*&` initialized to `0`.

    void
    register_callback(event_callback fn, int index);

Registers the pair `(fn, index)` such that during calls to `imbue()`, `copyfmt()`, or `~ios_base()`, the function `fn` is called with argument `index`. Functions registered are called when an event occurs, in opposite order of registration. Functions registered while a callback function is active are not called until the next event. Identical pairs are not merged; a function registered twice is called twice per event.

    bool
    sync_with_stdio(bool sync = true);

When called with a `false` argument, allows the C++ standard streams to operate independently of the standard C streams, which greatly improves performance. When called with a `true` argument, restores the default synchronization. The return value of the function is the status of the synchronization at the time of the call.

    streamsize
    width() const;

Returns the field width (number of characters) to generate on certain output conversions.

    streamsize
    width(streamsize wide);

Saves the field width, sets it to `wide`, and returns the previously saved value.

    static int
    xalloc();

Returns the next static index that can be used with `pword` and `iword`. This is useful if you want to share data between several stream objects.

### Class failure

The class failure defines the base class for the types of all objects thrown as exceptions by functions in the iostream s library. It reports errors detected during stream buffer operations.

Constructor

    explicit failure(const string& msg);

Constructs an object of class `failure`, initializing the base class with `exception(msg).`

Public Member Function

    const char*
    what() const;

Returns the message `msg` with which the exception was created.

### Class Init

The class Init describes an object whose construction ensures the construction of the eight objects declared in `<iostream>`, which associates file stream buffers with the standard C streams.

### Nonmember Functions

The following functions are ios_base manipulators.

    ios_base&
    boolalpha(ios_base& str);

Calls `str.setf(ios_base::boolalpha)` and returns `str`.

    ios_base&
    dec(ios_base& str);

Calls `str.setf(ios_base::dec, ios_base::basefield)` and returns `str`.

    ios_base&
    fixed(ios_base& str);

Calls `str.setf(ios_base::fixed, ios_base::floatfield)` and returns `str`.

    ios_base&
    hex(ios_base& str);

Calls `str.setf(ios_base::hex, ios_base::basefield)` and returns `str`.

    ios_base&
    internal(ios_base& str);

Calls `str.setf(ios_base::internal, ios_base::adjustfield)` and returns `str`.

    ios_base&
    left(ios_base& str);

Calls `str.setf(ios_base::left, ios_base::adjustfield)` and returns `str`.

    ios_base&
    noboolalpha(ios_base& str);

Calls `str.unsetf(ios_base::boolalpha)` and returns `str.`

    ios_base&
    noshowbase(ios_base& str);

Calls `str.unsetf(ios_base::showbase)` and returns `str`.

    ios_base&
    noshowpoint(ios_base& str);

Calls `str.unsetf(ios_base::showpoint)` and returns `str`.

    ios_base&
    noshowpos(ios_base& str);

Calls `str.unsetf(ios_base::showpos)` and returns `str`.

    ios_base&
    noskipws(ios_base& str);

Calls `str.unsetf(ios_base::skipws)` and returns `str`.

    ios_base&
    nounitbuf(ios_base& str);

Calls `str.unsetf(ios_base::unitbuf)` and returns `str`.

    ios_base&
    nouppercase(ios_base& str);

Calls `str.unsetf(ios_base::uppercase)` and returns `str`.

    ios_base&
    oct(ios_base& str);

Calls`str.setf(ios_base::oct, ios_base::basefield)` and returns`str`.

    ios_base&
    right(ios_base& str);

Calls `str.setf(ios_base::right, ios_base::adjustfield)` and returns `str`.

    ios_base&
    scientific(ios_base& str);

Calls `str.setf(ios_base::scientific, ios_base::floatfield)` and returns `str`.

    ios_base&
    showbase(ios_base& str);

Calls `str.setf(ios_base::showbase)` and returns `str`.

    ios_base&
    showpoint(ios_base& str);

Calls `str.setf(ios_base::showpoint)` and returns s`tr`.

    ios_base&
    showpos(ios_base& str);

Calls `str.setf(ios_base::showpos)` and returns `str`.

    ios_base&
    skipws(ios_base& str);

Calls `str.setf(ios_base::skipws)` and returns `str`.

    ios_base&
    unitbuf(ios_base& str);

Calls `str.setf(ios_base::unitbuf)` and returns `str`.

    ios_base&
    uppercase(ios_base& str);

Calls `str.setf(ios_base::uppercase)` and returns `str`.

### See Also

basic_ios, basic_istream, basic_ostream, char_traits

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems --Programming Language C++, Section 27.4.2