From Jason Turner

[filebuf]

C++23 → Trunk 7.2 KB 66 lines
Current Draft | LaTeX Source
Archived: C++23
Markdown: C++23 | Trunk
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpi9_myadj/{from.md → to.md} +36 -18
tmp/tmpi9_myadj/{from.md → to.md} RENAMED
@@ -6,14 +6,15 @@
6
  namespace std {
7
  template<class charT, class traits = char_traits<charT>>
8
  class basic_filebuf : public basic_streambuf<charT, traits> {
9
  public:
10
  using char_type = charT;
11
- using int_type = typename traits::int_type;
12
- using pos_type = typename traits::pos_type;
13
- using off_type = typename traits::off_type;
14
  using traits_type = traits;
 
15
 
16
  // [filebuf.cons], constructors/destructor
17
  basic_filebuf();
18
  basic_filebuf(const basic_filebuf&) = delete;
19
  basic_filebuf(basic_filebuf&& rhs);
@@ -27,32 +28,30 @@ namespace std {
27
  // [filebuf.members], members
28
  bool is_open() const;
29
  basic_filebuf* open(const char* s, ios_base::openmode mode);
30
  basic_filebuf* open(const filesystem::path::value_type* s,
31
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
32
- basic_filebuf* open(const string& s,
33
- ios_base::openmode mode);
34
- basic_filebuf* open(const filesystem::path& s,
35
- ios_base::openmode mode);
36
  basic_filebuf* close();
 
37
 
38
  protected:
39
  // [filebuf.virtuals], overridden virtual functions
40
  streamsize showmanyc() override;
41
  int_type underflow() override;
42
  int_type uflow() override;
43
  int_type pbackfail(int_type c = traits::eof()) override;
44
  int_type overflow (int_type c = traits::eof()) override;
45
 
46
- basic_streambuf<charT, traits>* setbuf(char_type* s,
47
- streamsize n) override;
48
  pos_type seekoff(off_type off, ios_base::seekdir way,
49
- ios_base::openmode which
50
- = ios_base::in | ios_base::out) override;
51
  pos_type seekpos(pos_type sp,
52
- ios_base::openmode which
53
- = ios_base::in | ios_base::out) override;
54
  int sync() override;
55
  void imbue(const locale& loc) override;
56
  };
57
  }
58
  ```
@@ -74,10 +73,19 @@ In particular:
74
 
75
  An instance of `basic_filebuf` behaves as described in  [[filebuf]]
76
  provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
77
  the behavior is undefined.
78
 
 
 
 
 
 
 
 
 
 
79
  In order to support file I/O and multibyte/wide character conversion,
80
  conversions are performed using members of a facet, referred to as
81
  `a_codecvt` in following subclauses, obtained as if by
82
 
83
  ``` cpp
@@ -156,11 +164,11 @@ void swap(basic_filebuf& rhs);
156
  ``` cpp
157
  template<class charT, class traits>
158
  void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
159
  ```
160
 
161
- *Effects:* Equivalent to: `x.swap(y)`.
162
 
163
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
164
 
165
  ``` cpp
166
  bool is_open() const;
@@ -173,11 +181,11 @@ non-null value) and there has been no intervening call to close.
173
  basic_filebuf* open(const char* s, ios_base::openmode mode);
174
  basic_filebuf* open(const filesystem::path::value_type* s,
175
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
176
  ```
177
 
178
- *Preconditions:* `s` points to a NTCTS [[defns.ntcts]].
179
 
180
  *Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
181
  initializes the `filebuf` as required. It then opens the file to which
182
  `s` resolves, if possible, as if by a call to `fopen` with the second
183
  argument determined from `mode & ~ios_base::ate` as indicated in
@@ -250,10 +258,18 @@ after closing the file.
250
 
251
  *Ensures:* `is_open() == false`.
252
 
253
  *Returns:* `this` on success, a null pointer otherwise.
254
 
 
 
 
 
 
 
 
 
255
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
256
 
257
  ``` cpp
258
  streamsize showmanyc() override;
259
  ```
@@ -275,11 +291,11 @@ that a sequence of characters is read from the input sequence as if by
275
  reading from the associated file into an internal buffer (`extern_buf`)
276
  and then as if by doing:
277
 
278
  ``` cpp
279
  char extern_buf[XSIZE];
280
- char* extern_end;
281
  charT intern_buf[ISIZE];
282
  charT* intern_end;
283
  codecvt_base::result r =
284
  a_codecvt.in(state, extern_buf, extern_buf+XSIZE, extern_end,
285
  intern_buf, intern_buf+ISIZE, intern_end);
@@ -340,11 +356,11 @@ int_type overflow(int_type c = traits::eof()) override;
340
  of “consuming characters” is performed by first converting as if by:
341
 
342
  ``` cpp
343
  charT* b = pbase();
344
  charT* p = pptr();
345
- charT* end;
346
  char xbuf[XSIZE];
347
  char* xbuf_end;
348
  codecvt_base::result r =
349
  a_codecvt.out(state, b, p, end, xbuf, xbuf+XSIZE, xbuf_end);
350
  ```
@@ -359,10 +375,12 @@ and then
359
  to `p`. If output fails, fail (without repeating).
360
  - Otherwise output from `xbuf` to `xbuf_end`, and fail if output fails.
361
  At this point if `b != p` and `b == end` (`xbuf` isn’t large enough)
362
  then increase `XSIZE` and repeat from the beginning.
363
 
 
 
364
  *Returns:* `traits::not_eof(c)` to indicate success, and `traits::eof()`
365
  to indicate failure. If `is_open() == false`, the function always fails.
366
 
367
  ``` cpp
368
  basic_streambuf* setbuf(char_type* s, streamsize n) override;
@@ -393,11 +411,11 @@ resultant stream position, if possible. If the positioning operation
393
  fails, or if the object cannot represent the resultant stream position,
394
  returns `pos_type(off_type(-1))`.
395
 
396
  *Remarks:* “The last operation was output” means either the last virtual
397
  operation was overflow or the put buffer is non-empty. “Write any
398
- unshift sequence” means, if `width` if less than zero then call
399
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
400
  resulting unshift sequence. The function determines one of three values
401
  for the argument `whence`, of type `int`, as indicated in
402
  [[filebuf.seekoff]].
403
 
 
6
  namespace std {
7
  template<class charT, class traits = char_traits<charT>>
8
  class basic_filebuf : public basic_streambuf<charT, traits> {
9
  public:
10
  using char_type = charT;
11
+ using int_type = traits::int_type;
12
+ using pos_type = traits::pos_type;
13
+ using off_type = traits::off_type;
14
  using traits_type = traits;
15
+ using native_handle_type = implementation-defined // type of native_handle_type; // see [file.native]
16
 
17
  // [filebuf.cons], constructors/destructor
18
  basic_filebuf();
19
  basic_filebuf(const basic_filebuf&) = delete;
20
  basic_filebuf(basic_filebuf&& rhs);
 
28
  // [filebuf.members], members
29
  bool is_open() const;
30
  basic_filebuf* open(const char* s, ios_base::openmode mode);
31
  basic_filebuf* open(const filesystem::path::value_type* s,
32
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
33
+ basic_filebuf* open(const string& s, ios_base::openmode mode);
34
+ basic_filebuf* open(const filesystem::path& s, ios_base::openmode mode);
 
 
35
  basic_filebuf* close();
36
+ native_handle_type native_handle() const noexcept;
37
 
38
  protected:
39
  // [filebuf.virtuals], overridden virtual functions
40
  streamsize showmanyc() override;
41
  int_type underflow() override;
42
  int_type uflow() override;
43
  int_type pbackfail(int_type c = traits::eof()) override;
44
  int_type overflow (int_type c = traits::eof()) override;
45
 
46
+ basic_streambuf<charT, traits>* setbuf(char_type* s, streamsize n) override;
47
+
48
  pos_type seekoff(off_type off, ios_base::seekdir way,
49
+ ios_base::openmode which = ios_base::in | ios_base::out) override;
 
50
  pos_type seekpos(pos_type sp,
51
+ ios_base::openmode which = ios_base::in | ios_base::out) override;
52
+
53
  int sync() override;
54
  void imbue(const locale& loc) override;
55
  };
56
  }
57
  ```
 
73
 
74
  An instance of `basic_filebuf` behaves as described in  [[filebuf]]
75
  provided `traits::pos_type` is `fpos<traits::{}state_type>`. Otherwise
76
  the behavior is undefined.
77
 
78
+ The file associated with a `basic_filebuf` has an associated value of
79
+ type `native_handle_type`, called the native handle [[file.native]] of
80
+ that file. This native handle can be obtained by calling the member
81
+ function `native_handle`.
82
+
83
+ For any opened `basic_filebuf f`, the native handle returned by
84
+ `f.native_handle()` is invalidated when `f.close()` is called, or `f` is
85
+ destroyed.
86
+
87
  In order to support file I/O and multibyte/wide character conversion,
88
  conversions are performed using members of a facet, referred to as
89
  `a_codecvt` in following subclauses, obtained as if by
90
 
91
  ``` cpp
 
164
  ``` cpp
165
  template<class charT, class traits>
166
  void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);
167
  ```
168
 
169
+ *Effects:* Equivalent to `x.swap(y)`.
170
 
171
  #### Member functions <a id="filebuf.members">[[filebuf.members]]</a>
172
 
173
  ``` cpp
174
  bool is_open() const;
 
181
  basic_filebuf* open(const char* s, ios_base::openmode mode);
182
  basic_filebuf* open(const filesystem::path::value_type* s,
183
  ios_base::openmode mode); // wide systems only; see [fstream.syn]
184
  ```
185
 
186
+ *Preconditions:* `s` points to an NTCTS [[defns.ntcts]].
187
 
188
  *Effects:* If `is_open() != false`, returns a null pointer. Otherwise,
189
  initializes the `filebuf` as required. It then opens the file to which
190
  `s` resolves, if possible, as if by a call to `fopen` with the second
191
  argument determined from `mode & ~ios_base::ate` as indicated in
 
258
 
259
  *Ensures:* `is_open() == false`.
260
 
261
  *Returns:* `this` on success, a null pointer otherwise.
262
 
263
+ ``` cpp
264
+ native_handle_type native_handle() const noexcept;
265
+ ```
266
+
267
+ *Preconditions:* `is_open()` is `true`.
268
+
269
+ *Returns:* The native handle associated with `*this`.
270
+
271
  #### Overridden virtual functions <a id="filebuf.virtuals">[[filebuf.virtuals]]</a>
272
 
273
  ``` cpp
274
  streamsize showmanyc() override;
275
  ```
 
291
  reading from the associated file into an internal buffer (`extern_buf`)
292
  and then as if by doing:
293
 
294
  ``` cpp
295
  char extern_buf[XSIZE];
296
+ const char* extern_end;
297
  charT intern_buf[ISIZE];
298
  charT* intern_end;
299
  codecvt_base::result r =
300
  a_codecvt.in(state, extern_buf, extern_buf+XSIZE, extern_end,
301
  intern_buf, intern_buf+ISIZE, intern_end);
 
356
  of “consuming characters” is performed by first converting as if by:
357
 
358
  ``` cpp
359
  charT* b = pbase();
360
  charT* p = pptr();
361
+ const charT* end;
362
  char xbuf[XSIZE];
363
  char* xbuf_end;
364
  codecvt_base::result r =
365
  a_codecvt.out(state, b, p, end, xbuf, xbuf+XSIZE, xbuf_end);
366
  ```
 
375
  to `p`. If output fails, fail (without repeating).
376
  - Otherwise output from `xbuf` to `xbuf_end`, and fail if output fails.
377
  At this point if `b != p` and `b == end` (`xbuf` isn’t large enough)
378
  then increase `XSIZE` and repeat from the beginning.
379
 
380
+ Then establishes an observable checkpoint [[intro.abstract]].
381
+
382
  *Returns:* `traits::not_eof(c)` to indicate success, and `traits::eof()`
383
  to indicate failure. If `is_open() == false`, the function always fails.
384
 
385
  ``` cpp
386
  basic_streambuf* setbuf(char_type* s, streamsize n) override;
 
411
  fails, or if the object cannot represent the resultant stream position,
412
  returns `pos_type(off_type(-1))`.
413
 
414
  *Remarks:* “The last operation was output” means either the last virtual
415
  operation was overflow or the put buffer is non-empty. “Write any
416
+ unshift sequence” means, if `width` is less than zero then call
417
  `a_codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_end)` and output the
418
  resulting unshift sequence. The function determines one of three values
419
  for the argument `whence`, of type `int`, as indicated in
420
  [[filebuf.seekoff]].
421