From Jason Turner

[bitset]

C++17 → C++20 13.3 KB 167 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpcdbd7odc/{from.md → to.md} +69 -83
tmp/tmpcdbd7odc/{from.md → to.md} RENAMED
@@ -1,12 +1,16 @@
1
  ## Bitsets <a id="bitset">[[bitset]]</a>
2
 
3
  ### Header `<bitset>` synopsis <a id="bitset.syn">[[bitset.syn]]</a>
4
 
 
 
 
 
5
  ``` cpp
6
  #include <string>
7
- #include <iosfwd> // for istream ([istream.syn]), ostream ([ostream.syn]), see [iosfwd.syn]
8
 
9
  namespace std {
10
  template<size_t N> class bitset;
11
 
12
  // [bitset.operators], bitset operators
@@ -23,26 +27,24 @@ namespace std {
23
  basic_ostream<charT, traits>&
24
  operator<<(basic_ostream<charT, traits>& os, const bitset<N>& x);
25
  }
26
  ```
27
 
28
- The header `<bitset>` defines a class template and several related
29
- functions for representing and manipulating fixed-size sequences of
30
- bits.
31
-
32
  ### Class template `bitset` <a id="template.bitset">[[template.bitset]]</a>
33
 
34
  ``` cpp
35
  namespace std {
36
  template<size_t N> class bitset {
37
  public:
38
- // bit reference:
39
  class reference {
40
  friend class bitset;
41
  reference() noexcept;
 
42
  public:
43
- ~reference() noexcept;
 
44
  reference& operator=(bool x) noexcept; // for b[i] = x;
45
  reference& operator=(const reference&) noexcept; // for b[i] = b[j];
46
  bool operator~() const noexcept; // flips the bit
47
  operator bool() const noexcept; // for x = b[i];
48
  reference& flip() noexcept; // for b[i].flip();
@@ -53,12 +55,12 @@ namespace std {
53
  constexpr bitset(unsigned long long val) noexcept;
54
  template<class charT, class traits, class Allocator>
55
  explicit bitset(
56
  const basic_string<charT, traits, Allocator>& str,
57
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
58
- typename basic_string<charT, traits, Allocator>::size_type n =
59
- basic_string<charT, traits, Allocator>::npos,
60
  charT zero = charT('0'),
61
  charT one = charT('1'));
62
  template<class charT>
63
  explicit bitset(
64
  const charT* str,
@@ -78,11 +80,11 @@ namespace std {
78
  bitset<N>& reset(size_t pos);
79
  bitset<N> operator~() const noexcept;
80
  bitset<N>& flip() noexcept;
81
  bitset<N>& flip(size_t pos);
82
 
83
- // element access:
84
  constexpr bool operator[](size_t pos) const; // for b[i];
85
  reference operator[](size_t pos); // for b[i];
86
 
87
  unsigned long to_ulong() const;
88
  unsigned long long to_ullong() const;
@@ -93,11 +95,10 @@ namespace std {
93
  to_string(charT zero = charT('0'), charT one = charT('1')) const;
94
 
95
  size_t count() const noexcept;
96
  constexpr size_t size() const noexcept;
97
  bool operator==(const bitset<N>& rhs) const noexcept;
98
- bool operator!=(const bitset<N>& rhs) const noexcept;
99
  bool test(size_t pos) const;
100
  bool all() const noexcept;
101
  bool any() const noexcept;
102
  bool none() const noexcept;
103
  bitset<N> operator<<(size_t pos) const noexcept;
@@ -123,89 +124,82 @@ values.
123
 
124
  The functions described in this subclause can report three kinds of
125
  errors, each associated with a distinct exception:
126
 
127
  - an *invalid-argument* error is associated with exceptions of type
128
- `invalid_argument` ([[invalid.argument]]);
129
  - an *out-of-range* error is associated with exceptions of type
130
- `out_of_range` ([[out.of.range]]);
131
  - an *overflow* error is associated with exceptions of type
132
- `overflow_error` ([[overflow.error]]).
133
 
134
- #### `bitset` constructors <a id="bitset.cons">[[bitset.cons]]</a>
135
 
136
  ``` cpp
137
  constexpr bitset() noexcept;
138
  ```
139
 
140
- *Effects:* Constructs an object of class `bitset<N>`, initializing all
141
- bits to zero.
142
 
143
  ``` cpp
144
  constexpr bitset(unsigned long long val) noexcept;
145
  ```
146
 
147
- *Effects:* Constructs an object of class `bitset<N>`, initializing the
148
- first `M` bit positions to the corresponding bit values in `val`. `M` is
149
- the smaller of `N` and the number of bits in the value
150
- representation ([[basic.types]]) of `unsigned long long`. If `M < N`,
151
- the remaining bit positions are initialized to zero.
152
 
153
  ``` cpp
154
  template<class charT, class traits, class Allocator>
155
- explicit
156
- bitset(const basic_string<charT, traits, Allocator>& str,
157
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
158
- typename basic_string<charT, traits, Allocator>::size_type n =
159
- basic_string<charT, traits, Allocator>::npos,
160
- charT zero = charT('0'), charT one = charT('1'));
 
161
  ```
162
 
163
- *Throws:* `out_of_range` if `pos > str.size()` or `invalid_argument` if
164
- an invalid character is found (see below).
165
-
166
  *Effects:* Determines the effective length `rlen` of the initializing
167
- string as the smaller of `n` and `str.size() - pos`.
168
-
169
- The function then throws
170
-
171
- `invalid_argument` if any of the `rlen` characters in `str` beginning at
172
- position `pos` is other than `zero` or `one`. The function uses
173
- `traits::eq()` to compare the character values.
174
-
175
- Otherwise, the function constructs an object of class `bitset<N>`,
176
- initializing the first `M` bit positions to values determined from the
177
- corresponding characters in the string `str`. `M` is the smaller of `N`
178
- and `rlen`.
179
 
180
  An element of the constructed object has value zero if the corresponding
181
  character in `str`, beginning at position `pos`, is `zero`. Otherwise,
182
  the element has the value one. Character position `pos + M - 1`
183
  corresponds to bit position zero. Subsequent decreasing character
184
  positions correspond to increasing bit positions.
185
 
186
  If `M < N`, remaining bit positions are initialized to zero.
187
 
 
 
 
 
 
 
188
  ``` cpp
189
  template<class charT>
190
  explicit bitset(
191
  const charT* str,
192
  typename basic_string<charT>::size_type n = basic_string<charT>::npos,
193
- charT zero = charT('0'), charT one = charT('1'));
 
194
  ```
195
 
196
- *Effects:* Constructs an object of class `bitset<N>` as if by:
197
 
198
  ``` cpp
199
- bitset(
200
- n == basic_string<charT>::npos
201
  ? basic_string<charT>(str)
202
  : basic_string<charT>(str, n),
203
  0, n, zero, one)
204
  ```
205
 
206
- #### `bitset` members <a id="bitset.members">[[bitset.members]]</a>
207
 
208
  ``` cpp
209
  bitset<N>& operator&=(const bitset<N>& rhs) noexcept;
210
  ```
211
 
@@ -268,18 +262,18 @@ bitset<N>& set() noexcept;
268
 
269
  ``` cpp
270
  bitset<N>& set(size_t pos, bool val = true);
271
  ```
272
 
273
- *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
274
- position.
275
-
276
  *Effects:* Stores a new value in the bit at position `pos` in `*this`.
277
- If `val` is nonzero, the stored value is one, otherwise it is zero.
278
 
279
  *Returns:* `*this`.
280
 
 
 
 
281
  ``` cpp
282
  bitset<N>& reset() noexcept;
283
  ```
284
 
285
  *Effects:* Resets all bits in `*this`.
@@ -288,17 +282,17 @@ bitset<N>& reset() noexcept;
288
 
289
  ``` cpp
290
  bitset<N>& reset(size_t pos);
291
  ```
292
 
293
- *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
294
- position.
295
-
296
  *Effects:* Resets the bit at position `pos` in `*this`.
297
 
298
  *Returns:* `*this`.
299
 
 
 
 
300
  ``` cpp
301
  bitset<N> operator~() const noexcept;
302
  ```
303
 
304
  *Effects:* Constructs an object `x` of class `bitset<N>` and initializes
@@ -316,37 +310,35 @@ bitset<N>& flip() noexcept;
316
 
317
  ``` cpp
318
  bitset<N>& flip(size_t pos);
319
  ```
320
 
321
- *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
322
- position.
323
-
324
  *Effects:* Toggles the bit at position `pos` in `*this`.
325
 
326
  *Returns:* `*this`.
327
 
 
 
 
328
  ``` cpp
329
  unsigned long to_ulong() const;
330
  ```
331
 
332
- *Throws:* `overflow_error`
333
-
334
- if the integral value `x` corresponding to the bits in `*this` cannot be
335
- represented as type `unsigned long`.
336
-
337
  *Returns:* `x`.
338
 
 
 
 
339
  ``` cpp
340
  unsigned long long to_ullong() const;
341
  ```
342
 
 
 
343
  *Throws:* `overflow_error` if the integral value `x` corresponding to
344
  the bits in `*this` cannot be represented as type `unsigned long long`.
345
 
346
- *Returns:* `x`.
347
-
348
  ``` cpp
349
  template<class charT = char,
350
  class traits = char_traits<charT>,
351
  class Allocator = allocator<charT>>
352
  basic_string<charT, traits, Allocator>
@@ -380,26 +372,20 @@ bool operator==(const bitset<N>& rhs) const noexcept;
380
  ```
381
 
382
  *Returns:* `true` if the value of each bit in `*this` equals the value
383
  of the corresponding bit in `rhs`.
384
 
385
- ``` cpp
386
- bool operator!=(const bitset<N>& rhs) const noexcept;
387
- ```
388
-
389
- *Returns:* `true` if `!(*this == rhs)`.
390
-
391
  ``` cpp
392
  bool test(size_t pos) const;
393
  ```
394
 
395
- *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
396
- position.
397
-
398
  *Returns:* `true` if the bit at position `pos` in `*this` has the value
399
  one.
400
 
 
 
 
401
  ``` cpp
402
  bool all() const noexcept;
403
  ```
404
 
405
  *Returns:* `count() == size()`.
@@ -430,41 +416,41 @@ bitset<N> operator>>(size_t pos) const noexcept;
430
 
431
  ``` cpp
432
  constexpr bool operator[](size_t pos) const;
433
  ```
434
 
435
- *Requires:* `pos` shall be valid.
436
 
437
  *Returns:* `true` if the bit at position `pos` in `*this` has the value
438
  one, otherwise `false`.
439
 
440
  *Throws:* Nothing.
441
 
442
  ``` cpp
443
  bitset<N>::reference operator[](size_t pos);
444
  ```
445
 
446
- *Requires:* `pos` shall be valid.
447
 
448
  *Returns:* An object of type `bitset<N>::reference` such that
449
  `(*this)[pos] == this->test(pos)`, and such that `(*this)[pos] = val` is
450
  equivalent to `this->set(pos, val)`.
451
 
452
  *Throws:* Nothing.
453
 
454
  *Remarks:* For the purpose of determining the presence of a data
455
- race ([[intro.multithread]]), any access or update through the
456
- resulting reference potentially accesses or modifies, respectively, the
457
- entire underlying bitset.
458
 
459
  ### `bitset` hash support <a id="bitset.hash">[[bitset.hash]]</a>
460
 
461
  ``` cpp
462
  template<size_t N> struct hash<bitset<N>>;
463
  ```
464
 
465
- The specialization is enabled ([[unord.hash]]).
466
 
467
  ### `bitset` operators <a id="bitset.operators">[[bitset.operators]]</a>
468
 
469
  ``` cpp
470
  bitset<N> operator&(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
@@ -488,11 +474,11 @@ bitset<N> operator^(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
488
  template<class charT, class traits, size_t N>
489
  basic_istream<charT, traits>&
490
  operator>>(basic_istream<charT, traits>& is, bitset<N>& x);
491
  ```
492
 
493
- A formatted input function ([[istream.formatted]]).
494
 
495
  *Effects:* Extracts up to `N` characters from `is`. Stores these
496
  characters in a temporary object `str` of type
497
  `basic_string<charT, traits>`, then evaluates the expression
498
  `x = bitset<N>(str)`. Characters are extracted and stored until any of
@@ -501,13 +487,13 @@ the following occurs:
501
  - `N` characters have been extracted and stored;
502
  - end-of-file occurs on the input sequence;
503
  - the next input character is neither `is.widen(’0’)` nor
504
  `is.widen(’1’)` (in which case the input character is not extracted).
505
 
506
- If no characters are stored in `str`, calls
507
- `is.setstate(ios_base::failbit)` (which may throw
508
- `ios_base::failure` ([[iostate.flags]])).
509
 
510
  *Returns:* `is`.
511
 
512
  ``` cpp
513
  template<class charT, class traits, size_t N>
 
1
  ## Bitsets <a id="bitset">[[bitset]]</a>
2
 
3
  ### Header `<bitset>` synopsis <a id="bitset.syn">[[bitset.syn]]</a>
4
 
5
+ The header `<bitset>` defines a class template and several related
6
+ functions for representing and manipulating fixed-size sequences of
7
+ bits.
8
+
9
  ``` cpp
10
  #include <string>
11
+ #include <iosfwd> // for istream[istream.syn], ostream[ostream.syn], see [iosfwd.syn]
12
 
13
  namespace std {
14
  template<size_t N> class bitset;
15
 
16
  // [bitset.operators], bitset operators
 
27
  basic_ostream<charT, traits>&
28
  operator<<(basic_ostream<charT, traits>& os, const bitset<N>& x);
29
  }
30
  ```
31
 
 
 
 
 
32
  ### Class template `bitset` <a id="template.bitset">[[template.bitset]]</a>
33
 
34
  ``` cpp
35
  namespace std {
36
  template<size_t N> class bitset {
37
  public:
38
+ // bit reference
39
  class reference {
40
  friend class bitset;
41
  reference() noexcept;
42
+
43
  public:
44
+ reference(const reference&) = default;
45
+ ~reference();
46
  reference& operator=(bool x) noexcept; // for b[i] = x;
47
  reference& operator=(const reference&) noexcept; // for b[i] = b[j];
48
  bool operator~() const noexcept; // flips the bit
49
  operator bool() const noexcept; // for x = b[i];
50
  reference& flip() noexcept; // for b[i].flip();
 
55
  constexpr bitset(unsigned long long val) noexcept;
56
  template<class charT, class traits, class Allocator>
57
  explicit bitset(
58
  const basic_string<charT, traits, Allocator>& str,
59
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
60
+ typename basic_string<charT, traits, Allocator>::size_type n
61
+ = basic_string<charT, traits, Allocator>::npos,
62
  charT zero = charT('0'),
63
  charT one = charT('1'));
64
  template<class charT>
65
  explicit bitset(
66
  const charT* str,
 
80
  bitset<N>& reset(size_t pos);
81
  bitset<N> operator~() const noexcept;
82
  bitset<N>& flip() noexcept;
83
  bitset<N>& flip(size_t pos);
84
 
85
+ // element access
86
  constexpr bool operator[](size_t pos) const; // for b[i];
87
  reference operator[](size_t pos); // for b[i];
88
 
89
  unsigned long to_ulong() const;
90
  unsigned long long to_ullong() const;
 
95
  to_string(charT zero = charT('0'), charT one = charT('1')) const;
96
 
97
  size_t count() const noexcept;
98
  constexpr size_t size() const noexcept;
99
  bool operator==(const bitset<N>& rhs) const noexcept;
 
100
  bool test(size_t pos) const;
101
  bool all() const noexcept;
102
  bool any() const noexcept;
103
  bool none() const noexcept;
104
  bitset<N> operator<<(size_t pos) const noexcept;
 
124
 
125
  The functions described in this subclause can report three kinds of
126
  errors, each associated with a distinct exception:
127
 
128
  - an *invalid-argument* error is associated with exceptions of type
129
+ `invalid_argument` [[invalid.argument]];
130
  - an *out-of-range* error is associated with exceptions of type
131
+ `out_of_range` [[out.of.range]];
132
  - an *overflow* error is associated with exceptions of type
133
+ `overflow_error` [[overflow.error]].
134
 
135
+ #### Constructors <a id="bitset.cons">[[bitset.cons]]</a>
136
 
137
  ``` cpp
138
  constexpr bitset() noexcept;
139
  ```
140
 
141
+ *Effects:* Initializes all bits in `*this` to zero.
 
142
 
143
  ``` cpp
144
  constexpr bitset(unsigned long long val) noexcept;
145
  ```
146
 
147
+ *Effects:* Initializes the first `M` bit positions to the corresponding
148
+ bit values in `val`. `M` is the smaller of `N` and the number of bits in
149
+ the value representation [[basic.types]] of `unsigned long long`. If
150
+ `M < N`, the remaining bit positions are initialized to zero.
 
151
 
152
  ``` cpp
153
  template<class charT, class traits, class Allocator>
154
+ explicit bitset(
155
+ const basic_string<charT, traits, Allocator>& str,
156
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
157
+ typename basic_string<charT, traits, Allocator>::size_type n
158
+ = basic_string<charT, traits, Allocator>::npos,
159
+ charT zero = charT('0'),
160
+ charT one = charT('1'));
161
  ```
162
 
 
 
 
163
  *Effects:* Determines the effective length `rlen` of the initializing
164
+ string as the smaller of `n` and `str.size() - pos`. Initializes the
165
+ first `M` bit positions to values determined from the corresponding
166
+ characters in the string `str`. `M` is the smaller of `N` and `rlen`.
 
 
 
 
 
 
 
 
 
167
 
168
  An element of the constructed object has value zero if the corresponding
169
  character in `str`, beginning at position `pos`, is `zero`. Otherwise,
170
  the element has the value one. Character position `pos + M - 1`
171
  corresponds to bit position zero. Subsequent decreasing character
172
  positions correspond to increasing bit positions.
173
 
174
  If `M < N`, remaining bit positions are initialized to zero.
175
 
176
+ The function uses `traits::eq` to compare the character values.
177
+
178
+ *Throws:* `out_of_range` if `pos > str.size()` or `invalid_argument` if
179
+ any of the `rlen` characters in `str` beginning at position `pos` is
180
+ other than `zero` or `one`.
181
+
182
  ``` cpp
183
  template<class charT>
184
  explicit bitset(
185
  const charT* str,
186
  typename basic_string<charT>::size_type n = basic_string<charT>::npos,
187
+ charT zero = charT('0'),
188
+ charT one = charT('1'));
189
  ```
190
 
191
+ *Effects:* As if by:
192
 
193
  ``` cpp
194
+ bitset(n == basic_string<charT>::npos
 
195
  ? basic_string<charT>(str)
196
  : basic_string<charT>(str, n),
197
  0, n, zero, one)
198
  ```
199
 
200
+ #### Members <a id="bitset.members">[[bitset.members]]</a>
201
 
202
  ``` cpp
203
  bitset<N>& operator&=(const bitset<N>& rhs) noexcept;
204
  ```
205
 
 
262
 
263
  ``` cpp
264
  bitset<N>& set(size_t pos, bool val = true);
265
  ```
266
 
 
 
 
267
  *Effects:* Stores a new value in the bit at position `pos` in `*this`.
268
+ If `val` is `true`, the stored value is one, otherwise it is zero.
269
 
270
  *Returns:* `*this`.
271
 
272
+ *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
273
+ position.
274
+
275
  ``` cpp
276
  bitset<N>& reset() noexcept;
277
  ```
278
 
279
  *Effects:* Resets all bits in `*this`.
 
282
 
283
  ``` cpp
284
  bitset<N>& reset(size_t pos);
285
  ```
286
 
 
 
 
287
  *Effects:* Resets the bit at position `pos` in `*this`.
288
 
289
  *Returns:* `*this`.
290
 
291
+ *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
292
+ position.
293
+
294
  ``` cpp
295
  bitset<N> operator~() const noexcept;
296
  ```
297
 
298
  *Effects:* Constructs an object `x` of class `bitset<N>` and initializes
 
310
 
311
  ``` cpp
312
  bitset<N>& flip(size_t pos);
313
  ```
314
 
 
 
 
315
  *Effects:* Toggles the bit at position `pos` in `*this`.
316
 
317
  *Returns:* `*this`.
318
 
319
+ *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
320
+ position.
321
+
322
  ``` cpp
323
  unsigned long to_ulong() const;
324
  ```
325
 
 
 
 
 
 
326
  *Returns:* `x`.
327
 
328
+ *Throws:* `overflow_error` if the integral value `x` corresponding to
329
+ the bits in `*this` cannot be represented as type `unsigned long`.
330
+
331
  ``` cpp
332
  unsigned long long to_ullong() const;
333
  ```
334
 
335
+ *Returns:* `x`.
336
+
337
  *Throws:* `overflow_error` if the integral value `x` corresponding to
338
  the bits in `*this` cannot be represented as type `unsigned long long`.
339
 
 
 
340
  ``` cpp
341
  template<class charT = char,
342
  class traits = char_traits<charT>,
343
  class Allocator = allocator<charT>>
344
  basic_string<charT, traits, Allocator>
 
372
  ```
373
 
374
  *Returns:* `true` if the value of each bit in `*this` equals the value
375
  of the corresponding bit in `rhs`.
376
 
 
 
 
 
 
 
377
  ``` cpp
378
  bool test(size_t pos) const;
379
  ```
380
 
 
 
 
381
  *Returns:* `true` if the bit at position `pos` in `*this` has the value
382
  one.
383
 
384
+ *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
385
+ position.
386
+
387
  ``` cpp
388
  bool all() const noexcept;
389
  ```
390
 
391
  *Returns:* `count() == size()`.
 
416
 
417
  ``` cpp
418
  constexpr bool operator[](size_t pos) const;
419
  ```
420
 
421
+ *Preconditions:* `pos` is valid.
422
 
423
  *Returns:* `true` if the bit at position `pos` in `*this` has the value
424
  one, otherwise `false`.
425
 
426
  *Throws:* Nothing.
427
 
428
  ``` cpp
429
  bitset<N>::reference operator[](size_t pos);
430
  ```
431
 
432
+ *Preconditions:* `pos` is valid.
433
 
434
  *Returns:* An object of type `bitset<N>::reference` such that
435
  `(*this)[pos] == this->test(pos)`, and such that `(*this)[pos] = val` is
436
  equivalent to `this->set(pos, val)`.
437
 
438
  *Throws:* Nothing.
439
 
440
  *Remarks:* For the purpose of determining the presence of a data
441
+ race [[intro.multithread]], any access or update through the resulting
442
+ reference potentially accesses or modifies, respectively, the entire
443
+ underlying bitset.
444
 
445
  ### `bitset` hash support <a id="bitset.hash">[[bitset.hash]]</a>
446
 
447
  ``` cpp
448
  template<size_t N> struct hash<bitset<N>>;
449
  ```
450
 
451
+ The specialization is enabled [[unord.hash]].
452
 
453
  ### `bitset` operators <a id="bitset.operators">[[bitset.operators]]</a>
454
 
455
  ``` cpp
456
  bitset<N> operator&(const bitset<N>& lhs, const bitset<N>& rhs) noexcept;
 
474
  template<class charT, class traits, size_t N>
475
  basic_istream<charT, traits>&
476
  operator>>(basic_istream<charT, traits>& is, bitset<N>& x);
477
  ```
478
 
479
+ A formatted input function [[istream.formatted]].
480
 
481
  *Effects:* Extracts up to `N` characters from `is`. Stores these
482
  characters in a temporary object `str` of type
483
  `basic_string<charT, traits>`, then evaluates the expression
484
  `x = bitset<N>(str)`. Characters are extracted and stored until any of
 
487
  - `N` characters have been extracted and stored;
488
  - end-of-file occurs on the input sequence;
489
  - the next input character is neither `is.widen(’0’)` nor
490
  `is.widen(’1’)` (in which case the input character is not extracted).
491
 
492
+ If `N > 0` and no characters are stored in `str`, calls
493
+ `is.setstate(ios_base::failbit)` (which may throw `ios_base::failure`
494
+ [[iostate.flags]]).
495
 
496
  *Returns:* `is`.
497
 
498
  ``` cpp
499
  template<class charT, class traits, size_t N>