cppdraft_translate/cppdraft/ios.md

[ios]

# 31 Input/output library [[input.output]](./#input.output)

## 31.5 Iostreams base classes [[iostreams.base]](iostreams.base#ios)

### 31.5.4 Class template basic_ios [ios]

#### [31.5.4.1](#overview) Overview [[ios.overview]](ios.overview)

[🔗](#lib:basic_ios)

namespace std {template<class charT, class traits = char_traits<charT>>class basic_ios : public ios_base {public:using char_type = charT; using int_type = typename traits::int_type; using pos_type = typename traits::pos_type; using off_type = typename traits::off_type; using traits_type = traits; // [[iostate.flags]](#iostate.flags "31.5.4.4 Flags functions"), flags functionsexplicit operator bool() const; bool operator!() const;
 iostate rdstate() const; void clear(iostate state = goodbit); void setstate(iostate state); bool good() const; bool eof() const; bool fail() const; bool bad() const;

 iostate exceptions() const; void exceptions(iostate except); // [[basic.ios.cons]](#basic.ios.cons "31.5.4.2 Constructors"), constructor/destructorexplicit basic_ios(basic_streambuf<charT, traits>* sb); virtual ~basic_ios(); // [[basic.ios.members]](#basic.ios.members "31.5.4.3 Member functions"), members basic_ostream<charT, traits>* tie() const;
 basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);

 basic_streambuf<charT, traits>* rdbuf() const;
 basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);

 basic_ios& copyfmt(const basic_ios& rhs);

 char_type fill() const;
 char_type fill(char_type ch);

 locale imbue(const locale& loc); char narrow(char_type c, char dfault) const;
 char_type widen(char c) const;

 basic_ios(const basic_ios&) = delete;
 basic_ios& operator=(const basic_ios&) = delete; protected: basic_ios(); void init(basic_streambuf<charT, traits>* sb); void move(basic_ios& rhs); void move(basic_ios&& rhs); void swap(basic_ios& rhs) noexcept; void set_rdbuf(basic_streambuf<charT, traits>* sb); };}

#### [31.5.4.2](#basic.ios.cons) Constructors [[basic.ios.cons]](basic.ios.cons)

[🔗](#lib:basic_ios,constructor)

`explicit basic_ios(basic_streambuf<charT, traits>* sb);
`

[1](#basic.ios.cons-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L1879)

*Effects*: Assigns initial values to its member objects by callinginit(sb)[.](#basic.ios.cons-1.sentence-1)

[🔗](#lib:basic_ios,constructor_)

`basic_ios();
`

[2](#basic.ios.cons-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L1891)

*Effects*: Leaves its member objects uninitialized[.](#basic.ios.cons-2.sentence-1)

The object
shall be initialized by callingbasic_ios​::​init before its first use or before it is destroyed, whichever comes first; otherwise the
behavior is undefined[.](#basic.ios.cons-2.sentence-2)

[🔗](#lib:basic_ios,destructor)

`~basic_ios();
`

[3](#basic.ios.cons-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L1906)

*Remarks*: The destructor does not destroyrdbuf()[.](#basic.ios.cons-3.sentence-1)

[🔗](#lib:init,basic_ios)

`void init(basic_streambuf<charT, traits>* sb);
`

[4](#basic.ios.cons-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L1918)

*Postconditions*: The postconditions of this function are indicated in Table [142](#tab:basic.ios.cons "Table 142: basic_­ios​::​init() effects")[.](#basic.ios.cons-4.sentence-1)

Table [142](#tab:basic.ios.cons) — basic_ios​::​init() effects [[tab:basic.ios.cons]](./tab:basic.ios.cons)  

| [🔗](#tab:basic.ios.cons-row-1)<br>**Element** | **Value** |
| --- | --- |
| [🔗](#tab:basic.ios.cons-row-2)<br>rdbuf() | sb |
| [🔗](#tab:basic.ios.cons-row-3)<br>tie() | 0 |
| [🔗](#tab:basic.ios.cons-row-4)<br>rdstate() | goodbit if sb is not a null pointer, otherwise badbit[.](#tab:basic.ios.cons-row-4-column-2-sentence-1) |
| [🔗](#tab:basic.ios.cons-row-5)<br>exceptions() | goodbit |
| [🔗](#tab:basic.ios.cons-row-6)<br>flags() | skipws | dec |
| [🔗](#tab:basic.ios.cons-row-7)<br>width() | 0 |
| [🔗](#tab:basic.ios.cons-row-8)<br>precision() | 6 |
| [🔗](#tab:basic.ios.cons-row-9)<br>fill() | widen(' ') |
| [🔗](#tab:basic.ios.cons-row-10)<br>getloc() | a copy of the value returned by locale() |
| [🔗](#tab:basic.ios.cons-row-11)<br>*iarray* | a null pointer |
| [🔗](#tab:basic.ios.cons-row-12)<br>*parray* | a null pointer |

#### [31.5.4.3](#basic.ios.members) Member functions [[basic.ios.members]](basic.ios.members)

[🔗](#lib:tie,basic_ios)

`basic_ostream<charT, traits>* tie() const;
`

[1](#basic.ios.members-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L1956)

*Returns*: An output sequence that is*tied* to (synchronized with) the sequence controlled by the stream buffer[.](#basic.ios.members-1.sentence-1)

[🔗](#lib:tie,basic_ios_)

`basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);
`

[2](#basic.ios.members-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L1969)

*Preconditions*: If tiestr is not null, tiestr is not reachable by
traversing the linked list of tied stream objects starting fromtiestr->tie()[.](#basic.ios.members-2.sentence-1)

[3](#basic.ios.members-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L1975)

*Postconditions*: tiestr == tie()[.](#basic.ios.members-3.sentence-1)

[4](#basic.ios.members-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L1979)

*Returns*: The previous value oftie()[.](#basic.ios.members-4.sentence-1)

[🔗](#lib:rdbuf,basic_ios)

`basic_streambuf<charT, traits>* rdbuf() const;
`

[5](#basic.ios.members-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L1991)

*Returns*: A pointer to thestreambuf associated with the stream[.](#basic.ios.members-5.sentence-1)

[🔗](#lib:rdbuf,basic_ios_)

`basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);
`

[6](#basic.ios.members-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2004)

*Effects*: Callsclear()[.](#basic.ios.members-6.sentence-1)

[7](#basic.ios.members-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2009)

*Postconditions*: sb == rdbuf()[.](#basic.ios.members-7.sentence-1)

[8](#basic.ios.members-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2013)

*Returns*: The previous value ofrdbuf()[.](#basic.ios.members-8.sentence-1)

[🔗](#lib:imbue,basic_ios)

`locale imbue(const locale& loc);
`

[9](#basic.ios.members-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2025)

*Effects*: Calls[ios_base​::​imbue](ios.base.locales#lib:ios_base,imbue "31.5.2.4 Functions [ios.base.locales]")(loc) and
ifrdbuf() != 0 thenrdbuf()->[pubimbue](streambuf.locales#lib:basic_streambuf,pubimbue "31.6.3.3.1 Locales [streambuf.locales]")(loc)[.](#basic.ios.members-9.sentence-1)

[10](#basic.ios.members-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2035)

*Returns*: The prior value ofios_base​::​imbue()[.](#basic.ios.members-10.sentence-1)

[🔗](#lib:narrow,basic_ios)

`char narrow(char_type c, char dfault) const;
`

[11](#basic.ios.members-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2047)

*Returns*: use_facet<ctype<char_type>>(getloc()).narrow(c, dfault)[.](#basic.ios.members-11.sentence-1)

[🔗](#lib:widen,basic_ios)

`char_type widen(char c) const;
`

[12](#basic.ios.members-12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2058)

*Returns*: use_facet<ctype<char_type>>(getloc()).widen(c)[.](#basic.ios.members-12.sentence-1)

[🔗](#lib:fill,basic_ios)

`char_type fill() const;
`

[13](#basic.ios.members-13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2069)

*Returns*: The character used to pad (fill) an output conversion to the specified
field width[.](#basic.ios.members-13.sentence-1)

[🔗](#lib:fill,basic_ios_)

`char_type fill(char_type fillch);
`

[14](#basic.ios.members-14)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2081)

*Postconditions*: traits​::​eq(fillch, fill())[.](#basic.ios.members-14.sentence-1)

[15](#basic.ios.members-15)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2085)

*Returns*: The previous value offill()[.](#basic.ios.members-15.sentence-1)

[🔗](#lib:copyfmt,basic_ios)

`basic_ios& copyfmt(const basic_ios& rhs);
`

[16](#basic.ios.members-16)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2097)

*Effects*: If(this == addressof(rhs)) is true does nothing[.](#basic.ios.members-16.sentence-1)

Otherwise assigns to the member objects of*this the corresponding member objects of rhs as follows:

- [(16.1)](#basic.ios.members-16.1)

calls each registered callback pair (fn, idx) as(*fn)(erase_event, *this, idx);

- [(16.2)](#basic.ios.members-16.2)

then, assigns to the member objects of *this the corresponding member objects ofrhs, except that
  * [(16.2.1)](#basic.ios.members-16.2.1)

rdstate(), rdbuf(), and exceptions() are left unchanged;

  * [(16.2.2)](#basic.ios.members-16.2.2)

the contents of arrays pointed at by pword and iword are copied,
not the pointers themselves;[263](#footnote-263 "This suggests an infinite amount of copying, but the implementation can keep track of the maximum element of the arrays that is nonzero.") and

  * [(16.2.3)](#basic.ios.members-16.2.3)

if any newly stored pointer values in *this point at objects stored outside
the object rhs and those objects are destroyed when rhs is destroyed, the
newly stored pointer values are altered to point at newly constructed copies of the
objects;

- [(16.3)](#basic.ios.members-16.3)

then, calls each callback pair that was copied from rhs as(*fn)(copyfmt_event, *this, idx);

- [(16.4)](#basic.ios.members-16.4)

then, calls exceptions(rhs.exceptions())[.](#basic.ios.members-16.sentence-2)

[17](#basic.ios.members-17)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2134)

[*Note [1](#basic.ios.members-note-1)*:

The second pass through the callback pairs permits a copied pword value to be zeroed, or to have its referent deep copied or reference counted, or to have
other special action taken[.](#basic.ios.members-17.sentence-1)

— *end note*]

[18](#basic.ios.members-18)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2141)

*Postconditions*: The postconditions of this function are indicated in Table [143](#tab:basic.ios.copyfmt "Table 143: basic_­ios​::​copyfmt() effects")[.](#basic.ios.members-18.sentence-1)

Table [143](#tab:basic.ios.copyfmt) — basic_ios​::​copyfmt() effects [[tab:basic.ios.copyfmt]](./tab:basic.ios.copyfmt)  

| [🔗](#tab:basic.ios.copyfmt-row-1)<br>**Element** | **Value** |
| --- | --- |
| [🔗](#tab:basic.ios.copyfmt-row-2)<br>rdbuf() | *unchanged* |
| [🔗](#tab:basic.ios.copyfmt-row-3)<br>tie() | rhs.tie() |
| [🔗](#tab:basic.ios.copyfmt-row-4)<br>rdstate() | *unchanged* |
| [🔗](#tab:basic.ios.copyfmt-row-5)<br>exceptions() | rhs.exceptions() |
| [🔗](#tab:basic.ios.copyfmt-row-6)<br>flags() | rhs.flags() |
| [🔗](#tab:basic.ios.copyfmt-row-7)<br>width() | rhs.width() |
| [🔗](#tab:basic.ios.copyfmt-row-8)<br>precision() | rhs.precision() |
| [🔗](#tab:basic.ios.copyfmt-row-9)<br>fill() | rhs.fill() |
| [🔗](#tab:basic.ios.copyfmt-row-10)<br>getloc() | rhs.getloc() |

[19](#basic.ios.members-19)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2167)

*Returns*: *this[.](#basic.ios.members-19.sentence-1)

[🔗](#lib:move,basic_ios)

`void move(basic_ios& rhs);
void move(basic_ios&& rhs);
`

[20](#basic.ios.members-20)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2179)

*Postconditions*: *this has the state thatrhs had before the function call, except thatrdbuf() returns nullptr[.](#basic.ios.members-20.sentence-1)

rhs is in a valid but
unspecified state, except that rhs.rdbuf() returns the
same value as it returned before the function call, andrhs.tie() returns nullptr[.](#basic.ios.members-20.sentence-2)

[🔗](#lib:swap,basic_ios)

`void swap(basic_ios& rhs) noexcept;
`

[21](#basic.ios.members-21)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2195)

*Effects*: The states of *this and rhs are exchanged, except that rdbuf() returns the same
value as it returned before the function call, and rhs.rdbuf() returns the same value as it returned before the function call[.](#basic.ios.members-21.sentence-1)

[🔗](#lib:set_rdbuf,basic_ios)

`void set_rdbuf(basic_streambuf<charT, traits>* sb);
`

[22](#basic.ios.members-22)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2209)

*Preconditions*: sb != nullptr is true[.](#basic.ios.members-22.sentence-1)

[23](#basic.ios.members-23)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2213)

*Effects*: Associates the basic_streambuf object
pointed to by sb with this stream without callingclear()[.](#basic.ios.members-23.sentence-1)

[24](#basic.ios.members-24)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2219)

*Postconditions*: rdbuf() == sb is true[.](#basic.ios.members-24.sentence-1)

[25](#basic.ios.members-25)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2223)

*Throws*: Nothing[.](#basic.ios.members-25.sentence-1)

[263)](#footnote-263)[263)](#footnoteref-263)

This suggests an infinite amount of copying, but the implementation can keep
track of the maximum element of the arrays that is nonzero[.](#footnote-263.sentence-1)

#### [31.5.4.4](#iostate.flags) Flags functions [[iostate.flags]](iostate.flags)

[🔗](#lib:operator_bool,basic_ios)

`explicit operator bool() const;
`

[1](#iostate.flags-1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2236)

*Returns*: !fail()[.](#iostate.flags-1.sentence-1)

[🔗](#lib:operator!,basic_ios)

`bool operator!() const;
`

[2](#iostate.flags-2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2247)

*Returns*: fail()[.](#iostate.flags-2.sentence-1)

[🔗](#lib:rdstate,basic_ios)

`iostate rdstate() const;
`

[3](#iostate.flags-3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2258)

*Returns*: The error state of the stream buffer[.](#iostate.flags-3.sentence-1)

[🔗](#lib:clear,basic_ios)

`void clear(iostate state = goodbit);
`

[4](#iostate.flags-4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2269)

*Effects*: If ((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0,
returns[.](#iostate.flags-4.sentence-1)

Otherwise, the function throws an object of classios_base​::​failure ([[ios.failure]](ios.failure "31.5.2.2.1 Class ios_­base​::​failure")),
constructed withimplementation-defined
argument values[.](#iostate.flags-4.sentence-2)

[5](#iostate.flags-5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2279)

*Postconditions*: Ifrdbuf() != 0 thenstate == rdstate();
otherwiserdstate() == (state | ios_base​::​badbit)[.](#iostate.flags-5.sentence-1)

[🔗](#lib:setstate,basic_ios)

`void setstate(iostate state);
`

[6](#iostate.flags-6)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2295)

*Effects*: Callsclear(rdstate() | state) (which may throwios_base​::​failure ([[ios.failure]](ios.failure "31.5.2.2.1 Class ios_­base​::​failure")))[.](#iostate.flags-6.sentence-1)

[🔗](#lib:good,basic_ios)

`bool good() const;
`

[7](#iostate.flags-7)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2309)

*Returns*: rdstate() == 0[.](#iostate.flags-7.sentence-1)

[🔗](#lib:eof,basic_ios)

`bool eof() const;
`

[8](#iostate.flags-8)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2320)

*Returns*: true ifeofbit is set inrdstate()[.](#iostate.flags-8.sentence-1)

[🔗](#lib:fail,basic_ios)

`bool fail() const;
`

[9](#iostate.flags-9)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2335)

*Returns*: true iffailbit orbadbit is set inrdstate()[.](#iostate.flags-9.sentence-1)[264](#footnote-264 "Checking badbit also for fail() is historical practice.")

[🔗](#lib:bad,basic_ios)

`bool bad() const;
`

[10](#iostate.flags-10)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2359)

*Returns*: true ifbadbit is set inrdstate()[.](#iostate.flags-10.sentence-1)

[🔗](#lib:exceptions,basic_ios)

`iostate exceptions() const;
`

[11](#iostate.flags-11)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2374)

*Returns*: A mask that determines what elements set inrdstate() cause exceptions to be thrown[.](#iostate.flags-11.sentence-1)

[🔗](#lib:exceptions,basic_ios_)

`void exceptions(iostate except);
`

[12](#iostate.flags-12)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2387)

*Effects*: Callsclear(rdstate())[.](#iostate.flags-12.sentence-1)

[13](#iostate.flags-13)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L2392)

*Postconditions*: except == exceptions()[.](#iostate.flags-13.sentence-1)

[264)](#footnote-264)[264)](#footnoteref-264)

Checkingbadbit also forfail() is historical practice[.](#footnote-264.sentence-1)