[output.streams] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpc_e_fnzy/{from.md → to.md} +63 -62

tmp/tmpc_e_fnzy/{from.md → to.md} RENAMED Viewed

@@ -19,13 +19,13 @@ namespace std {
   template<class charT, class traits = char_traits<charT>>
   class basic_ostream : virtual public basic_ios<charT, traits> {
   public:
     // types (inherited from basic_ios[ios])
     using char_type   = charT;
-    using int_type    = typename traits::int_type;
-    using pos_type    = typename traits::pos_type;
-    using off_type    = typename traits::off_type;
     using traits_type = traits;
     // [ostream.cons], constructor/destructor
     explicit basic_ostream(basic_streambuf<char_type, traits>* sb);
     virtual ~basic_ostream();
@@ -197,11 +197,11 @@ virtual ~basic_ostream();
 ``` cpp
 basic_ostream& operator=(basic_ostream&& rhs);
 ```
-*Effects:* Equivalent to: `swap(rhs)`.
 *Returns:* `*this`.
 ``` cpp
 void swap(basic_ostream& rhs);
@@ -237,28 +237,29 @@ explicit sentry(basic_ostream& os);
 If `os.good()` is nonzero, prepares for formatted or unformatted output.
 If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^29]
 If, after any preparation is completed, `os.good()` is `true`,
-`ok_ == true` otherwise, `ok_ == false`. During preparation, the
 constructor may call `setstate(failbit)` (which may throw
 `ios_base::failure` [[iostate.flags]]).[^30]
 ``` cpp
 ~sentry();
 ```
 If
 `(os.flags() & ios_base::unitbuf) && !uncaught_exceptions() && os.good()`
-is `true`, calls `os.rdbuf()->pubsync()`. If that function returns -1,
-sets `badbit` in `os.rdstate()` without propagating an exception.
 ``` cpp
 explicit operator bool() const;
 ```
-*Effects:* Returns `ok_`.
 ##### Seek members <a id="ostream.seeks">[[ostream.seeks]]</a>
 Each seek member function begins execution by constructing an object of
 class `sentry`. It returns by destroying the `sentry` object.
@@ -313,16 +314,16 @@ function is `*this`.
 The descriptions of the individual formatted output functions describe
 how they perform output and do not mention the `sentry` object.
 If a formatted output function of a stream `os` determines padding, it
 does so as follows. Given a `charT` character sequence `seq` where
-`charT` is the character type of the stream, if the length of `seq` is
-less than `os.width()`, then enough copies of `os.fill()` are added to
-this sequence as necessary to pad to a width of `os.width()` characters.
-If `(os.flags() & ios_base::adjustfield) == ios_base::left` is `true`,
-the fill characters are placed after the character sequence; otherwise,
-they are placed before the character sequence.
 ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
 ``` cpp
 basic_ostream& operator<<(bool val);
@@ -347,59 +348,52 @@ When `val` is of type `bool`, `long`, `unsigned long`, `long long`,
 `unsigned long long`, `double`, `long double`, or `const void*`, the
 formatting conversion occurs as if it performed the following code
 fragment:
 ``` cpp
-bool failed = use_facet<
- num_put<charT, ostreambuf_iterator<charT, traits>>
-    >(getloc()).put(*this, *this, fill(), val).failed();
 ```
 When `val` is of type `short` the formatting conversion occurs as if it
 performed the following code fragment:
 ``` cpp
 ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
-bool failed = use_facet<
- num_put<charT, ostreambuf_iterator<charT, traits>>
-    >(getloc()).put(*this, *this, fill(),
     baseflags == ios_base::oct || baseflags == ios_base::hex
       ? static_cast<long>(static_cast<unsigned short>(val))
       : static_cast<long>(val)).failed();
 ```
 When `val` is of type `int` the formatting conversion occurs as if it
 performed the following code fragment:
 ``` cpp
 ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
-bool failed = use_facet<
- num_put<charT, ostreambuf_iterator<charT, traits>>
-    >(getloc()).put(*this, *this, fill(),
     baseflags == ios_base::oct || baseflags == ios_base::hex
       ? static_cast<long>(static_cast<unsigned int>(val))
       : static_cast<long>(val)).failed();
 ```
 When `val` is of type `unsigned short` or `unsigned int` the formatting
 conversion occurs as if it performed the following code fragment:
 ``` cpp
-bool failed = use_facet<
- num_put<charT, ostreambuf_iterator<charT, traits>>
-    >(getloc()).put(*this, *this, fill(),
-      static_cast<unsigned long>(val)).failed();
 ```
 When `val` is of type `float` the formatting conversion occurs as if it
 performed the following code fragment:
 ``` cpp
-bool failed = use_facet<
- num_put<charT, ostreambuf_iterator<charT, traits>>
-    >(getloc()).put(*this, *this, fill(),
-      static_cast<double>(val)).failed();
 ```
 The first argument provides an object of the `ostreambuf_iterator<>`
 class which is an iterator for class `basic_ostream<>`. It bypasses
 `ostream`s and uses `streambuf`s directly. Class `locale` relies on
@@ -427,26 +421,22 @@ basic_ostream& operator<<(extended-floating-point-type val);
 *`extended-floating-point-type`* is less than or equal to that of
 `double`, the formatting conversion occurs as if it performed the
 following code fragment:
 ``` cpp
-bool failed = use_facet<
- num_put<charT, ostreambuf_iterator<charT, traits>>
-    >(getloc()).put(*this, *this, fill(),
-      static_cast<double>(val)).failed();
 ```
 Otherwise, if the floating-point conversion rank of
 *`extended-floating-point-type`* is less than or equal to that of
 `long double`, the formatting conversion occurs as if it performed the
 following code fragment:
 ``` cpp
-bool failed = use_facet<
- num_put<charT, ostreambuf_iterator<charT, traits>>
-    >(getloc()).put(*this, *this, fill(),
-      static_cast<long double>(val)).failed();
 ```
 Otherwise, an invocation of the operator function is conditionally
 supported with *implementation-defined* semantics.
@@ -540,15 +530,15 @@ template<class traits>
   basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, unsigned char c);
 ```
 *Effects:* Behaves as a formatted output
 function [[ostream.formatted.reqmts]] of `out`. Constructs a character
-sequence `seq`. If `c` has type `char` and the character type of the
-stream is not `char`, then `seq` consists of `out.widen(c)`; otherwise
-`seq` consists of `c`. Determines padding for `seq` as described
-in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`. Calls
-`os.width(0)`.
 *Returns:* `out`.
 ``` cpp
 template<class charT, class traits>
@@ -598,28 +588,38 @@ template<class... Args>
 *Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
 equivalent to:
 ``` cpp
-vprint_unicode(os, fmt.str, make_format_args(std::forward<Args>(args)...));
 ```
 Otherwise, equivalent to:
 ``` cpp
-vprint_nonunicode(os, fmt.str, make_format_args(std::forward<Args>(args)...));
 ```
 ``` cpp
 template<class... Args>
   void println(ostream& os, format_string<Args...> fmt, Args&&... args);
 ```
 *Effects:* Equivalent to:
 ``` cpp
-print(os, "{}\n", format(fmt, std::forward<Args>(args)...));
 ```
 ``` cpp
 void vprint_unicode(ostream& os, string_view fmt, format_args args);
 void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
@@ -631,28 +631,29 @@ function [[ostream.formatted.reqmts]] of `os`, except that:
 - failure to generate output is reported as specified below, and
 - any exception thrown by the call to `vformat` is propagated without
   regard to the value of `os.exceptions()` and without turning on
   `ios_base::badbit` in the error state of `os`.
-After constructing a `sentry` object, the function initializes an
-automatic variable via
 ``` cpp
 string out = vformat(os.getloc(), fmt, args);
 ```
-If the function is `vprint_unicode` and `os` is a stream that refers to
-a terminal capable of displaying Unicode which is determined in an
-implementation-defined manner, writes `out` to the terminal using the
-native Unicode API; if `out` contains invalid code units, the behavior
-is undefined and implementations are encouraged to diagnose it. If the
-native Unicode API is used, the function flushes `os` before writing
-`out`. Otherwise (if `os` is not such a stream or the function is
-`vprint_nonunicode`), inserts the character sequence \[`out.begin()`,
-`out.end()`) into `os`. If writing to the terminal or inserting into
-`os` fails, calls `os.setstate(ios_base::badbit)` (which may throw
-`ios_base::failure`).
 *Recommended practice:* For `vprint_unicode`, if invoking the native
 Unicode API requires transcoding, implementations should substitute
 invalid code units with U+fffd (replacement character) per the Unicode
 Standard, Chapter 3.9 ‘U+fffd‘ Substitution in Conversion.
@@ -713,11 +714,11 @@ object. If that object returns `true` when converted to a value of type
 [[iostate.flags]]). Otherwise, if the `sentry` object returns `false`,
 does nothing.
 *Returns:* `*this`.
-#### Standard manipulators <a id="ostream.manip">[[ostream.manip]]</a>
 Each instantiation of any of the function templates specified in this
 subclause is a designated addressable function [[namespace.std]].
 ``` cpp
@@ -759,11 +760,11 @@ of exposition, calls `buf->set_emit_on_sync(true)`. Otherwise this
 manipulator has no effect.
 [*Note 1*: To work around the issue that the `Allocator` template
 argument cannot be deduced, implementations can introduce an
 intermediate base class to `basic_syncbuf` that manages its
-`emit_on_sync` flag. — *end note*]
 *Returns:* `os`.
 ``` cpp
 template<class charT, class traits>

   template<class charT, class traits = char_traits<charT>>
   class basic_ostream : virtual public basic_ios<charT, traits> {
   public:
     // types (inherited from basic_ios[ios])
     using char_type   = charT;
+    using int_type    = traits::int_type;
+    using pos_type    = traits::pos_type;
+    using off_type    = traits::off_type;
     using traits_type = traits;
     // [ostream.cons], constructor/destructor
     explicit basic_ostream(basic_streambuf<char_type, traits>* sb);
     virtual ~basic_ostream();
 ``` cpp
 basic_ostream& operator=(basic_ostream&& rhs);
 ```
+*Effects:* Equivalent to `swap(rhs)`.
 *Returns:* `*this`.
 ``` cpp
 void swap(basic_ostream& rhs);
 If `os.good()` is nonzero, prepares for formatted or unformatted output.
 If `os.tie()` is not a null pointer, calls `os.tie()->flush()`.[^29]
 If, after any preparation is completed, `os.good()` is `true`,
+*`ok_`*` == true` otherwise, *`ok_`*` == false`. During preparation, the
 constructor may call `setstate(failbit)` (which may throw
 `ios_base::failure` [[iostate.flags]]).[^30]
 ``` cpp
 ~sentry();
 ```
 If
 `(os.flags() & ios_base::unitbuf) && !uncaught_exceptions() && os.good()`
+is `true`, calls `os.rdbuf()->pubsync()`. If that function returns -1 or
+exits via an exception, sets `badbit` in `os.rdstate()` without
+propagating an exception.
 ``` cpp
 explicit operator bool() const;
 ```
+*Effects:* Returns *ok\_*.
 ##### Seek members <a id="ostream.seeks">[[ostream.seeks]]</a>
 Each seek member function begins execution by constructing an object of
 class `sentry`. It returns by destroying the `sentry` object.
 The descriptions of the individual formatted output functions describe
 how they perform output and do not mention the `sentry` object.
 If a formatted output function of a stream `os` determines padding, it
 does so as follows. Given a `charT` character sequence `seq` where
+`charT` is the character container type of the stream, if the length of
+`seq` is less than `os.width()`, then enough copies of `os.fill()` are
+added to this sequence as necessary to pad to a width of `os.width()`
+characters. If `(os.flags() & ios_base::adjustfield) == ios_base::left`
+is `true`, the fill characters are placed after the character sequence;
+otherwise, they are placed before the character sequence.
 ##### Arithmetic inserters <a id="ostream.inserters.arithmetic">[[ostream.inserters.arithmetic]]</a>
 ``` cpp
 basic_ostream& operator<<(bool val);
 `unsigned long long`, `double`, `long double`, or `const void*`, the
 formatting conversion occurs as if it performed the following code
 fragment:
 ``` cpp
+bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
+ getloc()).put(*this, *this, fill(), val).failed();
 ```
 When `val` is of type `short` the formatting conversion occurs as if it
 performed the following code fragment:
 ``` cpp
 ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
+bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
+ getloc()).put(*this, *this, fill(),
     baseflags == ios_base::oct || baseflags == ios_base::hex
       ? static_cast<long>(static_cast<unsigned short>(val))
       : static_cast<long>(val)).failed();
 ```
 When `val` is of type `int` the formatting conversion occurs as if it
 performed the following code fragment:
 ``` cpp
 ios_base::fmtflags baseflags = ios_base::flags() & ios_base::basefield;
+bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
+ getloc()).put(*this, *this, fill(),
     baseflags == ios_base::oct || baseflags == ios_base::hex
       ? static_cast<long>(static_cast<unsigned int>(val))
       : static_cast<long>(val)).failed();
 ```
 When `val` is of type `unsigned short` or `unsigned int` the formatting
 conversion occurs as if it performed the following code fragment:
 ``` cpp
+bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
+ getloc()).put(*this, *this, fill(), static_cast<unsigned long>(val)).failed();
 ```
 When `val` is of type `float` the formatting conversion occurs as if it
 performed the following code fragment:
 ``` cpp
+bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
+ getloc()).put(*this, *this, fill(), static_cast<double>(val)).failed();
 ```
 The first argument provides an object of the `ostreambuf_iterator<>`
 class which is an iterator for class `basic_ostream<>`. It bypasses
 `ostream`s and uses `streambuf`s directly. Class `locale` relies on
 *`extended-floating-point-type`* is less than or equal to that of
 `double`, the formatting conversion occurs as if it performed the
 following code fragment:
 ``` cpp
+bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
+ getloc()).put(*this, *this, fill(), static_cast<double>(val)).failed();
 ```
 Otherwise, if the floating-point conversion rank of
 *`extended-floating-point-type`* is less than or equal to that of
 `long double`, the formatting conversion occurs as if it performed the
 following code fragment:
 ``` cpp
+bool failed = use_facet<num_put<charT, ostreambuf_iterator<charT, traits>>>(
+ getloc()).put(*this, *this, fill(), static_cast<long double>(val)).failed();
 ```
 Otherwise, an invocation of the operator function is conditionally
 supported with *implementation-defined* semantics.
   basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, unsigned char c);
 ```
 *Effects:* Behaves as a formatted output
 function [[ostream.formatted.reqmts]] of `out`. Constructs a character
+sequence `seq`. If `c` has type `char` and the character container type
+of the stream is not `char`, then `seq` consists of `out.widen(c)`;
+otherwise `seq` consists of `c`. Determines padding for `seq` as
+described in  [[ostream.formatted.reqmts]]. Inserts `seq` into `out`.
+Calls `os.width(0)`.
 *Returns:* `out`.
 ``` cpp
 template<class charT, class traits>
 *Effects:* If the ordinary literal encoding [[lex.charset]] is UTF-8,
 equivalent to:
 ``` cpp
+vprint_unicode(os, fmt.str, make_format_args(args...));
 ```
 Otherwise, equivalent to:
 ``` cpp
+vprint_nonunicode(os, fmt.str, make_format_args(args...));
 ```
 ``` cpp
 template<class... Args>
   void println(ostream& os, format_string<Args...> fmt, Args&&... args);
 ```
 *Effects:* Equivalent to:
 ``` cpp
+print(os, "{}\n", format(os.getloc(), fmt, std::forward<Args>(args)...));
+```
+``` cpp
+void println(ostream& os);
+```
+*Effects:* Equivalent to:
+``` cpp
+print(os, "\n");
 ```
 ``` cpp
 void vprint_unicode(ostream& os, string_view fmt, format_args args);
 void vprint_nonunicode(ostream& os, string_view fmt, format_args args);
 - failure to generate output is reported as specified below, and
 - any exception thrown by the call to `vformat` is propagated without
   regard to the value of `os.exceptions()` and without turning on
   `ios_base::badbit` in the error state of `os`.
+After constructing a `sentry` object, the function initializes a
+variable with automatic storage duration via
 ``` cpp
 string out = vformat(os.getloc(), fmt, args);
 ```
+- If the function is `vprint_unicode` and `os` is a stream that refers
+  to a terminal that is capable of displaying Unicode only via a native
+  Unicode API, which is determined in an implementation-defined manner,
+  flushes `os` and then writes `out` to the terminal using the native
+  Unicode API; if `out` contains invalid code units, the behavior is
+  undefined. Then establishes an observable
+  checkpoint [[intro.abstract]].
+- Otherwise inserts the character sequence \[`out.begin()`, `out.end()`)
+ into `os`.
+If writing to the terminal or inserting into `os` fails, calls
+`os.setstate(ios_base::badbit)` (which may throw `ios_base::failure`).
 *Recommended practice:* For `vprint_unicode`, if invoking the native
 Unicode API requires transcoding, implementations should substitute
 invalid code units with U+fffd (replacement character) per the Unicode
 Standard, Chapter 3.9 ‘U+fffd‘ Substitution in Conversion.
 [[iostate.flags]]). Otherwise, if the `sentry` object returns `false`,
 does nothing.
 *Returns:* `*this`.
+#### Standard `basic_ostream` manipulators <a id="ostream.manip">[[ostream.manip]]</a>
 Each instantiation of any of the function templates specified in this
 subclause is a designated addressable function [[namespace.std]].
 ``` cpp
 manipulator has no effect.
 [*Note 1*: To work around the issue that the `Allocator` template
 argument cannot be deduced, implementations can introduce an
 intermediate base class to `basic_syncbuf` that manages its
+*emit-on-sync* flag. — *end note*]
 *Returns:* `os`.
 ``` cpp
 template<class charT, class traits>

Diff to HTML by rtfpessoa