Annex D (normative) Compatibility features [depr]

D.6 char* streams [depr.str.strstreams]

Заголовок определяет три типа, которые связывают буферы потока с объектами символьного массива и помогают читать и записывать такие объекты.<strstream>

D.6.1 Class strstreambuf [depr.strstreambuf]

namespace std {
  class strstreambuf : public basic_streambuf<char> {
  public:
    explicit strstreambuf(streamsize alsize_arg = 0);
    strstreambuf(void* (*palloc_arg)(size_t), void (*pfree_arg)(void*));
    strstreambuf(char* gnext_arg, streamsize n, char* pbeg_arg = 0);
    strstreambuf(const char* gnext_arg, streamsize n);

    strstreambuf(signed char* gnext_arg, streamsize n,
                 signed char* pbeg_arg = 0);
    strstreambuf(const signed char* gnext_arg, streamsize n);
    strstreambuf(unsigned char* gnext_arg, streamsize n,
                 unsigned char* pbeg_arg = 0);
    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
  };
}

Класс strstreambuf связывает входную последовательность и, возможно, выходную последовательность с объектом некоторого character типа массива, элементы которого хранят произвольные значения. У объекта массива есть несколько атрибутов.

[ Note: Для наглядности они представлены как элементы типа битовой маски (обозначены здесь какT1) с именемstrstate. Элементами являются:

(2.1)
allocated, устанавливается, когда объект динамического массива был выделен и, следовательно, должен быть освобожден деструктором этого strstreambuf объекта;
(2.2)
constant, устанавливается, когда объект массива имеет const элементы, поэтому выходная последовательность не может быть записана;
(2.3)
dynamic, устанавливается, когда объект массива выделяется (или перераспределяется) по мере необходимости для хранения последовательности символов, длина которой может изменяться;
(2.4)
frozen, устанавливается, когда программа запросила, чтобы объект массива не был изменен, перераспределен или освобожден.

— end note ]

[ Note: Для демонстрации поддерживаемые данные представлены здесь как:

(3.1)
strstate strmode, атрибуты объекта массива, связанные сstrstreambuf объектом;
(3.2)
int alsize, рекомендуемый минимальный размер объекта динамического массива;
(3.3)
void* (*palloc)(size_t), указывает на функцию, которую нужно вызвать для выделения объекта динамического массива;
(3.4)
void (*pfree)(void*), указывает на функцию, вызываемую для освобождения объекта динамического массива.

— end note ]

Каждый объект класса strstreambuf имеет seekable area, разделенный указателямиseeklow иseekhigh. Еслиgnext это нулевой указатель, область поиска не определена. В противном случаеseeklow равноgbeg и seekhigh равно либоpend, еслиpend не является нулевым указателем, либоgend.

D.6.1.1 strstreambuf constructors [depr.strstreambuf.cons]

explicit strstreambuf(streamsize alsize_arg = 0);

Effects: Создает объект класса strstreambuf, инициализируя базовый класс с помощью streambuf(). Постусловия этой функции указаны в таблице142.

Таблица142 -strstreambuf(streamsize) эффекты

Элемент	Ценить
strmode	dynamic
alsize	alsize_arg
palloc	нулевой указатель
pfree	нулевой указатель

strstreambuf(void* (*palloc_arg)(size_t), void (*pfree_arg)(void*));

Effects: Создает объект класса strstreambuf, инициализируя базовый класс с помощью streambuf(). Постусловия этой функции указаны в таблице143.

Таблица143 -strstreambuf(void* (*)(size_t), void (*)(void*)) эффекты

Элемент	Ценить
strmode	dynamic
alsize	неуказанное значение
palloc	palloc_arg
pfree	pfree_arg

strstreambuf(char* gnext_arg, streamsize n, char* pbeg_arg = 0); strstreambuf(signed char* gnext_arg, streamsize n, signed char* pbeg_arg = 0); strstreambuf(unsigned char* gnext_arg, streamsize n, unsigned char* pbeg_arg = 0);

Effects: Создает объект класса strstreambuf, инициализируя базовый класс с помощью streambuf(). Постусловия этой функции указаны в таблице144.

Таблица144 -strstreambuf(charT*, streamsize, charT*) эффекты

Элемент	Ценить
strmode	0
alsize	неуказанное значение
palloc	нулевой указатель
pfree	нулевой указатель

gnext_arg должен указывать на первый элемент объекта массива, количество элементовN которого определяется следующим образом:

(4.1)
Если n > 0, то N естьn.
(4.2)
Если n == 0, то N есть std::strlen(gnext_arg).
(4.3)
Если n < 0, то N есть INT_MAX.331

Еслиpbeg_arg это нулевой указатель, функция выполняет:

setg(gnext_arg, gnext_arg, gnext_arg + N);

В противном случае функция выполняет:

setg(gnext_arg, gnext_arg, pbeg_arg);
setp(pbeg_arg,  pbeg_arg + N);

strstreambuf(const char* gnext_arg, streamsize n); strstreambuf(const signed char* gnext_arg, streamsize n); strstreambuf(const unsigned char* gnext_arg, streamsize n);

Effects: Ведет же , как strstreambuf((char*)gnext_arg,n), за исключением того, что конструктор также устанавливаетconstant вstrmode.

virtual ~strstreambuf();

Effects: Уничтожает объект класса strstreambuf. Функция освобождает динамически выделенный объект массива, только если (strmode & allocated) != 0 и (strmode & frozen) == 0. ([depr.strstreambuf.virtuals] описывает, как освобождается динамически выделенный объект массива.)

331)

Сигнатура функции strlen(const char*) объявлена в . Макрос определен в . <cstring>INT_MAX<climits>

D.6.1.2 Member functions [depr.strstreambuf.members]

void freeze(bool freezefl = true);

Effects: Если неstrmode & dynamic равно нулю, изменяет статус фиксации объекта динамического массива следующим образом:

(1.1)
Еслиfreezefl IS true, функция устанавливаетfrozen вstrmode.
(1.2)
В противном случае, она очищаетfrozen вstrmode.

char* str();

Effects: Вызывает freeze(), а затем возвращает начальный указатель для входной последовательностиgbeg.

Remarks: Возвращаемое значение может быть нулевым указателем.

int pcount() const;

Effects: Если следующий указатель для выходной последовательностиpnext, является нулевым указателем, возвращает ноль. В противном случае возвращает текущую эффективную длину объекта массива как следующий указатель минус начальный указатель для выходной последовательностиpnext - pbeg.

D.6.1.3 strstreambuf overridden virtual functions [depr.strstreambuf.virtuals]

int_type overflow(int_type c = EOF) override;

Effects: Добавляет символ, обозначенный значком,c к выходной последовательности, если возможно, одним из двух способов:

(1.1)
Если c != EOF и если либо выходная последовательность имеет позицию записи доступны или функция делает позицию записи доступную (как описано ниже), назначаетc для *pnext++.
Возврат (unsigned char)c.
(1.2)
Если c == EOFнет символа для добавления.
Возвращает значение, отличное отEOF.

Возвращает, EOF чтобы указать на сбой.

Remarks: Функция может изменить количество позиций записи, доступных в результате любого вызова.

Чтобы сделать позицию записи доступной, функция перераспределяет (или первоначально выделяет) объект массива с достаточным количеством элементов, n чтобы удерживать текущий объект массива (если есть), плюс по крайней мере одну дополнительную позицию записи. В противном случае не указывается, сколько дополнительных позиций записи доступно. 332 Еслиpalloc это не нулевой указатель, функция вызывает (*palloc)(n) выделение нового объекта динамического массива. В противном случае он оценивает выражение new charT[n]. В любом случае, если выделение не удалось, функция вернется EOF. В противном случае, он устанавливаетallocated вstrmode.

Чтобы освободить ранее существовавший объект динамического массива, адрес первого элемента которогоp: Еслиpfree не является нулевым указателем, функция вызывает (*pfree)(p). В противном случае он оценивает выражениеdelete[]p.

Если (strmode & dynamic) == 0или если (strmode & frozen) != 0функция не может расширить массив (перераспределить его на большую длину), чтобы сделать доступной позицию для записи.

int_type pbackfail(int_type c = EOF) override;

Возвращает символ, обозначенный значком,c во входную последовательность, если это возможно, одним из трех способов:

(7.1)
Если c != EOF, если входная последовательность имеет место Putback доступный, и если (char)c == gnext[-1], правопреемники gnext - 1 вgnext.
Возвратc.
(7.2)
Если c != EOF, если входная последовательность имеет позицию Putback доступный, и если strmode & constant равна нулю, правопреемниковc к *--gnext.
Возврат c.
(7.3)
Если c == EOF и , если входная последовательность имеет место Putback доступный, правопреемники gnext - 1 кgnext.
Возвращает значение, отличное от EOF.

Возвращает, EOF чтобы указать на сбой.

Remarks: Если функция может быть успешной более чем одним из этих способов, не указано, какой путь будет выбран. Функция может изменить количество позиций возврата, доступных в результате любого вызова.

int_type underflow() override;

Effects: Считывает символ из input sequence, если это возможно, не перемещая позицию потока мимо него, как показано ниже:

(10.1)
Если входная последовательность имеет доступную позицию чтения, функция сигнализирует об успехе, возвращаясь (unsigned char)*gnext.
(10.2)
В противном случае, если текущий указатель на следующую записьpnext не является нулевым указателем и больше, чем текущий указатель конца чтенияgend, делает read position доступным, присваиваяgend значение большеgnext и не большеpnext.
Возврат(unsigned char)*gnext.

Возвращает, EOF чтобы указать на сбой.

Remarks: Функция может изменить количество позиций чтения, доступных в результате любого вызова.

pos_type seekoff(off_type off, seekdir way, openmode which = in | out) override;

Effects: Если возможно, изменяет положение потока в одной из управляемых последовательностей, как указано в Табл145.

Стол145 -seekoff позиционирование

Условия	Результат
(which & ios::in) != 0	позиционирует входную последовательность
(which & ios::out) != 0	позиционирует выходную последовательность
(which & (ios::in \| ios::out)) == (ios::in \| ios::out)) и way == либо, ios::beg либо ios::end	позиционирует как входную, так и выходную последовательности
Иначе	операция позиционирования не выполняется.

Для позиционирования последовательности, если ее следующий указатель является нулевым указателем, операция позиционирования завершается ошибкой. В противном случае функция определяет,newoff как указано в таблице146.

Таблица146 -newoff значения

Состояние	newoff Ценить
way == ios::beg	0
way == ios::cur	следующий указатель минус указатель начала (xnext - xbeg).
way == ios::end	seekhigh минус начальный указатель (seekhigh - xbeg).

Если(newoff + off) < (seeklow - xbeg) или(seekhigh - xbeg) < (newoff + off), операция позиционирования не выполняется. В противном случае функция присваивает xbeg + newoff + off следующий указательxnext.

Returns: pos_type(newoff), построенный из результирующего смещения newoff (типа off_type), в котором, если возможно, сохраняется позиция результирующего потока. Если операция позиционирования завершается неудачно, или если сконструированный объект не может представлять позицию результирующего потока, возвращается значение pos_type(off_type(-1)).

pos_type seekpos(pos_type sp, ios_base::openmode which = ios_base::in | ios_base::out) override;

Effects: Изменяет позицию потока в одной из управляемых последовательностей, если это возможно, чтобы соответствовать позиции потока, сохраненной вsp (как описано ниже).

(17.1)
Если (which & ios::in) != 0, позиционирует входную последовательность.
(17.2)
Если (which & ios::out) != 0, позиционирует выходную последовательность.
(17.3)
Если функция не позиционирует ни одну последовательность, операция позиционирования не выполняется.

(18.1)
Еслиnewoff это недопустимая позиция в потоке, имеет отрицательное значение или значение больше (seekhigh - seeklow), операция позиционирования не выполняется.
(18.2)
В противном случае функция добавляетnewoff к начальному указателюxbeg и сохраняет результат в следующем указателеxnext.

Returns: pos_type(newoff), построенный из результирующего смещенияnewoff (типа off_type), в котором, если возможно, сохраняется позиция результирующего потока. Если операция позиционирования завершается неудачно, или если сконструированный объект не может представлять позицию результирующего потока, возвращается значение pos_type(off_type(-1)).

streambuf<char>* setbuf(char* s, streamsize n) override;

Effects: Реализация определена, но setbuf(0, 0) не имеет никакого эффекта.

332)

Приalsize принятии этого решения следует учитывать реализацию .

D.6.2 Class istrstream [depr.istrstream]

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
  };
}

Класс istrstream поддерживает чтение объектов класса strstreambuf. Он предоставляет strstreambuf объект для управления связанным объектом массива. Для демонстрации поддерживаемые данные представлены здесь как:

(1.1)
sb,strstreambuf объект.

D.6.2.1 istrstream constructors [depr.istrstream.cons]

explicit istrstream(const char* s); explicit istrstream(char* s);

Effects: Создает объект класса istrstream, инициализируя базовый класс istream(&sb) и инициализируяsb с помощью strstreambuf(s,0). s обозначает первый элемент ntbs .

istrstream(const char* s, streamsize n); istrstream(char* s, streamsize n);

Effects: Создает объект класса istrstream, инициализируя базовый класс istream(&sb) и инициализируяsb с помощью strstreambuf(s,n). s должен обозначать первый элемент массива, длина которого равна n elements, иn должна быть больше нуля.

D.6.2.2 Member functions [depr.istrstream.members]

strstreambuf* rdbuf() const;

Returns: const_cast<strstreambuf*>(&sb).

char* str();

Returns: rdbuf()->str().

D.6.3 Class ostrstream [depr.ostrstream]

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
  };
}

Класс ostrstream поддерживает запись объектов класса strstreambuf. Он предоставляет strstreambuf объект для управления связанным объектом массива. Для демонстрации поддерживаемые данные представлены здесь как:

(1.1)
sb,strstreambuf объект.

D.6.3.1 ostrstream constructors [depr.ostrstream.cons]

ostrstream();

Effects: Создает объект класса ostrstream, инициализируя базовый класс ostream(&sb) и инициализируяsb с помощью strstreambuf().

ostrstream(char* s, int n, ios_base::openmode mode = ios_base::out);

Effects: Создает объект класса ostrstream, инициализируя базовый класс ostream(&sb)и инициализируяsb одним из двух конструкторов:

(2.1)
Если (mode & app) == 0, тоs обозначает первый элемент массиваn элементов.
Конструктор есть strstreambuf(s, n, s).
(2.2)
Если (mode & app) != 0, тоs должен обозначить первый элемент массиваn элементов, который содержит ntbs , первый элемент которого обозначенs. Конструктор есть strstreambuf(s, n, s + std::strlen(s)).333

333)

Сигнатура функции strlen(const char*) объявлена в .<cstring>

D.6.3.2 Member functions [depr.ostrstream.members]

strstreambuf* rdbuf() const;

Returns: (strstreambuf*)&sb.

void freeze(bool freezefl = true);

Effects: Звонки rdbuf()->freeze(freezefl).

char* str();

Returns: rdbuf()->str().

int pcount() const;

Returns: rdbuf()->pcount().

D.6.4 Class strstream [depr.strstream]

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
  };
}

Класс strstream поддерживает чтение и запись из объектов класса strstreambuf. Он предоставляет strstreambuf объект для управления связанным объектом массива. Для демонстрации поддерживаемые данные представлены здесь как:

(1.1)
sb,strstreambuf объект.

D.6.4.1 strstream constructors [depr.strstream.cons]

strstream();

Effects: Создает объект класса strstream, инициализируя базовый класс с помощью iostream(&sb).

strstream(char* s, int n, ios_base::openmode mode = ios_base::in|ios_base::out);

Effects: Создает объект класса strstream, инициализируя базовый класс iostream(&sb) и инициализируяsb одним из двух конструкторов:

(2.1)
Если (mode & app) == 0, тоs обозначает первый элемент массиваn элементов. Конструктор есть strstreambuf(s,n,s).
(2.2)
Если (mode & app) != 0, тоs должен обозначить первый элемент массиваn элементов, который содержит ntbs , первый элемент которого обозначенs. Конструктор есть strstreambuf(s,n,s + std::strlen(s)).

D.6.4.2 strstream destructor [depr.strstream.dest]

virtual ~strstream();

Effects: Уничтожает объект класса strstream.

D.6.4.3 strstream operations [depr.strstream.oper]

strstreambuf* rdbuf() const;

Returns: &sb.

void freeze(bool freezefl = true);

Effects: Звонки rdbuf()->freeze(freezefl).

char* str();

Returns: rdbuf()->str().

int pcount() const;

Returns: rdbuf()->pcount().