Annex D (normative) Compatibility features [depr]

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

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. Элементами являются:

  • allocated, устанавливается, когда объект динамического массива был выделен и, следовательно, должен быть освобожден деструктором этого strstreambuf объекта;

  • constant, устанавливается, когда объект массива имеет const элементы, поэтому выходная последовательность не может быть записана;

  • dynamic, устанавливается, когда объект массива выделяется (или перераспределяется) по мере необходимости для хранения последовательности символов, длина которой может изменяться;

  • frozen, устанавливается, когда программа запросила, чтобы объект массива не был изменен, перераспределен или освобожден.

end note]

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

  • strstate strmode, атрибуты объекта массива, связанные сstrstreambuf объектом;

  • int alsize, рекомендуемый минимальный размер объекта динамического массива;

  • void* (*palloc)(size_­t), указывает на функцию, которую нужно вызвать для выделения объекта динамического массива;

  • 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 которого определяется следующим образом:

  • Если n > 0, то N естьn.

  • Если n == 0, то N есть std​::​strlen(gnext_­arg).

  • Если 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] описывает, как освобождается динамически выделенный объект массива.)

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

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

void freeze(bool freezefl = true);

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

  • Еслиfreezefl IS true, функция устанавливаетfrozen вstrmode.

  • В противном случае, она очищает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 к выходной последовательности, если возможно, одним из двух способов:

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

    Возврат (unsigned char)c.

  • Если 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 во входную последовательность, если это возможно, одним из трех способов:

  • Если c != EOF, если входная последовательность имеет место Putback доступный, и если (char)c == gnext[-1], правопреемники gnext - 1 вgnext.

    Возвратc.

  • Если c != EOF, если входная последовательность имеет позицию Putback доступный, и если strmode & constant равна нулю, правопреемниковc к *--gnext.

    Возврат c.

  • Если c == EOF и , если входная последовательность имеет место Putback доступный, правопреемники gnext - 1 кgnext.

    Возвращает значение, отличное от EOF.

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

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

int_type underflow() override;

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

  • Если входная последовательность имеет доступную позицию чтения, функция сигнализирует об успехе, возвращаясь (unsigned char)​*gnext.

  • В противном случае, если текущий указатель на следующую запись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 (как описано ниже).

  • Если (which & ios​::​in) != 0, позиционирует входную последовательность.

  • Если (which & ios​::​out) != 0, позиционирует выходную последовательность.

  • Если функция не позиционирует ни одну последовательность, операция позиционирования не выполняется.

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

  • Еслиnewoff это недопустимая позиция в потоке, имеет отрицательное значение или значение больше (seekhigh - seeklow), операция позиционирования не выполняется.

  • В противном случае функция добавляет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) не имеет никакого эффекта.

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