From Jason Turner

[template.bitset]

C++17 → C++20 10.8 KB 144 lines
Current Draft | LaTeX Source
Archived: C++17 | C++20
Markdown: C++17 | C++20
Explore in Adventure Game
C++ Weekly: Ep 230

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmppongwh1_/{from.md → to.md} +59 -73
tmp/tmppongwh1_/{from.md → to.md} RENAMED
@@ -2,16 +2,18 @@
2
 
3
  ``` cpp
4
  namespace std {
5
  template<size_t N> class bitset {
6
  public:
7
- // bit reference:
8
  class reference {
9
  friend class bitset;
10
  reference() noexcept;
 
11
  public:
12
- ~reference() noexcept;
 
13
  reference& operator=(bool x) noexcept; // for b[i] = x;
14
  reference& operator=(const reference&) noexcept; // for b[i] = b[j];
15
  bool operator~() const noexcept; // flips the bit
16
  operator bool() const noexcept; // for x = b[i];
17
  reference& flip() noexcept; // for b[i].flip();
@@ -22,12 +24,12 @@ namespace std {
22
  constexpr bitset(unsigned long long val) noexcept;
23
  template<class charT, class traits, class Allocator>
24
  explicit bitset(
25
  const basic_string<charT, traits, Allocator>& str,
26
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
27
- typename basic_string<charT, traits, Allocator>::size_type n =
28
- basic_string<charT, traits, Allocator>::npos,
29
  charT zero = charT('0'),
30
  charT one = charT('1'));
31
  template<class charT>
32
  explicit bitset(
33
  const charT* str,
@@ -47,11 +49,11 @@ namespace std {
47
  bitset<N>& reset(size_t pos);
48
  bitset<N> operator~() const noexcept;
49
  bitset<N>& flip() noexcept;
50
  bitset<N>& flip(size_t pos);
51
 
52
- // element access:
53
  constexpr bool operator[](size_t pos) const; // for b[i];
54
  reference operator[](size_t pos); // for b[i];
55
 
56
  unsigned long to_ulong() const;
57
  unsigned long long to_ullong() const;
@@ -62,11 +64,10 @@ namespace std {
62
  to_string(charT zero = charT('0'), charT one = charT('1')) const;
63
 
64
  size_t count() const noexcept;
65
  constexpr size_t size() const noexcept;
66
  bool operator==(const bitset<N>& rhs) const noexcept;
67
- bool operator!=(const bitset<N>& rhs) const noexcept;
68
  bool test(size_t pos) const;
69
  bool all() const noexcept;
70
  bool any() const noexcept;
71
  bool none() const noexcept;
72
  bitset<N> operator<<(size_t pos) const noexcept;
@@ -92,89 +93,82 @@ values.
92
 
93
  The functions described in this subclause can report three kinds of
94
  errors, each associated with a distinct exception:
95
 
96
  - an *invalid-argument* error is associated with exceptions of type
97
- `invalid_argument` ([[invalid.argument]]);
98
  - an *out-of-range* error is associated with exceptions of type
99
- `out_of_range` ([[out.of.range]]);
100
  - an *overflow* error is associated with exceptions of type
101
- `overflow_error` ([[overflow.error]]).
102
 
103
- #### `bitset` constructors <a id="bitset.cons">[[bitset.cons]]</a>
104
 
105
  ``` cpp
106
  constexpr bitset() noexcept;
107
  ```
108
 
109
- *Effects:* Constructs an object of class `bitset<N>`, initializing all
110
- bits to zero.
111
 
112
  ``` cpp
113
  constexpr bitset(unsigned long long val) noexcept;
114
  ```
115
 
116
- *Effects:* Constructs an object of class `bitset<N>`, initializing the
117
- first `M` bit positions to the corresponding bit values in `val`. `M` is
118
- the smaller of `N` and the number of bits in the value
119
- representation ([[basic.types]]) of `unsigned long long`. If `M < N`,
120
- the remaining bit positions are initialized to zero.
121
 
122
  ``` cpp
123
  template<class charT, class traits, class Allocator>
124
- explicit
125
- bitset(const basic_string<charT, traits, Allocator>& str,
126
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
127
- typename basic_string<charT, traits, Allocator>::size_type n =
128
- basic_string<charT, traits, Allocator>::npos,
129
- charT zero = charT('0'), charT one = charT('1'));
 
130
  ```
131
 
132
- *Throws:* `out_of_range` if `pos > str.size()` or `invalid_argument` if
133
- an invalid character is found (see below).
134
-
135
  *Effects:* Determines the effective length `rlen` of the initializing
136
- string as the smaller of `n` and `str.size() - pos`.
137
-
138
- The function then throws
139
-
140
- `invalid_argument` if any of the `rlen` characters in `str` beginning at
141
- position `pos` is other than `zero` or `one`. The function uses
142
- `traits::eq()` to compare the character values.
143
-
144
- Otherwise, the function constructs an object of class `bitset<N>`,
145
- initializing the first `M` bit positions to values determined from the
146
- corresponding characters in the string `str`. `M` is the smaller of `N`
147
- and `rlen`.
148
 
149
  An element of the constructed object has value zero if the corresponding
150
  character in `str`, beginning at position `pos`, is `zero`. Otherwise,
151
  the element has the value one. Character position `pos + M - 1`
152
  corresponds to bit position zero. Subsequent decreasing character
153
  positions correspond to increasing bit positions.
154
 
155
  If `M < N`, remaining bit positions are initialized to zero.
156
 
 
 
 
 
 
 
157
  ``` cpp
158
  template<class charT>
159
  explicit bitset(
160
  const charT* str,
161
  typename basic_string<charT>::size_type n = basic_string<charT>::npos,
162
- charT zero = charT('0'), charT one = charT('1'));
 
163
  ```
164
 
165
- *Effects:* Constructs an object of class `bitset<N>` as if by:
166
 
167
  ``` cpp
168
- bitset(
169
- n == basic_string<charT>::npos
170
  ? basic_string<charT>(str)
171
  : basic_string<charT>(str, n),
172
  0, n, zero, one)
173
  ```
174
 
175
- #### `bitset` members <a id="bitset.members">[[bitset.members]]</a>
176
 
177
  ``` cpp
178
  bitset<N>& operator&=(const bitset<N>& rhs) noexcept;
179
  ```
180
 
@@ -237,18 +231,18 @@ bitset<N>& set() noexcept;
237
 
238
  ``` cpp
239
  bitset<N>& set(size_t pos, bool val = true);
240
  ```
241
 
242
- *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
243
- position.
244
-
245
  *Effects:* Stores a new value in the bit at position `pos` in `*this`.
246
- If `val` is nonzero, the stored value is one, otherwise it is zero.
247
 
248
  *Returns:* `*this`.
249
 
 
 
 
250
  ``` cpp
251
  bitset<N>& reset() noexcept;
252
  ```
253
 
254
  *Effects:* Resets all bits in `*this`.
@@ -257,17 +251,17 @@ bitset<N>& reset() noexcept;
257
 
258
  ``` cpp
259
  bitset<N>& reset(size_t pos);
260
  ```
261
 
262
- *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
263
- position.
264
-
265
  *Effects:* Resets the bit at position `pos` in `*this`.
266
 
267
  *Returns:* `*this`.
268
 
 
 
 
269
  ``` cpp
270
  bitset<N> operator~() const noexcept;
271
  ```
272
 
273
  *Effects:* Constructs an object `x` of class `bitset<N>` and initializes
@@ -285,37 +279,35 @@ bitset<N>& flip() noexcept;
285
 
286
  ``` cpp
287
  bitset<N>& flip(size_t pos);
288
  ```
289
 
290
- *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
291
- position.
292
-
293
  *Effects:* Toggles the bit at position `pos` in `*this`.
294
 
295
  *Returns:* `*this`.
296
 
 
 
 
297
  ``` cpp
298
  unsigned long to_ulong() const;
299
  ```
300
 
301
- *Throws:* `overflow_error`
302
-
303
- if the integral value `x` corresponding to the bits in `*this` cannot be
304
- represented as type `unsigned long`.
305
-
306
  *Returns:* `x`.
307
 
 
 
 
308
  ``` cpp
309
  unsigned long long to_ullong() const;
310
  ```
311
 
 
 
312
  *Throws:* `overflow_error` if the integral value `x` corresponding to
313
  the bits in `*this` cannot be represented as type `unsigned long long`.
314
 
315
- *Returns:* `x`.
316
-
317
  ``` cpp
318
  template<class charT = char,
319
  class traits = char_traits<charT>,
320
  class Allocator = allocator<charT>>
321
  basic_string<charT, traits, Allocator>
@@ -349,26 +341,20 @@ bool operator==(const bitset<N>& rhs) const noexcept;
349
  ```
350
 
351
  *Returns:* `true` if the value of each bit in `*this` equals the value
352
  of the corresponding bit in `rhs`.
353
 
354
- ``` cpp
355
- bool operator!=(const bitset<N>& rhs) const noexcept;
356
- ```
357
-
358
- *Returns:* `true` if `!(*this == rhs)`.
359
-
360
  ``` cpp
361
  bool test(size_t pos) const;
362
  ```
363
 
364
- *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
365
- position.
366
-
367
  *Returns:* `true` if the bit at position `pos` in `*this` has the value
368
  one.
369
 
 
 
 
370
  ``` cpp
371
  bool all() const noexcept;
372
  ```
373
 
374
  *Returns:* `count() == size()`.
@@ -399,29 +385,29 @@ bitset<N> operator>>(size_t pos) const noexcept;
399
 
400
  ``` cpp
401
  constexpr bool operator[](size_t pos) const;
402
  ```
403
 
404
- *Requires:* `pos` shall be valid.
405
 
406
  *Returns:* `true` if the bit at position `pos` in `*this` has the value
407
  one, otherwise `false`.
408
 
409
  *Throws:* Nothing.
410
 
411
  ``` cpp
412
  bitset<N>::reference operator[](size_t pos);
413
  ```
414
 
415
- *Requires:* `pos` shall be valid.
416
 
417
  *Returns:* An object of type `bitset<N>::reference` such that
418
  `(*this)[pos] == this->test(pos)`, and such that `(*this)[pos] = val` is
419
  equivalent to `this->set(pos, val)`.
420
 
421
  *Throws:* Nothing.
422
 
423
  *Remarks:* For the purpose of determining the presence of a data
424
- race ([[intro.multithread]]), any access or update through the
425
- resulting reference potentially accesses or modifies, respectively, the
426
- entire underlying bitset.
427
 
 
2
 
3
  ``` cpp
4
  namespace std {
5
  template<size_t N> class bitset {
6
  public:
7
+ // bit reference
8
  class reference {
9
  friend class bitset;
10
  reference() noexcept;
11
+
12
  public:
13
+ reference(const reference&) = default;
14
+ ~reference();
15
  reference& operator=(bool x) noexcept; // for b[i] = x;
16
  reference& operator=(const reference&) noexcept; // for b[i] = b[j];
17
  bool operator~() const noexcept; // flips the bit
18
  operator bool() const noexcept; // for x = b[i];
19
  reference& flip() noexcept; // for b[i].flip();
 
24
  constexpr bitset(unsigned long long val) noexcept;
25
  template<class charT, class traits, class Allocator>
26
  explicit bitset(
27
  const basic_string<charT, traits, Allocator>& str,
28
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
29
+ typename basic_string<charT, traits, Allocator>::size_type n
30
+ = basic_string<charT, traits, Allocator>::npos,
31
  charT zero = charT('0'),
32
  charT one = charT('1'));
33
  template<class charT>
34
  explicit bitset(
35
  const charT* str,
 
49
  bitset<N>& reset(size_t pos);
50
  bitset<N> operator~() const noexcept;
51
  bitset<N>& flip() noexcept;
52
  bitset<N>& flip(size_t pos);
53
 
54
+ // element access
55
  constexpr bool operator[](size_t pos) const; // for b[i];
56
  reference operator[](size_t pos); // for b[i];
57
 
58
  unsigned long to_ulong() const;
59
  unsigned long long to_ullong() const;
 
64
  to_string(charT zero = charT('0'), charT one = charT('1')) const;
65
 
66
  size_t count() const noexcept;
67
  constexpr size_t size() const noexcept;
68
  bool operator==(const bitset<N>& rhs) const noexcept;
 
69
  bool test(size_t pos) const;
70
  bool all() const noexcept;
71
  bool any() const noexcept;
72
  bool none() const noexcept;
73
  bitset<N> operator<<(size_t pos) const noexcept;
 
93
 
94
  The functions described in this subclause can report three kinds of
95
  errors, each associated with a distinct exception:
96
 
97
  - an *invalid-argument* error is associated with exceptions of type
98
+ `invalid_argument` [[invalid.argument]];
99
  - an *out-of-range* error is associated with exceptions of type
100
+ `out_of_range` [[out.of.range]];
101
  - an *overflow* error is associated with exceptions of type
102
+ `overflow_error` [[overflow.error]].
103
 
104
+ #### Constructors <a id="bitset.cons">[[bitset.cons]]</a>
105
 
106
  ``` cpp
107
  constexpr bitset() noexcept;
108
  ```
109
 
110
+ *Effects:* Initializes all bits in `*this` to zero.
 
111
 
112
  ``` cpp
113
  constexpr bitset(unsigned long long val) noexcept;
114
  ```
115
 
116
+ *Effects:* Initializes the first `M` bit positions to the corresponding
117
+ bit values in `val`. `M` is the smaller of `N` and the number of bits in
118
+ the value representation [[basic.types]] of `unsigned long long`. If
119
+ `M < N`, the remaining bit positions are initialized to zero.
 
120
 
121
  ``` cpp
122
  template<class charT, class traits, class Allocator>
123
+ explicit bitset(
124
+ const basic_string<charT, traits, Allocator>& str,
125
  typename basic_string<charT, traits, Allocator>::size_type pos = 0,
126
+ typename basic_string<charT, traits, Allocator>::size_type n
127
+ = basic_string<charT, traits, Allocator>::npos,
128
+ charT zero = charT('0'),
129
+ charT one = charT('1'));
130
  ```
131
 
 
 
 
132
  *Effects:* Determines the effective length `rlen` of the initializing
133
+ string as the smaller of `n` and `str.size() - pos`. Initializes the
134
+ first `M` bit positions to values determined from the corresponding
135
+ characters in the string `str`. `M` is the smaller of `N` and `rlen`.
 
 
 
 
 
 
 
 
 
136
 
137
  An element of the constructed object has value zero if the corresponding
138
  character in `str`, beginning at position `pos`, is `zero`. Otherwise,
139
  the element has the value one. Character position `pos + M - 1`
140
  corresponds to bit position zero. Subsequent decreasing character
141
  positions correspond to increasing bit positions.
142
 
143
  If `M < N`, remaining bit positions are initialized to zero.
144
 
145
+ The function uses `traits::eq` to compare the character values.
146
+
147
+ *Throws:* `out_of_range` if `pos > str.size()` or `invalid_argument` if
148
+ any of the `rlen` characters in `str` beginning at position `pos` is
149
+ other than `zero` or `one`.
150
+
151
  ``` cpp
152
  template<class charT>
153
  explicit bitset(
154
  const charT* str,
155
  typename basic_string<charT>::size_type n = basic_string<charT>::npos,
156
+ charT zero = charT('0'),
157
+ charT one = charT('1'));
158
  ```
159
 
160
+ *Effects:* As if by:
161
 
162
  ``` cpp
163
+ bitset(n == basic_string<charT>::npos
 
164
  ? basic_string<charT>(str)
165
  : basic_string<charT>(str, n),
166
  0, n, zero, one)
167
  ```
168
 
169
+ #### Members <a id="bitset.members">[[bitset.members]]</a>
170
 
171
  ``` cpp
172
  bitset<N>& operator&=(const bitset<N>& rhs) noexcept;
173
  ```
174
 
 
231
 
232
  ``` cpp
233
  bitset<N>& set(size_t pos, bool val = true);
234
  ```
235
 
 
 
 
236
  *Effects:* Stores a new value in the bit at position `pos` in `*this`.
237
+ If `val` is `true`, the stored value is one, otherwise it is zero.
238
 
239
  *Returns:* `*this`.
240
 
241
+ *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
242
+ position.
243
+
244
  ``` cpp
245
  bitset<N>& reset() noexcept;
246
  ```
247
 
248
  *Effects:* Resets all bits in `*this`.
 
251
 
252
  ``` cpp
253
  bitset<N>& reset(size_t pos);
254
  ```
255
 
 
 
 
256
  *Effects:* Resets the bit at position `pos` in `*this`.
257
 
258
  *Returns:* `*this`.
259
 
260
+ *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
261
+ position.
262
+
263
  ``` cpp
264
  bitset<N> operator~() const noexcept;
265
  ```
266
 
267
  *Effects:* Constructs an object `x` of class `bitset<N>` and initializes
 
279
 
280
  ``` cpp
281
  bitset<N>& flip(size_t pos);
282
  ```
283
 
 
 
 
284
  *Effects:* Toggles the bit at position `pos` in `*this`.
285
 
286
  *Returns:* `*this`.
287
 
288
+ *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
289
+ position.
290
+
291
  ``` cpp
292
  unsigned long to_ulong() const;
293
  ```
294
 
 
 
 
 
 
295
  *Returns:* `x`.
296
 
297
+ *Throws:* `overflow_error` if the integral value `x` corresponding to
298
+ the bits in `*this` cannot be represented as type `unsigned long`.
299
+
300
  ``` cpp
301
  unsigned long long to_ullong() const;
302
  ```
303
 
304
+ *Returns:* `x`.
305
+
306
  *Throws:* `overflow_error` if the integral value `x` corresponding to
307
  the bits in `*this` cannot be represented as type `unsigned long long`.
308
 
 
 
309
  ``` cpp
310
  template<class charT = char,
311
  class traits = char_traits<charT>,
312
  class Allocator = allocator<charT>>
313
  basic_string<charT, traits, Allocator>
 
341
  ```
342
 
343
  *Returns:* `true` if the value of each bit in `*this` equals the value
344
  of the corresponding bit in `rhs`.
345
 
 
 
 
 
 
 
346
  ``` cpp
347
  bool test(size_t pos) const;
348
  ```
349
 
 
 
 
350
  *Returns:* `true` if the bit at position `pos` in `*this` has the value
351
  one.
352
 
353
+ *Throws:* `out_of_range` if `pos` does not correspond to a valid bit
354
+ position.
355
+
356
  ``` cpp
357
  bool all() const noexcept;
358
  ```
359
 
360
  *Returns:* `count() == size()`.
 
385
 
386
  ``` cpp
387
  constexpr bool operator[](size_t pos) const;
388
  ```
389
 
390
+ *Preconditions:* `pos` is valid.
391
 
392
  *Returns:* `true` if the bit at position `pos` in `*this` has the value
393
  one, otherwise `false`.
394
 
395
  *Throws:* Nothing.
396
 
397
  ``` cpp
398
  bitset<N>::reference operator[](size_t pos);
399
  ```
400
 
401
+ *Preconditions:* `pos` is valid.
402
 
403
  *Returns:* An object of type `bitset<N>::reference` such that
404
  `(*this)[pos] == this->test(pos)`, and such that `(*this)[pos] = val` is
405
  equivalent to `this->set(pos, val)`.
406
 
407
  *Throws:* Nothing.
408
 
409
  *Remarks:* For the purpose of determining the presence of a data
410
+ race [[intro.multithread]], any access or update through the resulting
411
+ reference potentially accesses or modifies, respectively, the entire
412
+ underlying bitset.
413