From Jason Turner

[print.fun]

C++23 → Trunk 5.2 KB 99 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/tmptobgqqk3/{from.md → to.md} +71 -22
tmp/tmptobgqqk3/{from.md → to.md} RENAMED
@@ -14,21 +14,27 @@ print(stdout, fmt, std::forward<Args>(args)...);
14
  ``` cpp
15
  template<class... Args>
16
  void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
17
  ```
18
 
19
- *Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
20
- equivalent to:
 
 
21
 
22
  ``` cpp
23
- vprint_unicode(stream, fmt.str, make_format_args(std::forward<Args>(args)...));
 
 
24
  ```
25
 
26
  Otherwise, equivalent to:
27
 
28
  ``` cpp
29
- vprint_nonunicode(stream, fmt.str, make_format_args(std::forward<Args>(args)...));
 
 
30
  ```
31
 
32
  ``` cpp
33
  template<class... Args>
34
  void println(format_string<Args...> fmt, Args&&... args);
@@ -38,19 +44,39 @@ template<class... Args>
38
 
39
  ``` cpp
40
  println(stdout, fmt, std::forward<Args>(args)...);
41
  ```
42
 
 
 
 
 
 
 
 
 
 
 
43
  ``` cpp
44
  template<class... Args>
45
  void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
46
  ```
47
 
48
  *Effects:* Equivalent to:
49
 
50
  ``` cpp
51
- print(stream, "{}\n", format(fmt, std::forward<Args>(args)...));
 
 
 
 
 
 
 
 
 
 
52
  ```
53
 
54
  ``` cpp
55
  void vprint_unicode(string_view fmt, format_args args);
56
  ```
@@ -59,37 +85,47 @@ void vprint_unicode(string_view fmt, format_args args);
59
 
60
  ``` cpp
61
  vprint_unicode(stdout, fmt, args);
62
  ```
63
 
 
 
 
 
 
 
 
 
 
 
 
64
  ``` cpp
65
  void vprint_unicode(FILE* stream, string_view fmt, format_args args);
66
  ```
67
 
68
  *Preconditions:* `stream` is a valid pointer to an output C stream.
69
 
70
- *Effects:* The function initializes an automatic variable via
 
 
71
 
72
- ``` cpp
73
- string out = vformat(fmt, args);
74
- ```
 
 
 
75
 
76
- If `stream` refers to a terminal capable of displaying Unicode, writes
77
- `out` to the terminal using the native Unicode API; if `out` contains
78
- invalid code units, the behavior is undefined and implementations are
79
- encouraged to diagnose it. Otherwise writes `out` to `stream` unchanged.
80
- If the native Unicode API is used, the function flushes `stream` before
81
- writing `out`.
82
 
83
- [*Note 1*: On POSIX and Windows, `stream` referring to a terminal means
84
- that, respectively, `isatty(fileno(stream))` and
85
- `GetConsoleMode(_get_osfhandle(_fileno(stream)), ...)` return
 
 
86
  nonzero. — *end note*]
87
 
88
- [*Note 2*: On Windows, the native Unicode API is
89
- `WriteConsoleW`. — *end note*]
90
-
91
  *Throws:* Any exception thrown by the call to `vformat`
92
  [[format.err.report]]. `system_error` if writing to the terminal or
93
  `stream` fails. May throw `bad_alloc`.
94
 
95
  *Recommended practice:* If invoking the native Unicode API requires
@@ -105,17 +141,30 @@ void vprint_nonunicode(string_view fmt, format_args args);
105
 
106
  ``` cpp
107
  vprint_nonunicode(stdout, fmt, args);
108
  ```
109
 
 
 
 
 
 
 
 
 
 
 
 
110
  ``` cpp
111
  void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
112
  ```
113
 
114
  *Preconditions:* `stream` is a valid pointer to an output C stream.
115
 
116
- *Effects:* Writes the result of `vformat(fmt, args)` to `stream`.
 
 
117
 
118
  *Throws:* Any exception thrown by the call to `vformat`
119
  [[format.err.report]]. `system_error` if writing to `stream` fails. May
120
  throw `bad_alloc`.
121
 
 
14
  ``` cpp
15
  template<class... Args>
16
  void print(FILE* stream, format_string<Args...> fmt, Args&&... args);
17
  ```
18
 
19
+ *Effects:* Let `locksafe` be
20
+ `(enable_nonlocking_formatter_optimization<remove_cvref_t<Args>> && ...)`.
21
+ If the ordinary literal encoding [[lex.charset]] is UTF-8, equivalent
22
+ to:
23
 
24
  ``` cpp
25
+ locksafe
26
+ ? vprint_unicode(stream, fmt.str, make_format_args(args...))
27
+ : vprint_unicode_buffered(stream, fmt.str, make_format_args(args...));
28
  ```
29
 
30
  Otherwise, equivalent to:
31
 
32
  ``` cpp
33
+ locksafe
34
+ ? vprint_nonunicode(stream, fmt.str, make_format_args(args...))
35
+ : vprint_nonunicode_buffered(stream, fmt.str, make_format_args(args...));
36
  ```
37
 
38
  ``` cpp
39
  template<class... Args>
40
  void println(format_string<Args...> fmt, Args&&... args);
 
44
 
45
  ``` cpp
46
  println(stdout, fmt, std::forward<Args>(args)...);
47
  ```
48
 
49
+ ``` cpp
50
+ void println();
51
+ ```
52
+
53
+ *Effects:* Equivalent to:
54
+
55
+ ``` cpp
56
+ println(stdout);
57
+ ```
58
+
59
  ``` cpp
60
  template<class... Args>
61
  void println(FILE* stream, format_string<Args...> fmt, Args&&... args);
62
  ```
63
 
64
  *Effects:* Equivalent to:
65
 
66
  ``` cpp
67
+ print(stream, runtime_format(string(fmt.get()) + '\n'), std::forward<Args>(args)...);
68
+ ```
69
+
70
+ ``` cpp
71
+ void println(FILE* stream);
72
+ ```
73
+
74
+ *Effects:* Equivalent to:
75
+
76
+ ``` cpp
77
+ print(stream, "\n");
78
  ```
79
 
80
  ``` cpp
81
  void vprint_unicode(string_view fmt, format_args args);
82
  ```
 
85
 
86
  ``` cpp
87
  vprint_unicode(stdout, fmt, args);
88
  ```
89
 
90
+ ``` cpp
91
+ void vprint_unicode_buffered(FILE* stream, string_view fmt, format_args args);
92
+ ```
93
+
94
+ *Effects:* Equivalent to:
95
+
96
+ ``` cpp
97
+ string out = vformat(fmt, args);
98
+ vprint_unicode(stream, "{}", make_format_args(out));
99
+ ```
100
+
101
  ``` cpp
102
  void vprint_unicode(FILE* stream, string_view fmt, format_args args);
103
  ```
104
 
105
  *Preconditions:* `stream` is a valid pointer to an output C stream.
106
 
107
+ *Effects:* Locks `stream`. Let `out` denote the character representation
108
+ of formatting arguments provided by `args` formatted according to
109
+ specifications given in `fmt`.
110
 
111
+ - If `stream` refers to a terminal that is capable of displaying Unicode
112
+ only via a native Unicode API, flushes `stream` and then writes `out`
113
+ to the terminal using the native Unicode API; if `out` contains
114
+ invalid code units, the behavior is undefined. Then establishes an
115
+ observable checkpoint [[intro.abstract]].
116
+ - Otherwise writes `out` to `stream` unchanged.
117
 
118
+ Unconditionally unlocks `stream` on function exit.
 
 
 
 
 
119
 
120
+ See also: ISO C 7.23.2.
121
+
122
+ [*Note 1*: On Windows the native Unicode API is `WriteConsoleW` and
123
+ `stream` referring to a terminal means that
124
+ `GetConsoleMode(_get_osfhandle(_fileno(stream)), ...)` returns
125
  nonzero. — *end note*]
126
 
 
 
 
127
  *Throws:* Any exception thrown by the call to `vformat`
128
  [[format.err.report]]. `system_error` if writing to the terminal or
129
  `stream` fails. May throw `bad_alloc`.
130
 
131
  *Recommended practice:* If invoking the native Unicode API requires
 
141
 
142
  ``` cpp
143
  vprint_nonunicode(stdout, fmt, args);
144
  ```
145
 
146
+ ``` cpp
147
+ void vprint_nonunicode_buffered(FILE* stream, string_view fmt, format_args args);
148
+ ```
149
+
150
+ *Effects:* Equivalent to:
151
+
152
+ ``` cpp
153
+ string out = vformat(fmt, args);
154
+ vprint_nonunicode("{}", make_format_args(out));
155
+ ```
156
+
157
  ``` cpp
158
  void vprint_nonunicode(FILE* stream, string_view fmt, format_args args);
159
  ```
160
 
161
  *Preconditions:* `stream` is a valid pointer to an output C stream.
162
 
163
+ *Effects:* While holding the lock on `stream`, writes the character
164
+ representation of formatting arguments provided by `args` formatted
165
+ according to specifications given in `fmt` to `stream`.
166
 
167
  *Throws:* Any exception thrown by the call to `vformat`
168
  [[format.err.report]]. `system_error` if writing to `stream` fails. May
169
  throw `bad_alloc`.
170