[depr.str.strstreams] - C++23 → Trunk

Files changed (1) hide show

tmp/tmplohfrk6f/{from.md → to.md} +0 -637

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

@@ -1,637 +0,0 @@
-## `char*` streams <a id="depr.str.strstreams">[[depr.str.strstreams]]</a>
-### Header `<strstream>` synopsis <a id="depr.strstream.syn">[[depr.strstream.syn]]</a>
-The header `<strstream>` defines types that associate stream buffers
-with character array objects and assist reading and writing such
-objects.
-``` cpp
-namespace std {
-  class strstreambuf;
-  class istrstream;
-  class ostrstream;
-  class strstream;
-}
-```
-### Class `strstreambuf` <a id="depr.strstreambuf">[[depr.strstreambuf]]</a>
-#### General <a id="depr.strstreambuf.general">[[depr.strstreambuf.general]]</a>
-``` cpp
-namespace std {
-  class strstreambuf : public basic_streambuf<char> {
-  public:
-    strstreambuf() : strstreambuf(0) {}
-    explicit strstreambuf(streamsize alsize_arg);
-    strstreambuf(void* (*palloc_arg)(size_t), void (*pfree_arg)(void*));
-    strstreambuf(char* gnext_arg, streamsize n, char* pbeg_arg = nullptr);
-    strstreambuf(const char* gnext_arg, streamsize n);
-    strstreambuf(signed char* gnext_arg, streamsize n,
-                 signed char* pbeg_arg = nullptr);
-    strstreambuf(const signed char* gnext_arg, streamsize n);
-    strstreambuf(unsigned char* gnext_arg, streamsize n,
-                 unsigned char* pbeg_arg = nullptr);
-    strstreambuf(const unsigned char* gnext_arg, streamsize n);
-    virtual ~strstreambuf();
-    void  freeze(bool freezefl = true);
-    char* str();
-    int   pcount();
-  protected:
-    int_type overflow (int_type c = EOF) override;
-    int_type pbackfail(int_type c = EOF) override;
-    int_type underflow() override;
-    pos_type seekoff(off_type off, ios_base::seekdir way,
-                     ios_base::openmode which = ios_base::in | ios_base::out) override;
-    pos_type seekpos(pos_type sp,
-                     ios_base::openmode which = ios_base::in | ios_base::out) override;
-    streambuf* setbuf(char* s, streamsize n) override;
-  private:
-    using strstate = T1;                // exposition only
-    static const strstate allocated;    // exposition only
-    static const strstate constant;     // exposition only
-    static const strstate dynamic;      // exposition only
-    static const strstate frozen;       // exposition only
-    strstate strmode;                   // exposition only
-    streamsize alsize;                  // exposition only
-    void* (*palloc)(size_t);            // exposition only
-    void (*pfree)(void*);               // exposition only
-  };
-}
-```
-The class `strstreambuf` associates the input sequence, and possibly the
-output sequence, with an object of some *character* array type, whose
-elements store arbitrary values. The array object has several
-attributes.
-[*Note 1*:
-For the sake of exposition, these are represented as elements of a
-bitmask type (indicated here as `T1`) called `strstate`. The elements
-are:
-- `allocated`, set when a dynamic array object has been allocated, and
-  hence will be freed by the destructor for the `strstreambuf` object;
-- `constant`, set when the array object has `const` elements, so the
-  output sequence cannot be written;
-- `dynamic`, set when the array object is allocated (or reallocated) as
-  necessary to hold a character sequence that can change in length;
-- `frozen`, set when the program has requested that the array object not
-  be altered, reallocated, or freed.
-— *end note*]
-[*Note 2*:
-For the sake of exposition, the maintained data is presented here as:
-- `strstate strmode`, the attributes of the array object associated with
-  the `strstreambuf` object;
-- `int alsize`, the suggested minimum size for a dynamic array object;
-- `void* (*palloc)(size_t)`, points to the function to call to allocate
-  a dynamic array object;
-- `void (*pfree)(void*)`, points to the function to call to free a
-  dynamic array object.
-— *end note*]
-Each object of class `strstreambuf` has a *seekable area*, delimited by
-the pointers `seeklow` and `seekhigh`. If `gnext` is a null pointer, the
-seekable area is undefined. Otherwise, `seeklow` equals `gbeg` and
-`seekhigh` is either `pend`, if `pend` is not a null pointer, or `gend`.
-#### `strstreambuf` constructors <a id="depr.strstreambuf.cons">[[depr.strstreambuf.cons]]</a>
-``` cpp
-explicit strstreambuf(streamsize alsize_arg);
-```
-*Effects:* Initializes the base class with `streambuf()`. The
-postconditions of this function are indicated in
-[[depr.strstreambuf.cons.sz]].
-**Table: `strstreambuf(streamsize)` effects** <a id="depr.strstreambuf.cons.sz">[depr.strstreambuf.cons.sz]</a>
-| Element   | Value          |
-| --------- | -------------- |
-| `strmode` | `dynamic`      |
-| `alsize`  | `alsize_arg`   |
-| `palloc`  | a null pointer |
-| `pfree`   | a null pointer |
-``` cpp
-strstreambuf(void* (*palloc_arg)(size_t), void (*pfree_arg)(void*));
-```
-*Effects:* Initializes the base class with `streambuf()`. The
-postconditions of this function are indicated in
-[[depr.strstreambuf.cons.alloc]].
-**Table: `strstreambuf(void* (*)(size_t), void (*)(void*))` effects** <a id="depr.strstreambuf.cons.alloc">[depr.strstreambuf.cons.alloc]</a>
-| Element   | Value                |
-| --------- | -------------------- |
-| `strmode` | `dynamic`            |
-| `alsize`  | an unspecified value |
-| `palloc`  | `palloc_arg`         |
-| `pfree`   | `pfree_arg`          |
-``` cpp
-strstreambuf(char* gnext_arg, streamsize n, char* pbeg_arg = nullptr);
-strstreambuf(signed char* gnext_arg, streamsize n,
-             signed char* pbeg_arg = nullptr);
-strstreambuf(unsigned char* gnext_arg, streamsize n,
-             unsigned char* pbeg_arg = nullptr);
-```
-*Effects:* Initializes the base class with `streambuf()`. The
-postconditions of this function are indicated in
-[[depr.strstreambuf.cons.ptr]].
-**Table: `strstreambuf(charT*, streamsize, charT*)` effects** <a id="depr.strstreambuf.cons.ptr">[depr.strstreambuf.cons.ptr]</a>
-| Element   | Value                |
-| --------- | -------------------- |
-| `strmode` | 0                    |
-| `alsize`  | an unspecified value |
-| `palloc`  | a null pointer       |
-| `pfree`   | a null pointer       |
-`gnext_arg` shall point to the first element of an array object whose
-number of elements `N` is determined as follows:
-- If `n > 0`, `N` is `n`.
-- If `n == 0`, `N` is `std::strlen(gnext_arg)`.
-- If `n < 0`, `N` is `INT_MAX`.[^1]
-If `pbeg_arg` is a null pointer, the function executes:
-``` cpp
-setg(gnext_arg, gnext_arg, gnext_arg + N);
-```
-Otherwise, the function executes:
-``` cpp
-setg(gnext_arg, gnext_arg, pbeg_arg);
-setp(pbeg_arg,  pbeg_arg + N);
-```
-``` cpp
-strstreambuf(const char* gnext_arg, streamsize n);
-strstreambuf(const signed char* gnext_arg, streamsize n);
-strstreambuf(const unsigned char* gnext_arg, streamsize n);
-```
-*Effects:* Behaves the same as `strstreambuf((char*)gnext_arg,n)`,
-except that the constructor also sets `constant` in `strmode`.
-``` cpp
-virtual ~strstreambuf();
-```
-*Effects:* Destroys an object of class `strstreambuf`. The function
-frees the dynamically allocated array object only if
-`(strmode & allocated) != 0` and `(strmode & frozen) == 0`.
-([[depr.strstreambuf.virtuals]] describes how a dynamically allocated
-array object is freed.)
-#### Member functions <a id="depr.strstreambuf.members">[[depr.strstreambuf.members]]</a>
-``` cpp
-void freeze(bool freezefl = true);
-```
-*Effects:* If `strmode & dynamic` is nonzero, alters the freeze status
-of the dynamic array object as follows:
-- If `freezefl` is `true`, the function sets `frozen` in `strmode`.
-- Otherwise, it clears `frozen` in `strmode`.
-``` cpp
-char* str();
-```
-*Effects:* Calls `freeze()`, then returns the beginning pointer for the
-input sequence, `gbeg`.
-*Remarks:* The return value can be a null pointer.
-``` cpp
-int pcount() const;
-```
-*Effects:* If the next pointer for the output sequence, `pnext`, is a
-null pointer, returns zero. Otherwise, returns the current effective
-length of the array object as the next pointer minus the beginning
-pointer for the output sequence, `pnext - pbeg`.
-#### `strstreambuf` overridden virtual functions <a id="depr.strstreambuf.virtuals">[[depr.strstreambuf.virtuals]]</a>
-``` cpp
-int_type overflow(int_type c = EOF) override;
-```
-*Effects:* Appends the character designated by `c` to the output
-sequence, if possible, in one of two ways:
-- If `c != EOF` and if either the output sequence has a write position
-  available or the function makes a write position available (as
-  described below), assigns `c` to `*pnext++`. Returns
-  `(unsigned char)c`.
-- If `c == EOF`, there is no character to append. Returns a value other
-  than `EOF`.
-Returns `EOF` to indicate failure.
-*Remarks:* The function can alter the number of write positions
-available as a result of any call.
-To make a write position available, the function reallocates (or
-initially allocates) an array object with a sufficient number of
-elements `n` to hold the current array object (if any), plus at least
-one additional write position. How many additional write positions are
-made available is otherwise unspecified. If `palloc` is not a null
-pointer, the function calls `(*palloc)(n)` to allocate the new dynamic
-array object. Otherwise, it evaluates the expression `new charT[n]`. In
-either case, if the allocation fails, the function returns `EOF`.
-Otherwise, it sets `allocated` in `strmode`.
-To free a previously existing dynamic array object whose first element
-address is `p`: If `pfree` is not a null pointer, the function calls
-`(*pfree)(p)`. Otherwise, it evaluates the expression `delete[]p`.
-If `(strmode & dynamic) == 0`, or if `(strmode & frozen) != 0`, the
-function cannot extend the array (reallocate it with greater length) to
-make a write position available.
-*Recommended practice:* An implementation should consider `alsize` in
-making the decision how many additional write positions to make
-available.
-``` cpp
-int_type pbackfail(int_type c = EOF) override;
-```
-Puts back the character designated by `c` to the input sequence, if
-possible, in one of three ways:
-- If `c != EOF`, if the input sequence has a putback position available,
-  and if `(char)c == gnext[-1]`, assigns `gnext - 1` to `gnext`. Returns
-  `c`.
-- If `c != EOF`, if the input sequence has a putback position available,
-  and if `strmode & constant` is zero, assigns `c` to `*–gnext`. Returns
-  `c`.
-- If `c == EOF` and if the input sequence has a putback position
-  available, assigns `gnext - 1` to `gnext`. Returns a value other than
-  `EOF`.
-Returns `EOF` to indicate failure.
-*Remarks:* If the function can succeed in more than one of these ways,
-it is unspecified which way is chosen. The function can alter the number
-of putback positions available as a result of any call.
-``` cpp
-int_type underflow() override;
-```
-*Effects:* Reads a character from the *input sequence*, if possible,
-without moving the stream position past it, as follows:
-- If the input sequence has a read position available, the function
-  signals success by returning `(unsigned char)*gnext`.
-- Otherwise, if the current write next pointer `pnext` is not a null
-  pointer and is greater than the current read end pointer `gend`, makes
-  a *read position* available by assigning to `gend` a value greater
-  than `gnext` and no greater than `pnext`. Returns
-  `(unsigned char)*gnext`.
-Returns `EOF` to indicate failure.
-*Remarks:* The function can alter the number of read positions available
-as a result of any call.
-``` cpp
-pos_type seekoff(off_type off, seekdir way, openmode which = in | out) override;
-```
-*Effects:* Alters the stream position within one of the controlled
-sequences, if possible, as indicated in
-[[depr.strstreambuf.seekoff.pos]].
-**Table: `seekoff` positioning** <a id="depr.strstreambuf.seekoff.pos">[depr.strstreambuf.seekoff.pos]</a>
-| Conditions                                                                                                           | Result                                            |
-| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| `(which & ios::in) != 0`                                                                                             | positions the input sequence                      |
-| `(which & ios::out) != 0`                                                                                            | positions the output sequence                     |
-| `(which & (ios::in | ios::out)) ==`<br> `(ios::in | ios::out)` and either<br> `way == ios::beg` or `way == ios::end` | positions both the input and the output sequences |
-| Otherwise                                                                                                            | the positioning operation fails.                  |
-For a sequence to be positioned, if its next pointer is a null pointer,
-the positioning operation fails. Otherwise, the function determines
-`newoff` as indicated in [[depr.strstreambuf.seekoff.newoff]].
-**Table: `newoff` values** <a id="depr.strstreambuf.seekoff.newoff">[depr.strstreambuf.seekoff.newoff]</a>
-| Condition         | `newoff` Value                                                 |
-| ----------------- | -------------------------------------------------------------- |
-| `way == ios::beg` | 0                                                              |
-| `way == ios::cur` | the next pointer minus the beginning pointer (`xnext - xbeg`). |
-| `way == ios::end` | `seekhigh` minus the beginning pointer (`seekhigh - xbeg`).    |
-If `(newoff + off) < (seeklow - xbeg)` or
-`(seekhigh - xbeg) < (newoff + off)`, the positioning operation fails.
-Otherwise, the function assigns `xbeg + newoff + off` to the next
-pointer `xnext`.
-*Returns:* `pos_type(newoff)`, constructed from the resultant offset
-`newoff` (of type `off_type`), that stores the resultant stream
-position, if possible. If the positioning operation fails, or if the
-constructed object cannot represent the resultant stream position, the
-return value is `pos_type(off_type(-1))`.
-``` cpp
-pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out) override;
-```
-*Effects:* Alters the stream position within one of the controlled
-sequences, if possible, to correspond to the stream position stored in
-`sp` (as described below).
-- If `(which & ios::in) != 0`, positions the input sequence.
-- If `(which & ios::out) != 0`, positions the output sequence.
-- If the function positions neither sequence, the positioning operation
-  fails.
-For a sequence to be positioned, if its next pointer is a null pointer,
-the positioning operation fails. Otherwise, the function determines
-`newoff` from `sp.offset()`:
-- If `newoff` is an invalid stream position, has a negative value, or
-  has a value greater than (`seekhigh - seeklow`), the positioning
-  operation fails
-- Otherwise, the function adds `newoff` to the beginning pointer `xbeg`
-  and stores the result in the next pointer `xnext`.
-*Returns:* `pos_type(newoff)`, constructed from the resultant offset
-`newoff` (of type `off_type`), that stores the resultant stream
-position, if possible. If the positioning operation fails, or if the
-constructed object cannot represent the resultant stream position, the
-return value is `pos_type(off_type(-1))`.
-``` cpp
-streambuf<char>* setbuf(char* s, streamsize n) override;
-```
-*Effects:* Behavior is *implementation-defined*, except that
-`setbuf(0, 0)` has no effect.
-### Class `istrstream` <a id="depr.istrstream">[[depr.istrstream]]</a>
-#### General <a id="depr.istrstream.general">[[depr.istrstream.general]]</a>
-``` cpp
-namespace std {
-  class istrstream : public basic_istream<char> {
-  public:
-    explicit istrstream(const char* s);
-    explicit istrstream(char* s);
-    istrstream(const char* s, streamsize n);
-    istrstream(char* s, streamsize n);
-    virtual ~istrstream();
-    strstreambuf* rdbuf() const;
-    char* str();
-  private:
-    strstreambuf sb;            // exposition only
-  };
-}
-```
-The class `istrstream` supports the reading of objects of class
-`strstreambuf`. It supplies a `strstreambuf` object to control the
-associated array object. For the sake of exposition, the maintained data
-is presented here as:
-- `sb`, the `strstreambuf` object.
-#### `istrstream` constructors <a id="depr.istrstream.cons">[[depr.istrstream.cons]]</a>
-``` cpp
-explicit istrstream(const char* s);
-explicit istrstream(char* s);
-```
-*Effects:* Initializes the base class with `istream(&sb)` and `sb` with
-`strstreambuf(s, 0)`. `s` shall designate the first element of an NTBS.
-``` cpp
-istrstream(const char* s, streamsize n);
-istrstream(char* s, streamsize n);
-```
-*Effects:* Initializes the base class with `istream(&sb)` and `sb` with
-`strstreambuf(s, n)`. `s` shall designate the first element of an array
-whose length is `n` elements, and `n` shall be greater than zero.
-#### Member functions <a id="depr.istrstream.members">[[depr.istrstream.members]]</a>
-``` cpp
-strstreambuf* rdbuf() const;
-```
-*Returns:* `const_cast<strstreambuf*>(&sb)`.
-``` cpp
-char* str();
-```
-*Returns:* `rdbuf()->str()`.
-### Class `ostrstream` <a id="depr.ostrstream">[[depr.ostrstream]]</a>
-#### General <a id="depr.ostrstream.general">[[depr.ostrstream.general]]</a>
-``` cpp
-namespace std {
-  class ostrstream : public basic_ostream<char> {
-  public:
-    ostrstream();
-    ostrstream(char* s, int n, ios_base::openmode mode = ios_base::out);
-    virtual ~ostrstream();
-    strstreambuf* rdbuf() const;
-    void freeze(bool freezefl = true);
-    char* str();
-    int pcount() const;
-  private:
-    strstreambuf sb;            // exposition only
-  };
-}
-```
-The class `ostrstream` supports the writing of objects of class
-`strstreambuf`. It supplies a `strstreambuf` object to control the
-associated array object. For the sake of exposition, the maintained data
-is presented here as:
-- `sb`, the `strstreambuf` object.
-#### `ostrstream` constructors <a id="depr.ostrstream.cons">[[depr.ostrstream.cons]]</a>
-``` cpp
-ostrstream();
-```
-*Effects:* Initializes the base class with `ostream(&sb)` and `sb` with
-`strstreambuf()`.
-``` cpp
-ostrstream(char* s, int n, ios_base::openmode mode = ios_base::out);
-```
-*Effects:* Initializes the base class with `ostream(&sb)`, and `sb` with
-one of two constructors:
-- If `(mode & app) == 0`, then `s` shall designate the first element of
-  an array of `n` elements. The constructor is `strstreambuf(s, n, s)`.
-- If `(mode & app) != 0`, then `s` shall designate the first element of
-  an array of `n` elements that contains an NTBS whose first element is
-  designated by `s`. The constructor is
-  `strstreambuf(s, n, s + std::strlen(s))`.[^2]
-#### Member functions <a id="depr.ostrstream.members">[[depr.ostrstream.members]]</a>
-``` cpp
-strstreambuf* rdbuf() const;
-```
-*Returns:* `(strstreambuf*)&sb`.
-``` cpp
-void freeze(bool freezefl = true);
-```
-*Effects:* Calls `rdbuf()->freeze(freezefl)`.
-``` cpp
-char* str();
-```
-*Returns:* `rdbuf()->str()`.
-``` cpp
-int pcount() const;
-```
-*Returns:* `rdbuf()->pcount()`.
-### Class `strstream` <a id="depr.strstream">[[depr.strstream]]</a>
-#### General <a id="depr.strstream.general">[[depr.strstream.general]]</a>
-``` cpp
-namespace std {
-  class strstream
-    : public basic_iostream<char> {
-  public:
-    // types
-    using char_type = char;
-    using int_type  = char_traits<char>::int_type;
-    using pos_type  = char_traits<char>::pos_type;
-    using off_type  = char_traits<char>::off_type;
-    // constructors/destructor
-    strstream();
-    strstream(char* s, int n,
-              ios_base::openmode mode = ios_base::in|ios_base::out);
-    virtual ~strstream();
-    // members
-    strstreambuf* rdbuf() const;
-    void freeze(bool freezefl = true);
-    int pcount() const;
-    char* str();
-  private:
-    strstreambuf sb;            // exposition only
-  };
-}
-```
-The class `strstream` supports reading and writing from objects of class
-`strstreambuf`. It supplies a `strstreambuf` object to control the
-associated array object. For the sake of exposition, the maintained data
-is presented here as:
-- `sb`, the `strstreambuf` object.
-#### `strstream` constructors <a id="depr.strstream.cons">[[depr.strstream.cons]]</a>
-``` cpp
-strstream();
-```
-*Effects:* Initializes the base class with `iostream(&sb)`.
-``` cpp
-strstream(char* s, int n,
-          ios_base::openmode mode = ios_base::in|ios_base::out);
-```
-*Effects:* Initializes the base class with `iostream(&sb)`, and `sb`
-with one of the two constructors:
-- If `(mode & app) == 0`, then `s` shall designate the first element of
-  an array of `n` elements. The constructor is `strstreambuf(s,n,s)`.
-- If `(mode & app) != 0`, then `s` shall designate the first element of
-  an array of `n` elements that contains an NTBS whose first element is
-  designated by `s`. The constructor is
-  `strstreambuf(s,n,s + std::strlen(s))`.
-#### `strstream` destructor <a id="depr.strstream.dest">[[depr.strstream.dest]]</a>
-``` cpp
-virtual ~strstream();
-```
-*Effects:* Destroys an object of class `strstream`.
-#### `strstream` operations <a id="depr.strstream.oper">[[depr.strstream.oper]]</a>
-``` cpp
-strstreambuf* rdbuf() const;
-```
-*Returns:* `const_cast<strstreambuf*>(&sb)`.
-``` cpp
-void freeze(bool freezefl = true);
-```
-*Effects:* Calls `rdbuf()->freeze(freezefl)`.
-``` cpp
-char* str();
-```
-*Returns:* `rdbuf()->str()`.
-``` cpp
-int pcount() const;
-```
-*Returns:* `rdbuf()->pcount()`.

Diff to HTML by rtfpessoa