30 Input/output library [input.output]

30.7 Formatting and manipulators [iostream.format]

30.7.5 Output streams [output.streams]

Заголовок <ostream> определяет тип и несколько сигнатур функций, которые управляют выводом в буфер потока вместе с шаблоном функции, который вставляется в rvalue потока.

30.7.5.1 Class template basic_­ostream [ostream]

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):
    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();

    // [ostream::sentry], prefix/suffix
    class sentry;

    // [ostream.formatted], formatted output
    basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));
    basic_ostream<charT, traits>&
      operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
    basic_ostream<charT, traits>&
      operator<<(ios_base& (*pf)(ios_base&));

    basic_ostream<charT, traits>& operator<<(bool n);
    basic_ostream<charT, traits>& operator<<(short n);
    basic_ostream<charT, traits>& operator<<(unsigned short n);
    basic_ostream<charT, traits>& operator<<(int n);
    basic_ostream<charT, traits>& operator<<(unsigned int n);
    basic_ostream<charT, traits>& operator<<(long n);
    basic_ostream<charT, traits>& operator<<(unsigned long n);
    basic_ostream<charT, traits>& operator<<(long long n);
    basic_ostream<charT, traits>& operator<<(unsigned long long n);
    basic_ostream<charT, traits>& operator<<(float f);
    basic_ostream<charT, traits>& operator<<(double f);
    basic_ostream<charT, traits>& operator<<(long double f);

    basic_ostream<charT, traits>& operator<<(const void* p);
    basic_ostream<charT, traits>& operator<<(nullptr_t);
    basic_ostream<charT, traits>& operator<<(basic_streambuf<char_type, traits>* sb);

    // [ostream.unformatted], unformatted output
    basic_ostream<charT, traits>& put(char_type c);
    basic_ostream<charT, traits>& write(const char_type* s, streamsize n);

    basic_ostream<charT, traits>& flush();

    // [ostream.seeks], seeks
    pos_type tellp();
    basic_ostream<charT, traits>& seekp(pos_type);
    basic_ostream<charT, traits>& seekp(off_type, ios_base::seekdir);

  protected:
    // [ostream.cons], copy/move constructor
    basic_ostream(const basic_ostream& rhs) = delete;
    basic_ostream(basic_ostream&& rhs);

    // [ostream.assign], assign and swap
    basic_ostream& operator=(const basic_ostream& rhs) = delete;
    basic_ostream& operator=(basic_ostream&& rhs);
    void swap(basic_ostream& rhs);
  };

  // [ostream.inserters.character], character inserters
  template<class charT, class traits>
    basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, charT);
  template<class charT, class traits>
    basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, char);
  template<class traits>
    basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, char);

  template<class traits>
    basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, signed char);
  template<class traits>
    basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, unsigned char);

  template<class charT, class traits>
    basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const charT*);
  template<class charT, class traits>
    basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&, const char*);
  template<class traits>
    basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const char*);

  template<class traits>
    basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const signed char*);
  template<class traits>
    basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>&, const unsigned char*);
}

Шаблон класса basic_­ostream определяет ряд сигнатур функций-членов, которые помогают форматировать и записывать выходные данные в выходные последовательности, управляемые буфером потока.

Две группы сигнатур функций-членов имеют общие свойства: formatted output functions (или inserters) и unformatted output functions. Обе группы функций вывода генерируют (или insert) вывод characters посредством действий, эквивалентных вызову rdbuf()->sputc(int_­type). Они могут использовать другие общественные член заbasic_­ostream исключением того , что они не должны вызывать какие - либо виртуальные членов , заrdbuf() исключением overflow(), xsputn()и sync().

Если одна из этих вызываемых функций вызывает исключение, тогда, если явно не указано иное, функция вывода переходит badbit в состояние ошибки. Если badbit на в exceptions(), функции выхода rethrows исключения без завершения его действия, в противном случае он ничего и лечить как ошибку не бросать.

30.7.5.1.1 basic_­ostream constructors [ostream.cons]

explicit basic_ostream(basic_streambuf<charT, traits>* sb);

Effects: Создает объект класса basic_­ostream, инициализируя подобъект базового класса с помощью basic_­ios<charT, traits>​::​init(sb) ([basic.ios.cons]).

Postconditions: rdbuf() == sb.

basic_ostream(basic_ostream&& rhs);

Effects: Переместите конструкции из rvaluerhs. Это выполняется по умолчанию путем создания базового класса и вызова basic_­ios<charT, traits>​::​move(rhs) для инициализации базового класса.

virtual ~basic_ostream();

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

Remarks: Не выполняет никаких операций над rdbuf().

30.7.5.1.2 Class basic_­ostream assign and swap [ostream.assign]

basic_ostream& operator=(basic_ostream&& rhs);

Effects: Как будто мимоswap(rhs).

Returns:*this.

void swap(basic_ostream& rhs);

Effects: Звонкиbasic_­ios<charT, traits>​::​swap(rhs).

30.7.5.1.3 Class basic_­ostream​::​sentry [ostream::sentry]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class basic_ostream<charT, traits>::sentry {
    bool ok_; // exposition only
  public:
    explicit sentry(basic_ostream<charT, traits>& os);
    ~sentry();
    explicit operator bool() const { return ok_; }

    sentry(const sentry&) = delete;
    sentry& operator=(const sentry&) = delete;
  };
}

Этот класс sentry определяет класс, который отвечает за выполнение безопасных в отношении исключений операций с префиксом и суффиксом.

explicit sentry(basic_ostream<charT, traits>& os);

Если не os.good() равно нулю, готовится к форматированному или неформатированному выводу. Если os.tie() не является нулевым указателем, вызывает os.tie()->flush().318

Если после любой препарат будет завершен, os.good() это true, вok_­ == true противном случае ok_­ == false. Во время подготовки конструктор может вызвать setstate(failbit) (который может throw ios_­base​::​​failure ([iostate.flags]))319

~sentry();

Если (os.flags() & ios_­base​::​unitbuf) && !uncaught_­exceptions() && os.good() есть true, звонит os.rdbuf()->pubsync(). Если эта функция возвращает -1, устанавливаетbadbit в os.rdstate() без распространяющегося исключения.

explicit operator bool() const;

Effects: Возврат ok_­.

Вызов os.tie()->flush() не обязательно происходит, если функция может определить, что синхронизация не требуется.

sentry Конструктор и деструктор может также выполнять дополнительные операции , зависящие от реализации.

30.7.5.1.4 basic_­ostream seek members [ostream.seeks]

Каждая функция-член поиска начинает выполнение с создания объекта классаsentry. Он возвращается, уничтожаяsentry объект.

pos_type tellp();

Returns: Если fail() != false, возвращается, pos_­type(-1) чтобы указать на сбой. В противном случае возвращается rdbuf()->​pubseekoff(​0, cur, out).

basic_ostream<charT, traits>& seekp(pos_type pos);

Effects: Если fail() != trueвыполняется rdbuf()->pubseekpos(pos, ios_­base​::​out). В случае неудачи вызовы функции setstate(failbit) (которые могут выкинуть ios_­base​::​failure).

Returns: *this.

basic_ostream<charT, traits>& seekp(off_type off, ios_base::seekdir dir);

Effects: Если fail() != trueвыполняется rdbuf()->pubseekoff(off, dir, ios_­base​::​out). В случае неудачи вызовы функцииsetstate(failbit) (которые могут выкинутьios_­base​::​failure).

Returns: *this.

30.7.5.2 Formatted output functions [ostream.formatted]

30.7.5.2.1 Common requirements [ostream.formatted.reqmts]

Каждая функция форматированного вывода начинает выполнение с создания объекта класса sentry. Если этот объект возвращается true при преобразовании в значение типа bool, функция пытается сгенерировать запрошенный вывод. В случае сбоя генерации выполняется функция форматированного вывода setstate(ios_­base​::​failbit), которая может вызвать исключение. Если во время вывода возникает исключение, то ios​::​badbit включается320 в *thisсостоянии ошибки. Если (exceptions()&badbit) != 0 тогда исключение генерируется повторно. Независимо от того, выбрасывается ли исключение, sentry объект уничтожается до выхода из функции форматированного вывода. Если исключение не генерируется, результатом функции форматированного вывода будет *this.

Описания отдельных функций форматированного вывода описывают, как они выполняют вывод, и не упоминают sentry объект.

Если функция форматированного вывода потокаos определяет заполнение, это делается следующим образом. Для даннойcharT символьной последовательности,seq где charT - символьный тип потока, если длинаseq меньше чемos.width(), тоos.fill() к этой последовательности добавляется достаточное количество копий, необходимое для заполнения до шириныos.width() символов. Если (os.flags() & ios_­base​::​adjustfield) == ios_­base​::​left есть true, символы заполнения помещаются после последовательности символов; в противном случае они помещаются перед последовательностью символов.

не вызывая ios​::​failure броска.

30.7.5.2.2 Arithmetic inserters [ostream.inserters.arithmetic]

operator<<(bool val); operator<<(short val); operator<<(unsigned short val); operator<<(int val); operator<<(unsigned int val); operator<<(long val); operator<<(unsigned long val); operator<<(long long val); operator<<(unsigned long long val); operator<<(float val); operator<<(double val); operator<<(long double val); operator<<(const void* val);

Effects: Классы num_­get<> и num_­put<> обрабатывают зависящее от языкового стандарта числовое форматирование и синтаксический анализ. Эти функции вставки используют встроенное locale значение для форматирования чисел. Когдаval имеет тип bool, long, unsigned long, long long,unsigned long long, double, long double, или const void*, форматирование превращение происходит так , как будто он выполняется следующий фрагмент кода:

bool failed = use_facet<
  num_put<charT, ostreambuf_iterator<charT, traits>>
    >(getloc()).put(*this, *this, fill(), val).failed();

Когдаval is of type, short преобразование форматирования происходит так, как если бы оно выполняло следующий фрагмент кода:

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();

Когдаval is of type, int преобразование форматирования происходит так, как если бы оно выполняло следующий фрагмент кода:

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();

Whenval is of type unsigned short или unsigned int преобразование форматирования происходит так, как если бы оно выполняло следующий фрагмент кода:

bool failed = use_facet<
  num_put<charT, ostreambuf_iterator<charT, traits>>
    >(getloc()).put(*this, *this, fill(),
      static_cast<unsigned long>(val)).failed();

Когдаval is of type, float преобразование форматирования происходит так, как если бы оно выполняло следующий фрагмент кода:

bool failed = use_facet<
  num_put<charT, ostreambuf_iterator<charT, traits>>
    >(getloc()).put(*this, *this, fill(),
      static_cast<double>(val)).failed();

Первый аргумент предоставляет объект ostreambuf_­iterator<> класса, который является итератором для классаbasic_­ostream<>. Он обходит ostreams и использует streambufs напрямую. Класс locale полагается на эти типы как на свой интерфейс к iostreams, поскольку для гибкости он абстрагирован от прямой зависимости от ostream. Второй параметр - это ссылка на подобъект базового класса типа ios_­base. Он предоставляет спецификации форматирования, такие как ширина поля и языковой стандарт, из которого можно получить другие фасеты. Если failed есть, true то это setstate(badbit)может вызвать исключение и вернуться.

Returns: *this.

30.7.5.2.3 basic_­ostream​::​operator<< [ostream.inserters]

basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& (*pf)(basic_ostream<charT, traits>&));

Effects: Никто. Не работает как функция форматированного вывода (как описано в[ostream.formatted.reqmts]).

Returns: pf(*this).321

basic_ostream<charT, traits>& operator<<(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));

Effects: Звонки pf(*this). Этот модуль вставки не работает как функция форматированного вывода (как описано в разделе[ostream.formatted.reqmts]).

Returns: *this.322

basic_ostream<charT, traits>& operator<<(ios_base& (*pf)(ios_base&));

Effects: Звонки pf(*this). Этот модуль вставки не работает как функция форматированного вывода (как описано в разделе[ostream.formatted.reqmts]).

Returns: *this.

basic_ostream<charT, traits>& operator<<(basic_streambuf<charT, traits>* sb);

Effects: Ведет себя какunformatted output function. После того, как объект-часовой создан, if sb является нулевым вызовом setstate(badbit) (который может вызывать ios_­base​::​failure).

Получает символы изsb и вставляет их в *this. Символы считываютсяsb и вставляются до тех пор, пока не произойдет одно из следующих событий:

  • конец файла встречается во входной последовательности;

  • вставка в выходную последовательность не выполняется (в этом случае вставляемый символ не извлекается);

  • исключение возникает при получении символа изsb.

Если функция не вставляет символы, она вызывает setstate(failbit) (что может вызвать throw ios_­base​::​​failure ([iostate.flags])). Если было брошено исключение при извлечении персонажа, функция устанавливает failbit в состоянии ошибки, и если failbit на в exceptions() пойманном исключении является вызвано повторно.

Returns: *this.

basic_ostream<charT, traits>& operator<<(nullptr_t);

Effects: Эквивалентен:

return *this << s;

гдеs определяется реализацией NTCTS.

См., Например, сигнатуру функции endl(basic_­ostream&).

См., Например, сигнатуру функции dec(ios_­base&).

30.7.5.2.4 Character inserter function templates [ostream.inserters.character]

template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& out, charT c); template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& out, char c); // specialization template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, char c); // signed and unsigned template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, signed char c); template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, unsigned char c);

Effects: Ведет себя какformatted output function офout. Создает последовательность символовseq. Еслиc имеет тип, char а символьный тип потока - нет char, тоseq состоит из out.widen(c); в противном случаеseq состоит из c. Определяет заполнение,seq как описано в[ostream.formatted.reqmts]. Вставляетseq в out. Звонкиos.width(0).

Returns: out.

template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& out, const charT* s); template<class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& out, const char* s); template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, const char* s); template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, const signed char* s); template<class traits> basic_ostream<char, traits>& operator<<(basic_ostream<char, traits>& out, const unsigned char* s);

Requires: s не должен быть нулевым указателем.

Effects: Работает как форматированный модуль вставки (как описано в разделе[ostream.formatted.reqmts]) изout. Создает последовательность символовseq изn символов , начиная сs, каждый расширена с помощью out.widen() ([basic.ios.members]), гдеn это число , которое будет вычислено как бы:

  • traits​::​length(s) для перегрузки, где первый аргумент имеет тип, basic_­ostream<charT, traits>& а второй - типа const charT*, а также для перегрузки, где первый аргумент имеет тип, basic_­ostream<char, traits>& а второй - тип const char*,

  • char_­traits<char>​::​length(s) для перегрузки, где первый аргумент имеет тип, basic_­ostream<charT, traits>& а второй - тип const char*,

  • traits​::​length(reinterpret_­cast<const char*>(s)) для двух других перегрузок.

Определяет заполнение,seq как описано в[ostream.formatted.reqmts]. Вставляетseq в out. Звонкиwidth(0).

Returns: out.

30.7.5.3 Unformatted output functions [ostream.unformatted]

Каждая функция неформатированного вывода начинает выполнение с создания объекта класса sentry. Если этот объект возвращается trueпри преобразовании в значение типа bool, функция пытается сгенерировать запрошенный вывод. Если во время вывода возникает исключение, то ios​::​badbit включается323 в *thisсостоянии ошибки. Если (exceptions() & badbit) != 0 тогда исключение генерируется повторно. В любом случае функция неформатированного вывода завершается уничтожением охранного объекта, а затем, если не было сгенерировано исключение, возвращает значение, указанное для функции неформатированного вывода.

basic_ostream<charT, traits>& put(char_type c);

Effects: Ведет себя как неформатированная функция вывода (как описано выше). После создания сторожевого объектаc, если возможно , вставляет символ .324

В противном случае вызовы setstate(badbit) (которые могут бросить ios_­base​::​failure ([iostate.flags])).

Returns: *this.

basic_ostream& write(const char_type* s, streamsize n);

Effects: Ведет себя как неформатированная функция вывода (как описано выше). После создания сторожевого объекта получает символы для вставки из последовательных мест массива, первый элемент которого обозначен s.325 Символы вставляются до тех пор, пока не произойдет одно из следующих событий:

  • n вставляются символы;

  • вставка в выходную последовательность не выполняется (в этом случае вызывается функция setstate(badbit), которая может throw ios_­base​::​failure ([iostate.flags])).

Returns: *this.

basic_ostream& flush();

Effects: Ведет себя как неформатированная функция вывода (как описано выше). Если rdbuf() не является нулевым указателем, создает объект-часовой. Если этот объект возвращаетсяtrue при преобразовании в значение типа,bool функция вызывает rdbuf()->pubsync(). Если эта функция возвращает -1 вызов setstate(badbit) (который может throw ios_­base​::​failure ([iostate.flags])). В противном случае, если объект-часовой возвращаетсяfalse, ничего не делает.

Returns: *this.

не вызывая ios​::​failure броска.

Обратите внимание, что эта функция не перегружена для типов signed char и unsigned char.

Обратите внимание, что эта функция не перегружена для типов signed char и unsigned char.

30.7.5.4 Standard basic_­ostream manipulators [ostream.manip]

template <class charT, class traits> basic_ostream<charT, traits>& endl(basic_ostream<charT, traits>& os);

Effects: os.put(os.widen('\n'))Тогда звонит os.flush().

Returns: os.

template <class charT, class traits> basic_ostream<charT, traits>& ends(basic_ostream<charT, traits>& os);

Effects: Вставляет нулевой символ в выходную последовательность: calls os.put(charT()).

Returns: os.

template <class charT, class traits> basic_ostream<charT, traits>& flush(basic_ostream<charT, traits>& os);

Effects: Звонки os.flush().

Returns: os.

30.7.5.5 Rvalue stream insertion [ostream.rvalue]

template <class charT, class traits, class T> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>&& os, const T& x);

Effects: Как будто по:os << x;

Returns:os.

Remarks: Эта функция не должна участвовать в разрешении перегрузки, если выражениеos << x не сформировано правильно.