[rand.req] - C++23 → Trunk

Files changed (1) hide show

tmp/tmpgtm91sne/{from.md → to.md} +98 -18

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

@@ -1,11 +1,10 @@
 ### Requirements <a id="rand.req">[[rand.req]]</a>
 #### General requirements <a id="rand.req.genl">[[rand.req.genl]]</a>
-Throughout this subclause [[rand]], the effect of instantiating a
-template:
 - that has a template type parameter named `Sseq` is undefined unless
   the corresponding template argument is cv-unqualified and meets the
   requirements of seed sequence [[rand.req.seedseq]].
 - that has a template type parameter named `URBG` is undefined unless
@@ -24,18 +23,18 @@ template:
 - that has a template type parameter named `UIntType` is undefined
   unless the corresponding template argument is cv-unqualified and is
   one of `unsigned short`, `unsigned int`, `unsigned long`, or
   `unsigned long long`.
-Throughout this subclause [[rand]], phrases of the form “`x` is an
-iterator of a specific kind” shall be interpreted as equivalent to the
-more formal requirement that “`x` is a value of a type meeting the
-requirements of the specified iterator type”.
-Throughout this subclause [[rand]], any constructor that can be called
-with a single argument and that meets a requirement specified in this
-subclause shall be declared `explicit`.
 #### Seed sequence requirements <a id="rand.req.seedseq">[[rand.req.seedseq]]</a>
 A *seed sequence* is an object that consumes a sequence of
 integer-valued data and produces a requested number of unsigned integer
@@ -46,12 +45,12 @@ streams of random variates. This can be useful, for example, in
 applications requiring large numbers of random number
 engines. — *end note*]
 A class `S` meets the requirements of a seed sequence if the expressions
 shown in [[rand.req.seedseq]] are valid and have the indicated
-semantics, and if `S` also meets all other requirements of this
-subclause [[rand.req.seedseq]]. In that Table and throughout this
 subclause:
 - `T` is the type named by `S`’s associated `result_type`;
 - `q` is a value of type `S` and `r` is a value of type `S` or
   `const S`;
@@ -118,12 +117,12 @@ suitable `operator>>`.
 A class `E` that meets the requirements of a uniform random bit
 generator [[rand.req.urng]] also meets the requirements of a *random
 number engine* if the expressions shown in [[rand.req.eng]] are valid
 and have the indicated semantics, and if `E` also meets all other
-requirements of this subclause [[rand.req.eng]]. In that Table and
-throughout this subclause:
 - `T` is the type named by `E`’s associated `result_type`;
 - `e` is a value of `E`, `v` is an lvalue of `E`, `x` and `y` are
   (possibly const) values of `E`;
 - `s` is a value of `T`;
@@ -141,10 +140,56 @@ where `charT` and `traits` are constrained according to [[strings]] and
 `E` shall meet the *Cpp17CopyConstructible* (
 [[cpp17.copyconstructible]]) and *Cpp17CopyAssignable* (
 [[cpp17.copyassignable]]) requirements. These operations shall each be
 of complexity no worse than 𝑂(\text{size of state}).
 #### Random number engine adaptor requirements <a id="rand.req.adapt">[[rand.req.adapt]]</a>
 A *random number engine adaptor* (commonly shortened to *adaptor*) `a`
 of type `A` is a random number engine that takes values produced by some
 other random number engine, and applies an algorithm to those values in
@@ -229,12 +274,12 @@ P(zᵢ |{`p`}), to denote a distribution’s parameters `p` taken as a
 whole.
 A class `D` meets the requirements of a *random number distribution* if
 the expressions shown in [[rand.req.dist]] are valid and have the
 indicated semantics, and if `D` and its associated types also meet all
-other requirements of this subclause [[rand.req.dist]]. In that Table
-and throughout this subclause,
 - `T` is the type named by `D`’s associated `result_type`;
 - `P` is the type named by `D`’s associated `param_type`;
 - `d` is a value of `D`, and `x` and `y` are (possibly const) values of
   `D`;
@@ -266,13 +311,12 @@ representation is restored into the same or a different object `y` of
 the same type using `is >> y`, repeated invocations of `y(g)` shall
 produce the same sequence of numbers as would repeated invocations of
 `x(g)`.
 It is unspecified whether `D::param_type` is declared as a (nested)
-`class` or via a `typedef`. In this subclause [[rand]], declarations of
-`D::param_type` are in the form of `typedef`s for convenience of
-exposition only.
 `P` shall meet the *Cpp17CopyConstructible* (
 [[cpp17.copyconstructible]]), *Cpp17CopyAssignable* (
 [[cpp17.copyassignable]]), and *Cpp17EqualityComparable* (
 [[cpp17.equalitycomparable]]) requirements.
@@ -289,5 +333,41 @@ the identical name, type, and semantics.
 ``` cpp
 using distribution_type =  D;
 ```

 ### Requirements <a id="rand.req">[[rand.req]]</a>
 #### General requirements <a id="rand.req.genl">[[rand.req.genl]]</a>
+Throughout [[rand]], the effect of instantiating a template:
 - that has a template type parameter named `Sseq` is undefined unless
   the corresponding template argument is cv-unqualified and meets the
   requirements of seed sequence [[rand.req.seedseq]].
 - that has a template type parameter named `URBG` is undefined unless
 - that has a template type parameter named `UIntType` is undefined
   unless the corresponding template argument is cv-unqualified and is
   one of `unsigned short`, `unsigned int`, `unsigned long`, or
   `unsigned long long`.
+Throughout [[rand]], phrases of the form “`x` is an iterator of a
+specific kind” shall be interpreted as equivalent to the more formal
+requirement that “`x` is a value of a type meeting the requirements of
+the specified iterator type”.
+Throughout [[rand]], any constructor that can be called with a single
+argument and that meets a requirement specified in this subclause shall
+be declared `explicit`.
 #### Seed sequence requirements <a id="rand.req.seedseq">[[rand.req.seedseq]]</a>
 A *seed sequence* is an object that consumes a sequence of
 integer-valued data and produces a requested number of unsigned integer
 applications requiring large numbers of random number
 engines. — *end note*]
 A class `S` meets the requirements of a seed sequence if the expressions
 shown in [[rand.req.seedseq]] are valid and have the indicated
+semantics, and if `S` also meets all other requirements of
+[[rand.req.seedseq]]. In [[rand.req.seedseq]] and throughout this
 subclause:
 - `T` is the type named by `S`’s associated `result_type`;
 - `q` is a value of type `S` and `r` is a value of type `S` or
   `const S`;
 A class `E` that meets the requirements of a uniform random bit
 generator [[rand.req.urng]] also meets the requirements of a *random
 number engine* if the expressions shown in [[rand.req.eng]] are valid
 and have the indicated semantics, and if `E` also meets all other
+requirements of [[rand.req.eng]]. In [[rand.req.eng]] and throughout
+this subclause:
 - `T` is the type named by `E`’s associated `result_type`;
 - `e` is a value of `E`, `v` is an lvalue of `E`, `x` and `y` are
   (possibly const) values of `E`;
 - `s` is a value of `T`;
 `E` shall meet the *Cpp17CopyConstructible* (
 [[cpp17.copyconstructible]]) and *Cpp17CopyAssignable* (
 [[cpp17.copyassignable]]) requirements. These operations shall each be
 of complexity no worse than 𝑂(\text{size of state}).
+On hosted implementations, the following expressions are well-formed and
+have the specified semantics.
+``` cpp
+os << x
+```
+*Effects:* With `os.`*`fmtflags`* set to `ios_base::dec|ios_base::left`
+and the fill character set to the space character, writes to `os` the
+textual representation of `x`’s current state. In the output, adjacent
+numbers are separated by one or more space characters.
+*Ensures:* The `os.`*`fmtflags`* and fill character are unchanged.
+*Result:* reference to the type of `os`.
+*Returns:* `os`.
+*Complexity:* 𝑂(size of state)
+``` cpp
+is >> v
+```
+*Preconditions:* `is` provides a textual representation that was
+previously written using an output stream whose imbued locale was the
+same as that of `is`, and whose type’s template specialization arguments
+`charT` and `traits` were respectively the same as those of `is`.
+*Effects:* With `is.`*`fmtflags`* set to `ios_base::dec`, sets `v`’s
+state as determined by reading its textual representation from `is`. If
+bad input is encountered, ensures that `v`’s state is unchanged by the
+operation and calls `is.setstate(ios_base::failbit)` (which may throw
+`ios_base::failure` [[iostate.flags]]). If a textual representation
+written via `os << x` was subsequently read via `is >> v`, then `x == v`
+provided that there have been no intervening invocations of `x` or of
+`v`.
+*Ensures:* The `is.`*`fmtflags`* are unchanged.
+*Result:* reference to the type of `is`.
+*Returns:* `is`.
+*Complexity:* 𝑂(size of state)
 #### Random number engine adaptor requirements <a id="rand.req.adapt">[[rand.req.adapt]]</a>
 A *random number engine adaptor* (commonly shortened to *adaptor*) `a`
 of type `A` is a random number engine that takes values produced by some
 other random number engine, and applies an algorithm to those values in
 whole.
 A class `D` meets the requirements of a *random number distribution* if
 the expressions shown in [[rand.req.dist]] are valid and have the
 indicated semantics, and if `D` and its associated types also meet all
+other requirements of [[rand.req.dist]]. In [[rand.req.dist]] and
+throughout this subclause,
 - `T` is the type named by `D`’s associated `result_type`;
 - `P` is the type named by `D`’s associated `param_type`;
 - `d` is a value of `D`, and `x` and `y` are (possibly const) values of
   `D`;
 the same type using `is >> y`, repeated invocations of `y(g)` shall
 produce the same sequence of numbers as would repeated invocations of
 `x(g)`.
 It is unspecified whether `D::param_type` is declared as a (nested)
+`class` or via a `typedef`. In [[rand]], declarations of `D::param_type`
+are in the form of `typedef`s for convenience of exposition only.
 `P` shall meet the *Cpp17CopyConstructible* (
 [[cpp17.copyconstructible]]), *Cpp17CopyAssignable* (
 [[cpp17.copyassignable]]), and *Cpp17EqualityComparable* (
 [[cpp17.equalitycomparable]]) requirements.
 ``` cpp
 using distribution_type =  D;
 ```
+On hosted implementations, the following expressions are well-formed and
+have the specified semantics.
+``` cpp
+os << x
+```
+*Effects:* Writes to `os` a textual representation for the parameters
+and the additional internal data of `x`.
+*Ensures:* The `os.`*`fmtflags`* and fill character are unchanged.
+*Result:* reference to the type of `os`.
+*Returns:* `os`.
+``` cpp
+is >> d
+```
+*Preconditions:* `is` provides a textual representation that was
+previously written using an `os` whose imbued locale and whose type’s
+template specialization arguments `charT` and `traits` were the same as
+those of `is`.
+*Effects:* Restores from `is` the parameters and additional internal
+data of the lvalue `d`. If bad input is encountered, ensures that `d` is
+unchanged by the operation and calls `is.setstate(ios_base::failbit)`
+(which may throw `ios_base::failure` [[iostate.flags]]).
+*Ensures:* The `is.`*`fmtflags`* are unchanged.
+*Result:* reference to the type of `is`.
+*Returns:* `is`.

Diff to HTML by rtfpessoa