From Jason Turner

[syncstream.osyncstream]

C++17 → C++20 5.1 KB 181 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/tmp147w3p_6/{from.md → to.md} +178 -0
tmp/tmp147w3p_6/{from.md → to.md} RENAMED
@@ -0,0 +1,178 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ### Class template `basic_osyncstream` <a id="syncstream.osyncstream">[[syncstream.osyncstream]]</a>
2
+
3
+ #### Overview <a id="syncstream.osyncstream.overview">[[syncstream.osyncstream.overview]]</a>
4
+
5
+ ``` cpp
6
+ namespace std {
7
+ template<class charT, class traits = char_traits<charT>, class Allocator = allocator<charT>>
8
+ class basic_osyncstream : public basic_ostream<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
+ using allocator_type = Allocator;
17
+ using streambuf_type = basic_streambuf<charT, traits>;
18
+ using syncbuf_type = basic_syncbuf<charT, traits, Allocator>;
19
+
20
+ // [syncstream.osyncstream.cons], construction and destruction
21
+ basic_osyncstream(streambuf_type*, const Allocator&);
22
+ explicit basic_osyncstream(streambuf_type* obuf)
23
+ : basic_osyncstream(obuf, Allocator()) {}
24
+ basic_osyncstream(basic_ostream<charT, traits>& os, const Allocator& allocator)
25
+ : basic_osyncstream(os.rdbuf(), allocator) {}
26
+ explicit basic_osyncstream(basic_ostream<charT, traits>& os)
27
+ : basic_osyncstream(os, Allocator()) {}
28
+ basic_osyncstream(basic_osyncstream&&) noexcept;
29
+ ~basic_osyncstream();
30
+
31
+ // assignment
32
+ basic_osyncstream& operator=(basic_osyncstream&&) noexcept;
33
+
34
+ // [syncstream.osyncstream.members], member functions
35
+ void emit();
36
+ streambuf_type* get_wrapped() const noexcept;
37
+ syncbuf_type* rdbuf() const noexcept { return const_cast<syncbuf_type*>(addressof(sb)); }
38
+
39
+ private:
40
+ syncbuf_type sb; // exposition only
41
+ };
42
+ }
43
+ ```
44
+
45
+ `Allocator` shall meet the *Cpp17Allocator* requirements (
46
+ [[cpp17.allocator]]).
47
+
48
+ [*Example 1*:
49
+
50
+ A named variable can be used within a block statement for streaming.
51
+
52
+ ``` cpp
53
+ {
54
+ osyncstream bout(cout);
55
+ bout << "Hello, ";
56
+ bout << "World!";
57
+ bout << endl; // flush is noted
58
+ bout << "and more!\n";
59
+ } // characters are transferred and cout is flushed
60
+ ```
61
+
62
+ — *end example*]
63
+
64
+ [*Example 2*:
65
+
66
+ A temporary object can be used for streaming within a single statement.
67
+
68
+ ``` cpp
69
+ osyncstream(cout) << "Hello, " << "World!" << '\n';
70
+ ```
71
+
72
+ In this example, `cout` is not flushed.
73
+
74
+ — *end example*]
75
+
76
+ #### Construction and destruction <a id="syncstream.osyncstream.cons">[[syncstream.osyncstream.cons]]</a>
77
+
78
+ ``` cpp
79
+ basic_osyncstream(streambuf_type* buf, const Allocator& allocator);
80
+ ```
81
+
82
+ *Effects:* Initializes `sb` from `buf` and `allocator`. Initializes the
83
+ base class with `basic_ostream<charT, traits>(addressof(sb))`.
84
+
85
+ [*Note 1*: The member functions of the provided stream buffer might be
86
+ called from `emit()` while a lock is held. Care should be taken to
87
+ ensure that this does not result in deadlock. — *end note*]
88
+
89
+ *Ensures:* `get_wrapped() == buf` is `true`.
90
+
91
+ ``` cpp
92
+ basic_osyncstream(basic_osyncstream&& other) noexcept;
93
+ ```
94
+
95
+ *Effects:* Move constructs the base class and `sb` from the
96
+ corresponding subobjects of `other`, and calls
97
+ `basic_ostream<charT, traits>::set_rdbuf(addressof(sb))`.
98
+
99
+ *Ensures:* The value returned by `get_wrapped()` is the value returned
100
+ by `os.get_wrapped()` prior to calling this constructor.
101
+ `nullptr == other.get_wrapped()` is `true`.
102
+
103
+ #### Member functions <a id="syncstream.osyncstream.members">[[syncstream.osyncstream.members]]</a>
104
+
105
+ ``` cpp
106
+ void emit();
107
+ ```
108
+
109
+ *Effects:* Calls `sb.emit()`. If that call returns `false`, calls
110
+ `setstate(ios_base::badbit)`.
111
+
112
+ [*Example 1*:
113
+
114
+ A flush on a `basic_osyncstream` does not flush immediately:
115
+
116
+ ``` cpp
117
+ {
118
+ osyncstream bout(cout);
119
+ bout << "Hello," << '\n'; // no flush
120
+ bout.emit(); // characters transferred; cout not flushed
121
+ bout << "World!" << endl; // flush noted; cout not flushed
122
+ bout.emit(); // characters transferred; cout flushed
123
+ bout << "Greetings." << '\n'; // no flush
124
+ } // characters transferred; cout not flushed
125
+ ```
126
+
127
+ — *end example*]
128
+
129
+ [*Example 2*:
130
+
131
+ The function `emit()` can be used to handle exceptions from operations
132
+ on the underlying stream.
133
+
134
+ ``` cpp
135
+ {
136
+ osyncstream bout(cout);
137
+ bout << "Hello, " << "World!" << '\n';
138
+ try {
139
+ bout.emit();
140
+ } catch (...) {
141
+ // handle exception
142
+ }
143
+ }
144
+ ```
145
+
146
+ — *end example*]
147
+
148
+ ``` cpp
149
+ streambuf_type* get_wrapped() const noexcept;
150
+ ```
151
+
152
+ *Returns:* `sb.get_wrapped()`.
153
+
154
+ [*Example 3*:
155
+
156
+ Obtaining the wrapped stream buffer with `get_wrapped()` allows wrapping
157
+ it again with an `osyncstream`. For example,
158
+
159
+ ``` cpp
160
+ {
161
+ osyncstream bout1(cout);
162
+ bout1 << "Hello, ";
163
+ {
164
+ osyncstream(bout1.get_wrapped()) << "Goodbye, " << "Planet!" << '\n';
165
+ }
166
+ bout1 << "World!" << '\n';
167
+ }
168
+ ```
169
+
170
+ produces the *uninterleaved* output
171
+
172
+ ``` text
173
+ Goodbye, Planet!
174
+ Hello, World!
175
+ ```
176
+
177
+ — *end example*]
178
+