From Jason Turner

[filebuf]

C++17 → C++20 9.7 KB 97 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/tmp7qr2m6zh/{from.md → to.md} +43 -42
tmp/tmp7qr2m6zh/{from.md → to.md} RENAMED
@@ -11,16 +11,16 @@ namespace std {
11
  using off_type = typename traits::off_type;
12
  using traits_type = traits;
13
 
14
  // [filebuf.cons], constructors/destructor
15
  basic_filebuf();
16
- basic_filebuf(const basic_filebuf& rhs) = delete;
17
  basic_filebuf(basic_filebuf&& rhs);
18
  virtual ~basic_filebuf();
19
 
20
  // [filebuf.assign], assign and swap
21
- basic_filebuf& operator=(const basic_filebuf& rhs) = delete;
22
  basic_filebuf& operator=(basic_filebuf&& rhs);
23
  void swap(basic_filebuf& rhs);
24
 
25
  // [filebuf.members], members
26
  bool is_open() const;
@@ -78,45 +78,44 @@ An instance of `basic_filebuf` behaves as described in  [[filebuf]]
78
  provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
79
  the behavior is undefined.
80
 
81
  In order to support file I/O and multibyte/wide character conversion,
82
  conversions are performed using members of a facet, referred to as
83
- `a_codecvt` in following sections, obtained as if by
84
 
85
  ``` cpp
86
  const codecvt<charT, char, typename traits::state_type>& a_codecvt =
87
  use_facet<codecvt<charT, char, typename traits::state_type>>(getloc());
88
  ```
89
 
90
- #### `basic_filebuf` constructors <a id="filebuf.cons">[[filebuf.cons]]</a>
91
 
92
  ``` cpp
93
  basic_filebuf();
94
  ```
95
 
96
- *Effects:* Constructs an object of class `basic_filebuf<charT, traits>`,
97
- initializing the base class with
98
- `basic_streambuf<charT, traits>()` ([[streambuf.cons]]).
99
 
100
- *Postconditions:* `is_open() == false`.
101
 
102
  ``` cpp
103
  basic_filebuf(basic_filebuf&& rhs);
104
  ```
105
 
106
- *Effects:* Move constructs from the rvalue `rhs`. It is
107
- *implementation-defined* whether the sequence pointers in `*this`
108
- (`eback()`, `gptr()`, `egptr()`, `pbase()`, `pptr()`, `epptr()`) obtain
109
- the values which `rhs` had. Whether they do or not, `*this` and `rhs`
110
- reference separate buffers (if any at all) after the construction.
111
- Additionally `*this` references the file which `rhs` did before the
112
- construction, and `rhs` references no file after the construction. The
113
- openmode, locale and any other state of `rhs` is also copied.
114
 
115
- *Postconditions:* Let `rhs_p` refer to the state of `rhs` just prior to
116
- this construction and let `rhs_a` refer to the state of `rhs` just after
117
- this construction.
118
 
119
  - `is_open() == rhs_p.is_open()`
120
  - `rhs_a.is_open() == false`
121
  - `gptr() - eback() == rhs_p.gptr() - rhs_p.eback()`
122
  - `egptr() - eback() == rhs_p.egptr() - rhs_p.eback()`
@@ -131,16 +130,16 @@ this construction.
131
 
132
  ``` cpp
133
  virtual ~basic_filebuf();
134
  ```
135
 
136
- *Effects:* Destroys an object of class `basic_filebuf<charT, traits>`.
137
- Calls `close()`. If an exception occurs during the destruction of the
138
- object, including the call to `close()`, the exception is caught but not
139
- rethrown (see  [[res.on.exception.handling]]).
140
 
141
- #### Assign and swap <a id="filebuf.assign">[[filebuf.assign]]</a>
142
 
143
  ``` cpp
144
  basic_filebuf& operator=(basic_filebuf&& rhs);
145
  ```
146
 
@@ -160,11 +159,11 @@ void swap(basic_filebuf& rhs);
160
  template<class charT, class traits>
161
  void swap(basic_filebuf<charT, traits>& x,
162
  basic_filebuf<charT, traits>& y);
163
  ```
164
 
165
- *Effects:* As if by `x.swap(y)`.
166
 
167
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
168
 
169
  ``` cpp
170
  bool is_open() const;
@@ -177,19 +176,20 @@ non-null value) and there has been no intervening call to close.
177
  basic_filebuf* open(const char* s, ios_base::openmode mode);
178
  basic_filebuf* open(const filesystem::path::value_type* s,
179
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
180
  ```
181
 
 
 
182
  *Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
183
- initializes the `filebuf` as required. It then opens a file, if
184
- possible, whose name is the NTBS`s` (as if by calling
185
- `fopen(s, modstr)`). The NTBS`modstr` is determined from
186
- `mode & ~ios_base::ate` as indicated in
187
- Table  [[tab:iostreams.file.open.modes]]. If `mode` is not some
188
- combination of flags shown in the table then the open fails.
189
 
190
- **Table: File open modes** <a id="tab:iostreams.file.open.modes">[tab:iostreams.file.open.modes]</a>
191
 
192
  | `binary` | `in` | `out` | `trunc` | `app` | | `stdio` equivalent |
193
  | -------- | ---- | ----- | ------- | ----- | --- | ------------------ |
194
  | | | + | | | `"w"` |
195
  | | | + | | + | `"a"` |
@@ -208,13 +208,14 @@ combination of flags shown in the table then the open fails.
208
  | + | + | + | + | | `"w+b"` |
209
  | + | + | + | | + | `"a+b"` |
210
  | + | + | | | + | `"a+b"` |
211
 
212
 
213
- If the open operation succeeds and `(mode & ios_base::ate) != 0`,
214
  positions the file to the end (as if by calling
215
- `fseek(file, 0, SEEK_END)`).[^40]
 
216
 
217
  If the repositioning operation fails, calls `close()` and returns a null
218
  pointer to indicate failure.
219
 
220
  *Returns:* `this` if successful, a null pointer otherwise.
@@ -243,20 +244,20 @@ or throws an exception, the function closes the file (as if by calling
243
  these calls throws an exception, the exception is caught and rethrown
244
  after closing the file.
245
 
246
  *Returns:* `this` on success, a null pointer otherwise.
247
 
248
- *Postconditions:* `is_open() == false`.
249
 
250
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
251
 
252
  ``` cpp
253
  streamsize showmanyc() override;
254
  ```
255
 
256
- *Effects:* Behaves the same as
257
- `basic_streambuf::showmanyc()` ([[streambuf.virtuals]]).
258
 
259
  *Remarks:* An implementation might well provide an overriding definition
260
  for this function signature if it can determine that more characters can
261
  be read from the input sequence.
262
 
@@ -313,11 +314,11 @@ sequence, if possible, in one of three ways:
313
  either the input sequence has a putback position available or the
314
  function makes a putback position available, decrements the next
315
  pointer for the input sequence, `gptr()`. Returns:
316
  `traits::not_eof(c)`.
317
 
318
- *Returns:* `traits::eof()` to indicate failure.
319
 
320
  *Remarks:* If `is_open() == false`, the function always fails.
321
 
322
  The function does not put back a character directly to the input
323
  sequence.
@@ -387,13 +388,13 @@ and write any unshift sequence. Next, seek to the new position: if
387
  operation was overflow or the put buffer is non-empty. “Write any
388
  unshift sequence” means, if `width` if less than zero then call
389
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
390
  resulting unshift sequence. The function determines one of three values
391
  for the argument `whence`, of type `int`, as indicated in
392
- Table  [[tab:iostreams.seekoff.effects]].
393
 
394
- **Table: `seekoff` effects** <a id="tab:iostreams.seekoff.effects">[tab:iostreams.seekoff.effects]</a>
395
 
396
  | `way` Value | `stdio` Equivalent |
397
  | ---------------- | ------------------ |
398
  | `basic_ios::beg` | `SEEK_SET` |
399
  | `basic_ios::cur` | `SEEK_CUR` |
@@ -442,13 +443,13 @@ characters to the file, then flushes the file as if by calling
442
 
443
  ``` cpp
444
  void imbue(const locale& loc) override;
445
  ```
446
 
447
- *Requires:* If the file is not positioned at its beginning and the
448
  encoding of the current locale as determined by `a_codecvt.encoding()`
449
- is state-dependent ([[locale.codecvt.virtuals]]) then that facet is the
450
  same as the corresponding facet of `loc`.
451
 
452
  *Effects:* Causes characters inserted or extracted after this call to be
453
  converted according to `loc` until another call of `imbue`.
454
 
 
11
  using off_type = typename traits::off_type;
12
  using traits_type = traits;
13
 
14
  // [filebuf.cons], constructors/destructor
15
  basic_filebuf();
16
+ basic_filebuf(const basic_filebuf&) = delete;
17
  basic_filebuf(basic_filebuf&& rhs);
18
  virtual ~basic_filebuf();
19
 
20
  // [filebuf.assign], assign and swap
21
+ basic_filebuf& operator=(const basic_filebuf&) = delete;
22
  basic_filebuf& operator=(basic_filebuf&& rhs);
23
  void swap(basic_filebuf& rhs);
24
 
25
  // [filebuf.members], members
26
  bool is_open() const;
 
78
  provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
79
  the behavior is undefined.
80
 
81
  In order to support file I/O and multibyte/wide character conversion,
82
  conversions are performed using members of a facet, referred to as
83
+ `a_codecvt` in following subclauses, obtained as if by
84
 
85
  ``` cpp
86
  const codecvt<charT, char, typename traits::state_type>& a_codecvt =
87
  use_facet<codecvt<charT, char, typename traits::state_type>>(getloc());
88
  ```
89
 
90
+ #### Constructors <a id="filebuf.cons">[[filebuf.cons]]</a>
91
 
92
  ``` cpp
93
  basic_filebuf();
94
  ```
95
 
96
+ *Effects:* Initializes the base class with
97
+ `basic_streambuf<charT, traits>()` [[streambuf.cons]].
 
98
 
99
+ *Ensures:* `is_open() == false`.
100
 
101
  ``` cpp
102
  basic_filebuf(basic_filebuf&& rhs);
103
  ```
104
 
105
+ *Effects:* It is *implementation-defined* whether the sequence pointers
106
+ in `*this` (`eback()`, `gptr()`, `egptr()`, `pbase()`, `pptr()`,
107
+ `epptr()`) obtain the values which `rhs` had. Whether they do or not,
108
+ `*this` and `rhs` reference separate buffers (if any at all) after the
109
+ construction. Additionally `*this` references the file which `rhs` did
110
+ before the construction, and `rhs` references no file after the
111
+ construction. The openmode, locale and any other state of `rhs` is also
112
+ copied.
113
 
114
+ *Ensures:* Let `rhs_p` refer to the state of `rhs` just prior to this
115
+ construction and let `rhs_a` refer to the state of `rhs` just after this
116
+ construction.
117
 
118
  - `is_open() == rhs_p.is_open()`
119
  - `rhs_a.is_open() == false`
120
  - `gptr() - eback() == rhs_p.gptr() - rhs_p.eback()`
121
  - `egptr() - eback() == rhs_p.egptr() - rhs_p.eback()`
 
130
 
131
  ``` cpp
132
  virtual ~basic_filebuf();
133
  ```
134
 
135
+ *Effects:* Calls `close()`. If an exception occurs during the
136
+ destruction of the object, including the call to `close()`, the
137
+ exception is caught but not rethrown
138
+ (see  [[res.on.exception.handling]]).
139
 
140
+ #### Assignment and swap <a id="filebuf.assign">[[filebuf.assign]]</a>
141
 
142
  ``` cpp
143
  basic_filebuf& operator=(basic_filebuf&& rhs);
144
  ```
145
 
 
159
  template<class charT, class traits>
160
  void swap(basic_filebuf<charT, traits>& x,
161
  basic_filebuf<charT, traits>& y);
162
  ```
163
 
164
+ *Effects:* Equivalent to: `x.swap(y)`.
165
 
166
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
167
 
168
  ``` cpp
169
  bool is_open() const;
 
176
  basic_filebuf* open(const char* s, ios_base::openmode mode);
177
  basic_filebuf* open(const filesystem::path::value_type* s,
178
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
179
  ```
180
 
181
+ *Preconditions:* `s` points to a NTCTS [[defns.ntcts]].
182
+
183
  *Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
184
+ initializes the `filebuf` as required. It then opens the file to which
185
+ `s` resolves, if possible, as if by a call to `fopen` with the second
186
+ argument determined from `mode & ~ios_base::ate` as indicated in
187
+ [[filebuf.open.modes]]. If `mode` is not some combination of flags shown
188
+ in the table then the open fails.
 
189
 
190
+ **Table: File open modes** <a id="filebuf.open.modes">[filebuf.open.modes]</a>
191
 
192
  | `binary` | `in` | `out` | `trunc` | `app` | | `stdio` equivalent |
193
  | -------- | ---- | ----- | ------- | ----- | --- | ------------------ |
194
  | | | + | | | `"w"` |
195
  | | | + | | + | `"a"` |
 
208
  | + | + | + | + | | `"w+b"` |
209
  | + | + | + | | + | `"a+b"` |
210
  | + | + | | | + | `"a+b"` |
211
 
212
 
213
+ If the open operation succeeds and `ios_base::ate` is set in `mode`,
214
  positions the file to the end (as if by calling
215
+ `fseek(file, 0, SEEK_END)`, where `file` is the pointer returned by
216
+ calling `fopen`). [^40]
217
 
218
  If the repositioning operation fails, calls `close()` and returns a null
219
  pointer to indicate failure.
220
 
221
  *Returns:* `this` if successful, a null pointer otherwise.
 
244
  these calls throws an exception, the exception is caught and rethrown
245
  after closing the file.
246
 
247
  *Returns:* `this` on success, a null pointer otherwise.
248
 
249
+ *Ensures:* `is_open() == false`.
250
 
251
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
252
 
253
  ``` cpp
254
  streamsize showmanyc() override;
255
  ```
256
 
257
+ *Effects:* Behaves the same as `basic_streambuf::showmanyc()`
258
+ [[streambuf.virtuals]].
259
 
260
  *Remarks:* An implementation might well provide an overriding definition
261
  for this function signature if it can determine that more characters can
262
  be read from the input sequence.
263
 
 
314
  either the input sequence has a putback position available or the
315
  function makes a putback position available, decrements the next
316
  pointer for the input sequence, `gptr()`. Returns:
317
  `traits::not_eof(c)`.
318
 
319
+ *Returns:* As specified above, or `traits::eof()` to indicate failure.
320
 
321
  *Remarks:* If `is_open() == false`, the function always fails.
322
 
323
  The function does not put back a character directly to the input
324
  sequence.
 
388
  operation was overflow or the put buffer is non-empty. “Write any
389
  unshift sequence” means, if `width` if less than zero then call
390
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
391
  resulting unshift sequence. The function determines one of three values
392
  for the argument `whence`, of type `int`, as indicated in
393
+ [[filebuf.seekoff]].
394
 
395
+ **Table: `seekoff` effects** <a id="filebuf.seekoff">[filebuf.seekoff]</a>
396
 
397
  | `way` Value | `stdio` Equivalent |
398
  | ---------------- | ------------------ |
399
  | `basic_ios::beg` | `SEEK_SET` |
400
  | `basic_ios::cur` | `SEEK_CUR` |
 
443
 
444
  ``` cpp
445
  void imbue(const locale& loc) override;
446
  ```
447
 
448
+ *Preconditions:* If the file is not positioned at its beginning and the
449
  encoding of the current locale as determined by `a_codecvt.encoding()`
450
+ is state-dependent [[locale.codecvt.virtuals]] then that facet is the
451
  same as the corresponding facet of `loc`.
452
 
453
  *Effects:* Causes characters inserted or extracted after this call to be
454
  converted according to `loc` until another call of `imbue`.
455