30 Input/output library [input.output]

30.1 General [input.output.general]

В этом разделе описаны компоненты, которые программы C ++ могут использовать для выполнения операций ввода / вывода.

В следующих подпунктах описываются требования к параметрам потока и компонентам для прямого объявления iostreams, предопределенных объектов iostreams, базовых классов iostreams, буферизации потока, форматирования и манипуляторов потока, потоков строк и потоков файлов, как показано в таблице 106.

Таблица 106 - Сводная информация о библиотеке ввода / вывода
Подпункт Заголовок (ы)
[iostreams.requirements] Требования
[iostream.forward] Форвардные декларации <iosfwd>
[iostream.objects] Стандартные объекты iostream <iostream>
[iostreams.base] Базовые классы Iostreams <ios>
[stream.buffers] Буферы потока <streambuf>
[iostream.format] Форматирование и манипуляторы <istream>
<ostream>
<iomanip>
[string.streams] Строковые потоки <sstream>
[file.streams] Файловые потоки <fstream>
[filesystems] Файловые системы <filesystem>
[c.files] Файлы библиотеки C <cstdio>
<cinttypes>

На рисунке [fig:streampos] показаны отношения между различными типами, описанными в этом разделе. Линия от A до B указывает на то, что является псевдонимом (например, ЬурейеЕ) для B или , что определен в терминах B .

figstreampos traits_pos_type_char traits_pos_type_char char_traits<char> ::pos_type streampos streampos streampos traits_pos_type_char->streampos traits_pos_type_char->streampos iostreams.limits.pos traits_pos_type_wchar_t traits_pos_type_wchar_t char_traits<wchar_t> ::pos_type wstreampos wstreampos wstreampos traits_pos_type_wchar_t->wstreampos traits_pos_type_wchar_t->wstreampos iostreams.limits.pos fpos fpos fpos<mbstate_t> streampos->fpos streampos->fpos iostream.forward wstreampos->fpos wstreampos->fpos iostream.forward traits_off_type_char traits_off_type_char char_traits<char> ::off_type streamoff streamoff streamoff traits_off_type_char->streamoff traits_off_type_char->streamoff iostreams.limits.pos traits_off_type_wchar_t traits_off_type_wchar_t char_traits<wchar_t> ::off_type traits_off_type_wchar_t->streamoff traits_off_type_wchar_t->streamoff iostreams.limits.pos streamoff_type streamoff_type signed integer type sufficient for O/S maximum file size streamoff->streamoff_type streamoff->streamoff_type stream.types streamsize streamsize streamsize streamsize_type streamsize_type signed integer type represents characters xfered or buffer sizes streamsize->streamsize_type streamsize->streamsize_type stream.types
Рисунок 7 - Типы положения, смещения и размера потока [ненормативный]

30.2 Iostreams requirements [iostreams.requirements]

30.2.1 Imbue limitations [iostream.limits.imbue]

Никакая функция, описанная в Пункте, не описана, [input.output] за исключением ios_­base​::​imbue и basic_­filebuf​::​pubimbue вызывает любой экземпляр basic_­ios​::​imbue или basic_­streambuf​::​imbue для вызова. Если какая-либо пользовательская функция вызывается из функции, объявленной в Clause, [input.output] или как замещающая виртуальная функция любого класса, объявленного в Clause, [input.output]вызывается imbue, поведение не определено.

30.2.2 Positioning type limitations [iostreams.limits.pos]

Классы Clause [input.output] с аргументами шаблона charT и traits ведут себя, как описано, если traits​::​pos_­type и traits​::​off_­type есть streampos и streamoff соответственно. За исключением случаев, явно указанных ниже, их поведение, когда traits​::​pos_­type и traits​::​off_­type являются другими типами, определяется реализацией.

В классах пункта [input.output], параметр шаблона с именем charT представляет собой элемент из набора типов , содержащих char, wchar_­tи любых других реализации определенных типов символов , которые удовлетворяют требования , предъявляемые к характеру , на которых любые из компонентов iostream может быть реализованным.

30.2.3 Thread safety [iostreams.threadsafety]

Одновременный доступ к объекту потока ( [string.streams], [file.streams]), объекту буфера потока ( [stream.buffers]) или потоку библиотеки C ( [c.files]) несколькими потоками может привести к гонке данных ( [intro.multithread]), если не указано иное ( [iostream.objects]). [ Note: Гонки данных приводят к неопределенному поведению ( [intro.multithread]). ] end note

Если один поток делает вызов библиотеки , a которая записывает значение потока и, как следствие, другой поток считывает это значение из потока через библиотеку вызова b таким образом, что это не приведет к гонке данных, а затем a«s синхронизирует запись с b» прочитал.

30.3 Forward declarations [iostream.forward]

30.3.1 Header <iosfwd> synopsis [iosfwd.syn]

namespace std {
  template<class charT> class char_traits;
  template<> class char_traits<char>;
  template<> class char_traits<char16_t>;
  template<> class char_traits<char32_t>;
  template<> class char_traits<wchar_t>;

  template<class T> class allocator;

  template <class charT, class traits = char_traits<charT>>
    class basic_ios;
  template <class charT, class traits = char_traits<charT>>
    class basic_streambuf;
  template <class charT, class traits = char_traits<charT>>
    class basic_istream;
  template <class charT, class traits = char_traits<charT>>
    class basic_ostream;
  template <class charT, class traits = char_traits<charT>>
    class basic_iostream;

  template <class charT, class traits = char_traits<charT>,
      class Allocator = allocator<charT>>
    class basic_stringbuf;
  template <class charT, class traits = char_traits<charT>,
      class Allocator = allocator<charT>>
    class basic_istringstream;
  template <class charT, class traits = char_traits<charT>,
      class Allocator = allocator<charT>>
    class basic_ostringstream;
  template <class charT, class traits = char_traits<charT>,
      class Allocator = allocator<charT>>
    class basic_stringstream;

  template <class charT, class traits = char_traits<charT>>
    class basic_filebuf;
  template <class charT, class traits = char_traits<charT>>
    class basic_ifstream;
  template <class charT, class traits = char_traits<charT>>
    class basic_ofstream;
  template <class charT, class traits = char_traits<charT>>
    class basic_fstream;

  template <class charT, class traits = char_traits<charT>>
    class istreambuf_iterator;
  template <class charT, class traits = char_traits<charT>>
    class ostreambuf_iterator;

  using ios  = basic_ios<char>;
  using wios = basic_ios<wchar_t>;

  using streambuf = basic_streambuf<char>;
  using istream   = basic_istream<char>;
  using ostream   = basic_ostream<char>;
  using iostream  = basic_iostream<char>;

  using stringbuf     = basic_stringbuf<char>;
  using istringstream = basic_istringstream<char>;
  using ostringstream = basic_ostringstream<char>;
  using stringstream  = basic_stringstream<char>;

  using filebuf  = basic_filebuf<char>;
  using ifstream = basic_ifstream<char>;
  using ofstream = basic_ofstream<char>;
  using fstream  = basic_fstream<char>;

  using wstreambuf = basic_streambuf<wchar_t>;
  using wistream   = basic_istream<wchar_t>;
  using wostream   = basic_ostream<wchar_t>;
  using wiostream  = basic_iostream<wchar_t>;

  using wstringbuf     = basic_stringbuf<wchar_t>;
  using wistringstream = basic_istringstream<wchar_t>;
  using wostringstream = basic_ostringstream<wchar_t>;
  using wstringstream  = basic_stringstream<wchar_t>;

  using wfilebuf  = basic_filebuf<wchar_t>;
  using wifstream = basic_ifstream<wchar_t>;
  using wofstream = basic_ofstream<wchar_t>;
  using wfstream  = basic_fstream<wchar_t>;

  template <class state> class fpos;
  using streampos  = fpos<char_traits<char>::state_type>;
  using wstreampos = fpos<char_traits<wchar_t>::state_type>;
}

Аргументы шаблона по умолчанию описаны как появляющиеся как <iosfwd> в синопсисе других заголовков, так и в их синопсисе, но он хорошо сформирован, чтобы включать оба <iosfwd> и один или несколько других заголовков.287

Реализация отвечает за реализацию заголовков, чтобы включение <iosfwd> и другие заголовки не нарушали правила о множественном появлении аргументов по умолчанию.

30.3.2 Overview [iostream.forward.overview]

Шаблон класса специализация basic_­ios<charT, traits> служит в качестве виртуального базового класса для шаблонов классов basic_­istream, basic_­ostreamи шаблоны классов , полученных из них. basic_­iostream - это шаблон класса, производный от обоих basic_­istream<charT, traits> и basic_­ostream<charT, traits>.

Специализация шаблона класса basic_­streambuf<charT, traits> служит базовым классом для шаблонов классов basic_­stringbuf и basic_­filebuf.

Специализация шаблона класса basic_­istream<charT, traits> служит базовым классом для шаблонов классов basic_­istringstream и basic_­ifstream.

Специализация шаблона класса basic_­ostream<charT, traits> служит базовым классом для шаблонов классов basic_­ostringstream и basic_­ofstream.

Специализация шаблона класса basic_­iostream<charT, traits> служит базовым классом для шаблонов классов basic_­stringstream и basic_­fstream.

Другие typedef-names определяют экземпляры шаблонов классов, специализированных для типов char или wchar_­t.

Специализации шаблона класса fpos используются для указания информации о положении файла.

Типы streampos и wstreampos используются для позиционирования потоков, специализирующихся на char и wchar_­t соответственно.

[ Note: Этот синопсис предполагает замкнутость между streampos и char_­traits<char>. Реализация может избежать этой замкнутости путем замены эквивалентных типов. Один из способов сделать это может быть

template<class stateT> class fpos { ... };      // depends on nothing
using _STATE = ... ;             // implementation private declaration of stateT

using streampos = fpos<_STATE>;

template<> struct char_traits<char> {
  using pos_type = streampos;
}

end note]

30.4 Standard iostream objects [iostream.objects]

30.4.1 Header <iostream> synopsis [iostream.syn]

#include <ios>          // see [ios.syn]
#include <streambuf>    // see [streambuf.syn]
#include <istream>      // see [istream.syn]
#include <ostream>      // see [ostream.syn]

namespace std {
  extern istream cin;
  extern ostream cout;
  extern ostream cerr;
  extern ostream clog;

  extern wistream wcin;
  extern wostream wcout;
  extern wostream wcerr;
  extern wostream wclog;
}

30.4.2 Overview [iostream.objects.overview]

В этом разделе имя типа FILE относится к типу, FILE объявленному в .<cstdio>

Заголовок <iostream> объявляет объекты, которые связывают объекты со стандартными потоками C, предусмотренными функциями, объявленными в <cstdio> ( [c.files]), и включает все заголовки, необходимые для использования этих объектов.

Объекты конструируются, и ассоциации устанавливаются в некоторый момент до или во время первого ios_­base​::​Init конструирования объекта класса , и в любом случае до начала выполнения тела main . 288 Объекты не уничтожаются во время выполнения программы. 289 Результаты включения <iostream> в блок трансляции должны быть такими, как если бы он был <iostream> определен как экземпляр ios_­base​::​Init со статической продолжительностью хранения.

Операции смешивания для соответствующих потоков с широкими и узкими символами следует той же семантике, что и смешивание таких операций с FILEs, как указано в стандартной библиотеке C.

Одновременный доступ к синхронизированным ( [ios.members.static]) стандартного объекта iostream отформатирован и неотформатированная input и output функции или стандартный поток С несколькими потоками , не должно приводить к data race. [ Note: Пользователи должны по-прежнему синхронизировать одновременное использование этих объектов и потоков несколькими потоками, если они хотят избежать чередования символов. ] end note

См. Также: ISO C 7.21.2.

Если это возможно, реализациям рекомендуется инициализировать объекты раньше, чем требуется.

Конструкторы и деструкторы для статических объектов могут обращаться к этим объектам для чтения ввода stdin или записи вывода в stdout или stderr.

30.4.3 Narrow stream objects [narrow.stream.objects]

istream cin;

Объект cin управляет вводом из буфера потока, связанного с объектом stdin, объявленным в .<cstdio>

После cin инициализации объекта cin.tie() возвращается &cout. В остальном его состояние такое же, как требуется для basic_­ios<char>​::​init.

ostream cout;

Объект cout управляет выводом в буфер потока, связанный с объектом stdout, объявленным в . <cstdio>

ostream cerr;

Объект cerr управляет выводом в буфер потока, связанный с объектом stderr, объявленным в .<cstdio>

После cerr инициализации объекта cerr.flags() & unitbuf ненулевое значение и cerr.tie() возвращается &cout. В остальном его состояние такое же, как требуется для basic_­ios<char>​::​init.

ostream clog;

Объект clog управляет выводом в буфер потока, связанный с объектом stderr, объявленным в . <cstdio>

30.4.4 Wide stream objects [wide.stream.objects]

wistream wcin;

Объект wcin управляет вводом из буфера потока, связанного с объектом stdin, объявленным в .<cstdio>

После wcin инициализации объекта wcin.tie() возвращается &wcout. В остальном его состояние такое же, как требуется для basic_­ios<wchar_­t>​::​init.

wostream wcout;

Объект wcout управляет выводом в буфер потока, связанный с объектом stdout, объявленным в . <cstdio>

wostream wcerr;

Объект wcerr управляет выводом в буфер потока, связанный с объектом stderr, объявленным в .<cstdio>

После wcerr инициализации объекта wcerr.flags() & unitbuf ненулевое значение и wcerr.tie() возвращается &wcout. В остальном его состояние такое же, как требуется для basic_­ios<wchar_­t>​::​init.

wostream wclog;

Объект wclog управляет выводом в буфер потока, связанный с объектом stderr, объявленным в . <cstdio>

30.5 Iostreams base classes [iostreams.base]

30.5.1 Header <ios> synopsis [ios.syn]

#include <iosfwd>   // see [iosfwd.syn]

namespace std {
  using streamoff  = implementation-defined;
  using streamsize = implementation-defined;
  template <class stateT> class fpos;

  class ios_base;
  template <class charT, class traits = char_traits<charT>>
    class basic_ios;

  // [std.ios.manip], manipulators
  ios_base& boolalpha  (ios_base& str);
  ios_base& noboolalpha(ios_base& str);

  ios_base& showbase   (ios_base& str);
  ios_base& noshowbase (ios_base& str);

  ios_base& showpoint  (ios_base& str);
  ios_base& noshowpoint(ios_base& str);

  ios_base& showpos    (ios_base& str);
  ios_base& noshowpos  (ios_base& str);

  ios_base& skipws     (ios_base& str);
  ios_base& noskipws   (ios_base& str);

  ios_base& uppercase  (ios_base& str);
  ios_base& nouppercase(ios_base& str);

  ios_base& unitbuf    (ios_base& str);
  ios_base& nounitbuf  (ios_base& str);

  // [adjustfield.manip], adjustfield
  ios_base& internal   (ios_base& str);
  ios_base& left       (ios_base& str);
  ios_base& right      (ios_base& str);

  // [basefield.manip], basefield
  ios_base& dec        (ios_base& str);
  ios_base& hex        (ios_base& str);
  ios_base& oct        (ios_base& str);

  // [floatfield.manip], floatfield
  ios_base& fixed      (ios_base& str);
  ios_base& scientific (ios_base& str);
  ios_base& hexfloat   (ios_base& str);
  ios_base& defaultfloat(ios_base& str);

  // [error.reporting], error reporting
  enum class io_errc {
    stream = 1
  };

  template <> struct is_error_code_enum<io_errc> : public true_type { };
  error_code make_error_code(io_errc e) noexcept;
  error_condition make_error_condition(io_errc e) noexcept;
  const error_category& iostream_category() noexcept;
}

30.5.2 Types [stream.types]

using streamoff = implementation-defined;

Тип streamoff является синонимом одного из основных целочисленных типов со знаком, достаточного размера для представления максимально возможного размера файла для операционной системы.290

using streamsize = implementation-defined;

Тип streamsize является синонимом одного из основных целочисленных типов со знаком. Он используется для представления количества символов, переданных в операции ввода-вывода, или размера буферов ввода-вывода.291

Обычно long long.

streamsize используется в большинстве мест , где ISO C будет использовать size_­t. streamsize Можно использовать в большинстве size_­tслучаев, за исключением strstreambuf конструкторов, требующих отрицательных значений. Вероятно, это должен быть подписанный тип, соответствующий size_­t (что и вызывает Posix.2 ssize_­t).

30.5.3 Class ios_­base [ios.base]

namespace std {
  class ios_base {
  public:
    class failure; // see below

    // [ios::fmtflags], fmtflags
    using fmtflags = T1;
    static constexpr fmtflags boolalpha = unspecified;
    static constexpr fmtflags dec = unspecified;
    static constexpr fmtflags fixed = unspecified;
    static constexpr fmtflags hex = unspecified;
    static constexpr fmtflags internal = unspecified;
    static constexpr fmtflags left = unspecified;
    static constexpr fmtflags oct = unspecified;
    static constexpr fmtflags right = unspecified;
    static constexpr fmtflags scientific = unspecified;
    static constexpr fmtflags showbase = unspecified;
    static constexpr fmtflags showpoint = unspecified;
    static constexpr fmtflags showpos = unspecified;
    static constexpr fmtflags skipws = unspecified;
    static constexpr fmtflags unitbuf = unspecified;
    static constexpr fmtflags uppercase = unspecified;
    static constexpr fmtflags adjustfield = see below;
    static constexpr fmtflags basefield = see below;
    static constexpr fmtflags floatfield = see below;

    // [ios::iostate], iostate
    using iostate = T2;
    static constexpr iostate badbit = unspecified;
    static constexpr iostate eofbit = unspecified;
    static constexpr iostate failbit = unspecified;
    static constexpr iostate goodbit = see below;

    // [ios::openmode], openmode
    using openmode = T3;
    static constexpr openmode app = unspecified;
    static constexpr openmode ate = unspecified;
    static constexpr openmode binary = unspecified;
    static constexpr openmode in = unspecified;
    static constexpr openmode out = unspecified;
    static constexpr openmode trunc = unspecified;

    // [ios::seekdir], seekdir
    using seekdir = T4;
    static constexpr seekdir beg = unspecified;
    static constexpr seekdir cur = unspecified;
    static constexpr seekdir end = unspecified;

    class Init;

    // [fmtflags.state], fmtflags state
    fmtflags flags() const;
    fmtflags flags(fmtflags fmtfl);
    fmtflags setf(fmtflags fmtfl);
    fmtflags setf(fmtflags fmtfl, fmtflags mask);
    void unsetf(fmtflags mask);

    streamsize precision() const;
    streamsize precision(streamsize prec);
    streamsize width() const;
    streamsize width(streamsize wide);

    // [ios.base.locales], locales
    locale imbue(const locale& loc);
    locale getloc() const;

    // [ios.base.storage], storage
    static int xalloc();
    long&  iword(int index);
    void*& pword(int index);

    // destructor:
    virtual ~ios_base();

    // [ios.base.callback], callbacks;
    enum event { erase_event, imbue_event, copyfmt_event };
    using event_callback = void (*)(event, ios_base&, int index);
    void register_callback(event_callback fn, int index);

    ios_base(const ios_base&) = delete;
    ios_base& operator=(const ios_base&) = delete;

    static bool sync_with_stdio(bool sync = true);

  protected:
    ios_base();

  private:
    static int index;  // exposition only
    long*  iarray;     // exposition only
    void** parray;     // exposition only
  };
}

ios_­base определяет несколько типов членов:

  • тип failure, определяемый либо как производный класс, system_­error либо как синоним класса, производного от system_­error;

  • класс Init;

  • три типа Bitmask, fmtflags, iostate, и openmode;

  • перечислимого типа, seekdir.

Он поддерживает несколько типов данных:

  • информация о состоянии, отражающая целостность буфера потока;

  • управляющая информация, которая влияет на то, как интерпретировать (форматировать) входные последовательности и как генерировать (форматировать) выходные последовательности;

  • дополнительная информация, которая хранится программой для личного пользования.

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

  • static int index, определяет следующий доступный уникальный индекс для массивов целых чисел или указателей, поддерживаемых для частного использования программой, инициализированных неопределенным значением;

  • long* iarray, указывает на первый элемент long массива произвольной длины, предназначенного для частного использования программой;

  • void** parray, указывает на первый элемент массива указателей произвольной длины, предназначенного для частного использования программой.

end note]

30.5.3.1 Types [ios.types]

30.5.3.1.1 Class ios_­base​::​failure [ios::failure]

namespace std {
  class ios_base::failure : public system_error {
  public:
    explicit failure(const string& msg, const error_code& ec = io_errc::stream);
    explicit failure(const char* msg, const error_code& ec = io_errc::stream);
  };
}

Реализацию разрешено определять ios_­base​::​failure как синоним класса с функциональностью, эквивалентной классу, ios_­base​::​failure показанному в этом подпункте. [ Note: Когда ios_­base​::​failure является синонимом другого типа, он должен предоставлять вложенный тип failureдля имитации имени внедренного класса. ] Класс определяет базовый класс для типов всех объектов, созданных как исключения функциями в библиотеке iostreams, чтобы сообщать об ошибках, обнаруженных во время операций с буфером потока.end notefailure

При ios_­base​::​failure создании исключений реализации должны предоставлять значения, ec которые определяют конкретную причину сбоя. [ Note: Ошибки, возникающие в операционной системе, обычно сообщаются как system_­category() ошибки со значением ошибки, равным номеру ошибки, сообщаемому операционной системой. Об ошибках, возникающих в библиотеке потоков, обычно сообщается как error_­code(io_­errc​::​stream, iostream_­category()). ] end note

explicit failure(const string& msg, const error_code& ec = io_errc::stream);

Effects: Создает объект класса failure , создавая базовый класс с помощью msg и ec.

explicit failure(const char* msg, const error_code& ec = io_errc::stream);

Effects: Создает объект класса failure , создавая базовый класс с помощью msg и ec.

30.5.3.1.2 Type ios_­base​::​fmtflags [ios::fmtflags]

using fmtflags = T1;

Тип fmtflags - это bitmask type. Установка его элементов имеет эффекты, указанные в Табл 107.

Таблица 107 - fmtflags эффекты
ЭлементЭффект (ы), если установлен
boolalpha вставить и извлечь bool тип в алфавитном формате
dec преобразует целочисленный ввод или генерирует целочисленный вывод в десятичной системе счисления
fixed генерировать вывод с плавающей запятой в нотации с фиксированной запятой
hex преобразует целочисленный ввод или генерирует целочисленный вывод в шестнадцатеричной системе счисления
internal добавляет символы заливки в обозначенную внутреннюю точку в определенном сгенерированном выводе или идентично, right если такая точка не обозначена
left добавляет символы заливки справа (конечные позиции) определенного сгенерированного вывода
oct преобразует целочисленный ввод или генерирует целочисленный вывод в восьмеричной системе счисления
right добавляет символы заполнения слева (начальные позиции) определенного сгенерированного вывода
scientific генерирует вывод с плавающей запятой в экспоненциальной нотации
showbase генерирует префикс, указывающий числовую основу сгенерированного целочисленного вывода
showpoint безоговорочно генерирует символ десятичной точки в сгенерированном выводе с плавающей запятой
showpos генерирует + знак в неотрицательном сгенерированном числовом выводе
skipws пропускает начальные пробелы перед определенными операциями ввода
unitbuf сбрасывает вывод после каждой операции вывода
uppercase заменяет определенные строчные буквы их эквивалентами в верхнем регистре в сгенерированном выводе

Тип fmtflags также определяет константы, указанные в Табл 108.

Таблица 108 - fmtflags константы
ПостоянныйДопустимые значения
adjustfield left | right | internal
basefield dec | oct | hex
floatfield scientific | fixed

30.5.3.1.3 Type ios_­base​::​iostate [ios::iostate]

using iostate = T2;

Типом iostate является a bitmask type , содержащий элементы, указанные в таблице 109.

Таблица 109 - iostate эффекты
ЭлементЭффект (ы), если установлен
badbit указывает на потерю целостности во входной или выходной последовательности (например, на неисправимую ошибку чтения из файла);
eofbit указывает, что операция ввода достигла конца входной последовательности;
failbit указывает, что операция ввода не смогла прочитать ожидаемые символы или что операция вывода не смогла сгенерировать желаемые символы.

Тип iostate также определяет константу:

  • goodbit, нулевое значение.

30.5.3.1.4 Type ios_­base​::​openmode [ios::openmode]

using openmode = T3;

Тип openmode - это bitmask type. Он содержит элементы, указанные в таблице 110.

Таблица 110 - openmode эффекты
ЭлементЭффект (ы), если установлен
app стремиться закончить перед каждой записью
ate открывать и стремиться к завершению сразу после открытия
binary выполнять ввод и вывод в двоичном режиме (в отличие от текстового режима)
in открыт для ввода
out открыт для вывода
trunc обрезать существующий поток при открытии

30.5.3.1.5 Type ios_­base​::​seekdir [ios::seekdir]

using seekdir = T4;

Тип seekdir - это объект enumerated type , содержащий элементы, указанные в таблице 111.

Таблица 111 - seekdir эффекты
ЭлементИмея в виду
beg запросить поиск (для последующего ввода или вывода) относительно начала потока
cur запросить поиск относительно текущей позиции в последовательности
end запросить поиск относительно текущего конца последовательности

30.5.3.1.6 Class ios_­base​::​Init [ios::Init]

namespace std {
  class ios_base::Init {
  public:
    Init();
    ~Init();
  private:
    static int init_cnt; // exposition only
  };
}

Класс Init описывает объект, конструкция которого обеспечивает создание восьми объектов, объявленных в <iostream> ( [iostream.objects]), которые связывают буферы файловых потоков со стандартными потоками C, предусмотренными функциями, объявленными в <cstdio>.

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

  • static int init_­cnt, подсчитывает количество вызовов конструктора и деструктора для класса Init, инициализированного нулем.

Init();

Effects: Создает объект класса Init. Формирует и инициализирует объекты cin, cout, cerr, clog, wcin, wcout, wcerr, и , wclog если они еще не были построены и инициализируется.

~Init();

Effects: Уничтожает объект класса Init. Если нет других экземпляров класса все еще существует, звонки cout.flush(), cerr.flush(), clog.flush(), wcout.flush(), wcerr.flush(), wclog.flush().

30.5.3.2 ios_­base state functions [fmtflags.state]

fmtflags flags() const;

Returns: Информация управления форматом как для ввода, так и для вывода.

fmtflags flags(fmtflags fmtfl);

Postconditions: fmtfl == flags().

Returns: Предыдущее значение flags().

fmtflags setf(fmtflags fmtfl);

Effects: Наборы fmtfl в flags().

Returns: Предыдущее значение flags().

fmtflags setf(fmtflags fmtfl, fmtflags mask);

Effects: Очищает mask в flags(), наборы fmtfl & mask в flags().

Returns: Предыдущее значение flags().

void unsetf(fmtflags mask);

Effects: Очищает mask в flags().

streamsize precision() const;

Returns: Точность, генерируемая при определенных выходных преобразованиях.

streamsize precision(streamsize prec);

Postconditions: prec == precision().

Returns: Предыдущее значение precision().

streamsize width() const;

Returns: Минимальная ширина поля (количество символов), генерируемая при определенных преобразованиях вывода.

streamsize width(streamsize wide);

Postconditions: wide == width().

Returns: Предыдущее значение width().

30.5.3.3 ios_­base functions [ios.base.locales]

locale imbue(const locale& loc);

Effects: Вызывает каждую зарегистрированную пару обратного вызова (fn, index) ( [ios.base.callback]) (*fn)(imbue_­event, *this, index) в такой момент, когда вызов ios_­base​::​getloc() изнутри fn возвращает новое значение локали loc.

Returns: Предыдущее значение getloc().

Postconditions: loc == getloc().

locale getloc() const;

Returns: Если языковой стандарт не был добавлен, копия глобального языкового стандарта C ++ locale(), действующая на момент создания. В противном случае возвращает встроенный языковой стандарт, который будет использоваться для выполнения операций ввода и вывода, зависящих от языкового стандарта.

30.5.3.4 ios_­base static members [ios.members.static]

bool sync_with_stdio(bool sync = true);

Returns: true если предыдущее состояние standard iostream objects было синхронизировано, в противном случае возвращается false. При первом вызове функция возвращается true.

Effects: Если какая-либо операция ввода или вывода произошла с использованием стандартных потоков до вызова, эффект определяется реализацией. В противном случае, вызванный с false аргументом, он позволяет стандартным потокам работать независимо от стандартных потоков C.

Когда стандартный объект iostream str находится synchronized со стандартным потоком stdio f, эффект вставки символа с c помощью

fputc(f, c);

такой же, как эффект

str.rdbuf()->sputc(c);

для любых последовательностей символов; эффект извлечения персонажа с c помощью

c = fgetc(f);

такой же, как эффект

c = str.rdbuf()->sbumpc();

для любых последовательностей символов; и эффект отодвигая персонажа c по

ungetc(c, f);

такой же, как эффект

str.rdbuf()->sputbackc(c);

для любой последовательности символов.292

Это означает, что операции над стандартным объектом iostream могут произвольно сочетаться с операциями над соответствующим потоком stdio. На практике синхронизация обычно означает, что стандартный объект iostream и стандартный объект stdio совместно используют буфер.

30.5.3.5 ios_­base storage functions [ios.base.storage]

static int xalloc();

Returns: index ++.

Remarks: Одновременный доступ к этой функции нескольких потоков не должен приводить к возникновению файла data race.

long& iword(int idx);

Effects: Если iarray - нулевой указатель, выделяет массив long неопределенного размера и сохраняет указатель на его первый элемент в iarray. Затем функция расширяет массив, на который указывает, по iarray мере необходимости, чтобы включить элемент iarray[idx]. Каждый вновь выделенный элемент массива инициализируется нулем. Возвращенная ссылка недействительна после любых других операций с объектом. 293 Однако значение указанного хранилища сохраняется, так что до следующего вызова copyfmtвызов iword с тем же индексом дает еще одну ссылку на то же значение. Если функция не работает 294 и *this является подобъектом базового класса basic_­ios<> объекта или подобъекта, эффект эквивалентен вызову basic_­ios<>​::​setstate(badbit) производного объекта (который может вызвать ошибку failure).

Returns: Об успехе iarray[idx]. В случае сбоя действительный long& инициализируется значением 0.

void*& pword(int idx);

Effects: Если parray - нулевой указатель, выделяет массив указателей на void неопределенный размер и сохраняет указатель на свой первый элемент в parray. Затем функция расширяет массив, на который указывает, по parray мере необходимости, чтобы включить элемент parray[idx]. Каждый вновь выделенный элемент массива инициализируется нулевым указателем. Возвращенная ссылка недействительна после любых других операций с объектом. Однако значение указанного хранилища сохраняется, так что до следующего вызова copyfmtвызов pword с тем же индексом дает еще одну ссылку на то же значение. Если функция не работает 295 и *this является подобъектом базового класса basic_­ios<> объекта или подобъекта, эффект эквивалентен вызову basic_­ios<>​::​setstate(badbit) производного объекта (который может вызвать ошибку failure).

Returns: Об успехе parray[idx]. В случае ошибки действительный void*& инициализируется значением 0.

Remarks: После последующего обращения к pword(int) тому же объекту более раннее возвращаемое значение может быть недействительным.

Реализация может реализовать как целочисленный массив, на который указывает, так iarray и массив указателей, на который указывает parray как разреженные структуры данных, возможно, с одноэлементным кешем для каждой.

например, потому что он не может выделить место.

например, потому что он не может выделить место.

30.5.3.6 ios_­base callbacks [ios.base.callback]

void register_callback(event_callback fn, int index);

Effects: Регистрирует пару (fn, index) таким образом, чтобы во время вызовов imbue() ( [ios.base.locales]) copyfmt(), или ~ios_­base() ( [ios.base.cons]) функция fn вызывалась с аргументом index. Зарегистрированные функции вызываются при возникновении события в порядке, обратном регистрации. Функции, зарегистрированные при активной функции обратного вызова, не вызываются до следующего события.

Requires: Функция fn не должна вызывать исключений.

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

30.5.3.7 ios_­base constructors/destructor [ios.base.cons]

ios_base();

Effects: ios_­base После построения каждый член имеет неопределенное значение. Члены объекта должны быть инициализированы вызовом basic_­ios​::​init перед первым использованием объекта или перед его уничтожением, в зависимости от того, что произойдет раньше; в противном случае поведение не определено.

~ios_base();

Effects: Уничтожает объект класса ios_­base. Вызывает каждую зарегистрированную пару обратного вызова (fn, index) ( [ios.base.callback]) как (*fn)(​erase_­event, *this, index) в то время, когда любая ios_­base функция-член, вызываемая изнутри, fn имеет четко определенные результаты.

30.5.4 Class template fpos [fpos]

namespace std {
  template <class stateT> class fpos {
  public:
    // [fpos.members], members
    stateT state() const;
    void state(stateT);
  private;
    stateT st; // exposition only
  };
}

30.5.4.1 fpos members [fpos.members]

void state(stateT s);

Effects: Назначает s в st.

stateT state() const;

Returns: Текущее значение st.

30.5.4.2 fpos requirements [fpos.operations]

Разрешены операции, указанные в таблице 112 . В этой таблице

  • P относится к экземпляру fpos,

  • p и q обращайтесь к значениям типа P,

  • O относится к типу streamoff,

  • o относится к значению типа streamoff,

  • sz относится к значению типа streamsize и

  • i относится к значению типа int.

Таблица 112 - Требования к типу позиции
ВыражениеТип возвратаОперативныйУтверждение / примечание
семантикадо / после состояния
P(i) p == P(i)
примечание: предполагается деструктор.
P p(i);
P p = i;
Postconditions: p == P(i).
P(o) fpos конвертирует из offset
O(p) streamoff конвертируется в offset P(O(p)) == p
p == q конвертируемый в bool == является отношением эквивалентности
p != q конвертируемый в bool !(p == q)
q = p + o
p += o
fpos + компенсировать q - o == p
q = p - o
p -= o
fpos - компенсировать q + o == p
o = p - q streamoff расстояние q + o == p
streamsize(o)
O(sz)
streamsize
streamoff
обращает
новообращенных
streamsize(O(sz)) == sz
streamsize(O(sz)) == sz

[ Note: Каждая реализация должна предоставлять перегруженные операторы для fpos объектов, чтобы удовлетворить требованиям [fpos.operations]. Не указано, являются ли эти операторы членами fposглобальных операторов или предоставлены каким-либо другим образом. ]end note

Операции потока, возвращающие значение типа, traits​::​pos_­type возвращаются P(O(-1)) как недопустимое значение, чтобы сигнализировать об ошибке. Если это значение используется в качестве аргумента в любой istream, ostreamили streambuf члена , который принимает значение типа , traits​::​pos_­type то поведение этой функции не определено.

30.5.5 Class template basic_­ios [ios]

30.5.5.1 Overview [ios.overview]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class basic_ios : public ios_base {
  public:
    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;

    // [iostate.flags], flags functions
    explicit operator bool() const;
    bool operator!() const;
    iostate rdstate() const;
    void clear(iostate state = goodbit);
    void setstate(iostate state);
    bool good() const;
    bool eof()  const;
    bool fail() const;
    bool bad()  const;

    iostate exceptions() const;
    void exceptions(iostate except);

    // [basic.ios.cons], constructor/destructor
    explicit basic_ios(basic_streambuf<charT, traits>* sb);
    virtual ~basic_ios();

    // [basic.ios.members], members
    basic_ostream<charT, traits>* tie() const;
    basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);

    basic_streambuf<charT, traits>* rdbuf() const;
    basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);

    basic_ios& copyfmt(const basic_ios& rhs);

    char_type fill() const;
    char_type fill(char_type ch);

    locale imbue(const locale& loc);

    char      narrow(char_type c, char dfault) const;
    char_type widen(char c) const;

    basic_ios(const basic_ios&) = delete;
    basic_ios& operator=(const basic_ios&) = delete;

  protected:
    basic_ios();
    void init(basic_streambuf<charT, traits>* sb);
    void move(basic_ios& rhs);
    void move(basic_ios&& rhs);
    void swap(basic_ios& rhs) noexcept;
    void set_rdbuf(basic_streambuf<charT, traits>* sb);

  };
}

30.5.5.2 basic_­ios constructors [basic.ios.cons]

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

Effects: Создает объект класса basic_­ios, присваивая начальные значения его объектам-членам путем вызова init(sb).

basic_ios();

Effects: Создает объект класса basic_­ios ( [ios.base.cons]), оставляя его объекты-члены неинициализированными. Объект должен быть инициализирован вызовом basic_­ios​::​init до его первого использования или до его уничтожения, в зависимости от того, что произойдет раньше; в противном случае поведение не определено.

~basic_ios();

Remarks: Деструктор не разрушает rdbuf().

void init(basic_streambuf<charT, traits>* sb);

Postconditions: Постусловия этой функции указаны в таблице 113.

Таблица 113 - basic_­ios​::​init() эффекты
ЭлементЦенить
rdbuf() sb
tie() 0
rdstate() goodbit если sb не является нулевым указателем, в противном случае badbit.
exceptions() goodbit
flags() skipws | dec
width() 0
precision() 6
fill() widen(' ')
getloc() копия значения, возвращаемого locale()
iarray нулевой указатель
parray нулевой указатель

30.5.5.3 Member functions [basic.ios.members]

basic_ostream<charT, traits>* tie() const;

Returns: Выходная последовательность, которая tied должна (синхронизироваться) с последовательностью, управляемой буфером потока.

basic_ostream<charT, traits>* tie(basic_ostream<charT, traits>* tiestr);

Requires: Если tiestr не равно нулю, он tiestr не должен быть доступен при просмотре связанного списка связанных объектов потока, начиная с tiestr->tie().

Postconditions: tiestr == tie().

Returns: Предыдущее значение tie().

basic_streambuf<charT, traits>* rdbuf() const;

Returns: Указатель на streambuf связанный с потоком.

basic_streambuf<charT, traits>* rdbuf(basic_streambuf<charT, traits>* sb);

Postconditions: sb == rdbuf().

Effects: Звонки clear().

Returns: Предыдущее значение rdbuf().

locale imbue(const locale& loc);

Effects: Вызывает ios_­base​::​imbue(loc) ( [ios.base.locales]), а если rdbuf() != 0 то rdbuf()->pubimbue(loc) ( [streambuf.locales]).

Returns: Приоритетное значение ios_­base​::​imbue().

char narrow(char_type c, char dfault) const;

Returns: use_­facet<ctype<char_­type>>(getloc()).narrow(c, dfault)

char_type widen(char c) const;

Returns: use_­facet<ctype<char_­type>>(getloc()).widen(c)

char_type fill() const;

Returns: Символ, используемый для заполнения (заполнения) преобразования вывода до указанной ширины поля.

char_type fill(char_type fillch);

Postconditions: traits​::​eq(fillch, fill()).

Returns: Предыдущее значение fill().

basic_ios& copyfmt(const basic_ios& rhs);

Effects: Если (this == &rhs) ничего не делает. В противном случае присваивает объектам *this -членам соответствующих объектов-членов rhs следующим образом:

  1. 1.вызывает каждую зарегистрированную пару обратных вызовов (fn, index) как (*fn)(erase_­event, *this, index);

  2. 2.присваивается объектам *this -членам соответствующих объектов-членов rhs, за исключением того, что

    • rdstate(),, rdbuf()и exceptions() остаются без изменений;

    • копируется содержимое массивов, на которые указывает pword и iword , а не сами указатели; 296 а также

    • если какие-либо вновь сохраненные значения указателя *this указывают на объекты, хранящиеся вне объекта, rhs и эти объекты уничтожаются при rhs уничтожении, вновь сохраненные значения указателя изменяются, чтобы указывать на вновь созданные копии объектов;

  3. 3.вызывает каждую пару обратных вызовов, скопированную из rhs as (*fn)(copyfmt_­event, *this, index);

  4. 4.звонки exceptions(rhs.exceptions()).

[ Note: Второй проход через пары обратного вызова позволяет pword обнулить скопированное значение, либо глубоко скопировать его референт, либо подсчитать ссылку, либо выполнить другие специальные действия. ]end note

Postconditions: Постусловия этой функции указаны в таблице 114.

Таблица 114 - basic_­ios​::​copyfmt() эффекты
ЭлементЦенить
rdbuf() unchanged
tie() rhs.tie()
rdstate() unchanged
exceptions() rhs.exceptions()
flags() rhs.flags()
width() rhs.width()
precision() rhs.precision()
fill() rhs.fill()
getloc() rhs.getloc()

Returns: *this.

void move(basic_ios& rhs); void move(basic_ios&& rhs);

Postconditions: *this должен иметь состояние, которое rhs было до вызова функции, за исключением того rdbuf() , что должен возвращать 0. rhs должен быть в допустимом, но неуказанном состоянии, за исключением того rhs.rdbuf() , что должен возвращать то же значение, что и перед вызовом функции, и rhs.tie() должен возвращать 0.

void swap(basic_ios& rhs) noexcept;

Effects: Состояниями *this и rhs необходимо поменять местами, за исключением того rdbuf() , что они должны возвращать то же значение, что и перед вызовом функции, и rhs.rdbuf() должны возвращать то же значение, что и перед вызовом функции.

void set_rdbuf(basic_streambuf<charT, traits>* sb);

Requires: sb != nullptr.

Effects: Связывает basic_­streambuf объект, на который указывает sb этот поток, без вызова clear().

Postconditions: rdbuf() == sb.

Throws: Ничего такого.

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

30.5.5.4 basic_­ios flags functions [iostate.flags]

explicit operator bool() const;

Returns: !fail().

bool operator!() const;

Returns: fail().

iostate rdstate() const;

Returns: Состояние ошибки буфера потока.

void clear(iostate state = goodbit);

Postconditions: Если rdbuf() != 0 тогда state == rdstate(); иначе rdstate() == (state | ios_­base​::​badbit).

Effects: Если ((state | (rdbuf() ? goodbit : badbit)) & exceptions()) == 0, вернется. В противном случае функция генерирует объект класса basic_­ios​::​failure, построенный со значениями аргументов, определяемыми реализацией.

void setstate(iostate state);

Effects: Звонки clear(rdstate() | state) (которые могут бросить basic_­ios​::​failure).

bool good() const;

Returns: rdstate() == 0

bool eof() const;

Returns: true если eofbit установлен в rdstate().

bool fail() const;

Returns: true если failbit или badbit установлен в rdstate().297

bool bad() const;

Returns: true если badbit установлен в rdstate().

iostate exceptions() const;

Returns: Маска, определяющая, какие элементы установлены в rdstate() вызове исключения.

void exceptions(iostate except);

Postconditions: except == exceptions().

Effects: Звонки clear(rdstate()).

Проверка badbit также на fail() историческую практику.

30.5.6 ios_­base manipulators [std.ios.manip]

30.5.6.1 fmtflags manipulators [fmtflags.manip]

ios_base& boolalpha(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​boolalpha).

Returns: str.

ios_base& noboolalpha(ios_base& str);

Effects: Звонки str.unsetf(ios_­base​::​boolalpha).

Returns: str.

ios_base& showbase(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​showbase).

Returns: str.

ios_base& noshowbase(ios_base& str);

Effects: Звонки str.unsetf(ios_­base​::​showbase).

Returns: str.

ios_base& showpoint(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​showpoint).

Returns: str.

ios_base& noshowpoint(ios_base& str);

Effects: Звонки str.unsetf(ios_­base​::​showpoint).

Returns: str.

ios_base& showpos(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​showpos).

Returns: str.

ios_base& noshowpos(ios_base& str);

Effects: Звонки str.unsetf(ios_­base​::​showpos).

Returns: str.

ios_base& skipws(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​skipws).

Returns: str.

ios_base& noskipws(ios_base& str);

Effects: Звонки str.unsetf(ios_­base​::​skipws).

Returns: str.

ios_base& uppercase(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​uppercase).

Returns: str.

ios_base& nouppercase(ios_base& str);

Effects: Звонки str.unsetf(ios_­base​::​uppercase).

Returns: str.

ios_base& unitbuf(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​unitbuf).

Returns: str.

ios_base& nounitbuf(ios_base& str);

Effects: Звонки str.unsetf(ios_­base​::​unitbuf).

Returns: str.

30.5.6.2 adjustfield manipulators [adjustfield.manip]

ios_base& internal(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​internal, ios_­base​::​adjustfield).

Returns: str.

ios_base& left(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​left, ios_­base​::​adjustfield).

Returns: str.

ios_base& right(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​right, ios_­base​::​adjustfield).

Returns: str.

30.5.6.3 basefield manipulators [basefield.manip]

ios_base& dec(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​dec, ios_­base​::​basefield).

Returns: str298.

ios_base& hex(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​hex, ios_­base​::​basefield).

Returns: str.

ios_base& oct(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​oct, ios_­base​::​basefield).

Returns: str.

Сигнатура функции dec(ios_­base&) может быть вызвана сигнатурой функции, basic_­ostream& stream​::​operator<<(ios_­base& (*)(ios_­base&)) чтобы разрешить выражениям формы cout << dec изменять флаги формата, хранящиеся в cout.

30.5.6.4 floatfield manipulators [floatfield.manip]

ios_base& fixed(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​fixed, ios_­base​::​floatfield).

Returns: str.

ios_base& scientific(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​scientific, ios_­base​::​floatfield).

Returns: str.

ios_base& hexfloat(ios_base& str);

Effects: Звонки str.setf(ios_­base​::​fixed | ios_­base​::​scientific, ios_­base​::​floatfield).

Returns: str.

[ Note: Более очевидное использование ios_­base​::​hex для указания шестнадцатеричного формата с плавающей запятой изменило бы смысл существующих четко определенных программ. C ++ 2003 не придает значения комбинации fixed и scientific. ]end note

ios_base& defaultfloat(ios_base& str);

Effects: Звонки str.unsetf(ios_­base​::​floatfield).

Returns: str.

30.5.6.5 Error reporting [error.reporting]

error_code make_error_code(io_errc e) noexcept;

Returns: error_­code(static_­cast<int>(e), iostream_­category()).

error_condition make_error_condition(io_errc e) noexcept;

Returns: error_­condition(static_­cast<int>(e), iostream_­category()).

const error_category& iostream_category() noexcept;

Returns: Ссылка на объект типа, производного от класса error_­category.

Объектные default_­error_­condition и equivalent виртуальные функции должны вести себя, как указано для класса error_­category. name Виртуальная функция объекта должна возвращать указатель на строку "iostream".

30.6 Stream buffers [stream.buffers]

30.6.1 Header <streambuf> synopsis [streambuf.syn]

namespace std {
  template <class charT, class traits = char_traits<charT>>
    class basic_streambuf;
  using streambuf  = basic_streambuf<char>;
  using wstreambuf = basic_streambuf<wchar_t>;
}

Заголовок <streambuf> определяет типы, которые управляют вводом и выводом character последовательностей.

30.6.2 Stream buffer requirements [streambuf.reqts]

Буферы потоков могут накладывать различные ограничения на последовательности, которыми они управляют. Некоторые ограничения:

  • Управляемая входная последовательность не читается.

  • Управляемая выходная последовательность не может быть записана.

  • Управляемые последовательности могут быть связаны с содержимым других представлений для последовательностей символов, таких как внешние файлы.

  • Управляемые последовательности могут поддерживать операции directly с ассоциированными последовательностями или из них.

  • Управляемые последовательности могут налагать ограничения на то, как программа может читать символы из последовательности, записывать символы в последовательность, возвращать символы во входную последовательность или изменять положение потока.

Каждая последовательность характеризуется тремя указателями, которые, если они не равны нулю, все указывают на один и тот же charT объект массива. Объект массива представляет в любой момент (под) последовательность символов из этой последовательности. Операции, выполняемые над последовательностью, изменяют значения, хранящиеся в этих указателях, выполняют чтение и запись непосредственно в или из связанных последовательностей, а также изменяют «позицию потока» и состояние преобразования по мере необходимости для поддержания этой взаимосвязи подпоследовательностей. Три указателя:

  • адрес beginning pointer, или наименьший адрес элемента в массиве (называемый xbeg здесь);

  • адрес next pointer, или следующий элемент, который является текущим кандидатом на чтение или запись ( xnext здесь называется );

  • end pointerили первый элемент адрес за концом массива ( так называемый xend здесь).

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

  • Если xnext не является нулевым указателем, то xbeg и xend также должны быть ненулевыми указателями на тот же charT массив, как описано выше; в противном случае xbeg и xend также должно быть недействительным.

  • Если xnext это не нулевой указатель и xnext < xend для выходной последовательности, то write position доступен. В этом случае *xnext должен быть назначен в качестве следующего элемента для записи (для помещения или сохранения символьного значения в последовательность).

  • Если xnext это не нулевой указатель и xbeg < xnext для входной последовательности, то putback position доступен. В этом случае xnext[-1] должен иметь определенное значение и быть следующим (предыдущим) элементом для хранения символа, который возвращается во входную последовательность.

  • Если xnext это не нулевой указатель и xnext < xend для входной последовательности, то read position доступен. В этом случае *xnext должен иметь определенное значение и быть следующим элементом для чтения (для получения или для получения символьного значения из последовательности).

30.6.3 Class template basic_­streambuf [streambuf]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class basic_streambuf {
  public:
    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;

    virtual ~basic_streambuf();

    // [streambuf.locales], locales
    locale   pubimbue(const locale& loc);
    locale   getloc() const;

    // [streambuf.buffer], buffer and positioning
    basic_streambuf* pubsetbuf(char_type* s, streamsize n);
    pos_type pubseekoff(off_type off, ios_base::seekdir way,
                        ios_base::openmode which
                          = ios_base::in | ios_base::out);
    pos_type pubseekpos(pos_type sp,
                        ios_base::openmode which
                          = ios_base::in | ios_base::out);
    int      pubsync();

    // Get and put areas
    // [streambuf.pub.get], get area
    streamsize in_avail();
    int_type snextc();
    int_type sbumpc();
    int_type sgetc();
    streamsize sgetn(char_type* s, streamsize n);

    // [streambuf.pub.pback], putback
    int_type sputbackc(char_type c);
    int_type sungetc();

    // [streambuf.pub.put], put area
    int_type   sputc(char_type c);
    streamsize sputn(const char_type* s, streamsize n);

  protected:
    basic_streambuf();
    basic_streambuf(const basic_streambuf& rhs);
    basic_streambuf& operator=(const basic_streambuf& rhs);

    void swap(basic_streambuf& rhs);

    // [streambuf.get.area], get area access
    char_type* eback() const;
    char_type* gptr()  const;
    char_type* egptr() const;
    void       gbump(int n);
    void       setg(char_type* gbeg, char_type* gnext, char_type* gend);

    // [streambuf.put.area], put area access
    char_type* pbase() const;
    char_type* pptr() const;
    char_type* epptr() const;
    void       pbump(int n);
    void       setp(char_type* pbeg, char_type* pend);

    // [streambuf.virtuals], virtual functions
    // [streambuf.virt.locales], locales
    virtual void imbue(const locale& loc);

    // [streambuf.virt.buffer], buffer management and positioning
    virtual basic_streambuf* setbuf(char_type* s, streamsize n);
    virtual pos_type seekoff(off_type off, ios_base::seekdir way,
                             ios_base::openmode which
                               = ios_base::in | ios_base::out);
    virtual pos_type seekpos(pos_type sp,
                             ios_base::openmode which
                               = ios_base::in | ios_base::out);
    virtual int      sync();

    // [streambuf.virt.get], get area
    virtual streamsize showmanyc();
    virtual streamsize xsgetn(char_type* s, streamsize n);
    virtual int_type   underflow();
    virtual int_type   uflow();

    // [streambuf.virt.pback], putback
    virtual int_type   pbackfail(int_type c = traits::eof());

    // [streambuf.virt.put], put area
    virtual streamsize xsputn(const char_type* s, streamsize n);
    virtual int_type   overflow(int_type c = traits::eof());
  };
}

Шаблон класса basic_­streambuf служит абстрактным базовым классом для получения различных stream buffers объектов, каждый из которых контролирует два character sequences:

  • персонаж input sequence;

  • персонаж output sequence.

30.6.3.1 basic_­streambuf constructors [streambuf.cons]

basic_streambuf();

Effects: Создает объект класса basic_­streambuf<charT, traits> и инициализирует:299

  • все его объекты-члены-указатели на нулевые указатели,

  • getloc() член в копию глобальной локали locale(), во время строительства.

Remarks: После getloc() инициализации члена результаты вызова функций-членов локали и полученных таким образом элементов фасетов можно безопасно кэшировать до следующего вызова этого члена imbue .

basic_streambuf(const basic_streambuf& rhs);

Effects: Создает копию rhs.

Postconditions:

  • eback() == rhs.eback()

  • gptr() == rhs.gptr()

  • egptr() == rhs.egptr()

  • pbase() == rhs.pbase()

  • pptr() == rhs.pptr()

  • epptr() == rhs.epptr()

  • getloc() == rhs.getloc()

~basic_streambuf();

Effects: Никто.

Конструктор по умолчанию защищен для класса, basic_­streambuf чтобы гарантировать, что могут быть созданы только объекты для классов, производных от этого класса.

30.6.3.2 basic_­streambuf public member functions [streambuf.members]

30.6.3.2.1 Locales [streambuf.locales]

locale pubimbue(const locale& loc);

Postconditions: loc == getloc().

Effects: Звонки imbue(loc).

Returns: Предыдущее значение getloc().

locale getloc() const;

Returns: Если pubimbue() когда-либо вызывалась, то последнее значение loc предоставлено, в противном случае - текущая глобальная локаль, locale()действующая на момент создания. Если вызван после того, pubimbue() как был вызван, но перед возвратом pubimbue (т. Е. Изнутри вызова imbue()), то он возвращает предыдущее значение.

30.6.3.2.2 Buffer management and positioning [streambuf.buffer]

basic_streambuf* pubsetbuf(char_type* s, streamsize n);

Returns: setbuf(s, n).

pos_type pubseekoff(off_type off, ios_base::seekdir way, ios_base::openmode which = ios_base::in | ios_base::out);

Returns: seekoff(off, way, which).

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

Returns: seekpos(sp, which).

int pubsync();

Returns: sync().

30.6.3.2.3 Get area [streambuf.pub.get]

streamsize in_avail();

Returns: Если позиция чтения доступна, возвращается egptr() - gptr(). В противном случае возвращается showmanyc().

int_type snextc();

Effects: Звонки sbumpc().

Returns: Если эта функция возвращается traits​::​eof(), возвращается traits​::​eof(). В противном случае возвращается sgetc().

int_type sbumpc();

Returns: Если позиция чтения входной последовательности недоступна, возвращается uflow(). В противном случае возвращает traits​::​to_­int_­type(*gptr()) и увеличивает следующий указатель для входной последовательности.

int_type sgetc();

Returns: Если позиция чтения входной последовательности недоступна, возвращается underflow(). В противном случае возвращается traits​::​to_­int_­type(*gptr()).

streamsize sgetn(char_type* s, streamsize n);

Returns: xsgetn(s, n).

30.6.3.2.4 Putback [streambuf.pub.pback]

int_type sputbackc(char_type c);

Returns: Если позиция возврата входной последовательности недоступна, или если traits​::​eq(c, gptr()[-1]) есть false, возвращается pbackfail(traits​::​to_­int_­type(c)). В противном случае уменьшает следующий указатель входной последовательности и возвращается traits​::​to_­int_­type(*gptr()).

int_type sungetc();

Returns: Если позиция возврата входной последовательности недоступна, возвращается pbackfail(). В противном случае уменьшает следующий указатель входной последовательности и возвращается traits​::​to_­int_­type(*gptr()).

30.6.3.2.5 Put area [streambuf.pub.put]

int_type sputc(char_type c);

Returns: Если позиция записи выходной последовательности недоступна, возвращается overflow(traits​::​to_­int_­type(c)). В противном случае сохраняет c в следующем указателе выходной последовательности, увеличивает указатель на единицу и возвращается traits​::​to_­int_­type(c).

streamsize sputn(const char_type* s, streamsize n);

Returns: xsputn(s, n).

30.6.3.3 basic_­streambuf protected member functions [streambuf.protected]

30.6.3.3.1 Assignment [streambuf.assign]

basic_streambuf& operator=(const basic_streambuf& rhs);

Effects: Назначает элементы данных rhs для *this.

Postconditions:

  • eback() == rhs.eback()

  • gptr() == rhs.gptr()

  • egptr() == rhs.egptr()

  • pbase() == rhs.pbase()

  • pptr() == rhs.pptr()

  • epptr() == rhs.epptr()

  • getloc() == rhs.getloc()

Returns: *this.

void swap(basic_streambuf& rhs);

Effects: Меняет местами элементы данных rhs и *this.

30.6.3.3.2 Get area access [streambuf.get.area]

char_type* eback() const;

Returns: Начальный указатель входной последовательности.

char_type* gptr() const;

Returns: Следующий указатель входной последовательности.

char_type* egptr() const;

Returns: Конечный указатель входной последовательности.

void gbump(int n);

Effects: Добавляет n к следующему указателю входной последовательности.

void setg(char_type* gbeg, char_type* gnext, char_type* gend);

Postconditions: gbeg == eback(),, gnext == gptr()и gend == egptr().

30.6.3.3.3 Put area access [streambuf.put.area]

char_type* pbase() const;

Returns: Начальный указатель выходной последовательности.

char_type* pptr() const;

Returns: Следующий указатель выходной последовательности.

char_type* epptr() const;

Returns: Конечный указатель выходной последовательности.

void pbump(int n);

Effects: Добавляет n к следующему указателю выходной последовательности.

void setp(char_type* pbeg, char_type* pend);

Postconditions: pbeg == pbase(),, pbeg == pptr()и pend == epptr().

30.6.3.4 basic_­streambuf virtual functions [streambuf.virtuals]

30.6.3.4.1 Locales [streambuf.virt.locales]

void imbue(const locale&);

Effects: Измените любые переводы в зависимости от языкового стандарта.

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

Default behavior: Ничего не делает.

30.6.3.4.2 Buffer management and positioning [streambuf.virt.buffer]

basic_streambuf* setbuf(char_type* s, streamsize n);

Effects: Влияет на буферизацию потока способом, который определяется отдельно для каждого класса, производного от basic_­streambuf этого пункта ( [stringbuf.virtuals], [filebuf.virtuals]).

Default behavior: Ничего не делает. Возврат this.

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

Effects: Изменяет позиции потока в одной или нескольких управляемых последовательностях способом, который определяется отдельно для каждого класса, производного от basic_­streambuf этого пункта ( [stringbuf.virtuals], [filebuf.virtuals]).

Default behavior: Возврат pos_­type(off_­type(-1)).

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

Effects: Изменяет позиции потока в одной или нескольких управляемых последовательностях способом, который определяется отдельно для каждого класса, производного от basic_­streambuf этого пункта ( [stringbuf], [filebuf]).

Default behavior: Возврат pos_­type(off_­type(-1)).

int sync();

Effects: Синхронизирует контролируемые последовательности с массивами. То есть, если не pbase() равно нулю, символы между pbase() и pptr() записываются в управляемую последовательность. Затем указатели могут быть при необходимости сброшены.

Returns: -1 при неудаче. Что составляет отказ, определяется каждым производным классом ( [filebuf.virtuals]).

Default behavior: Возвращает ноль.

30.6.3.4.3 Get area [streambuf.virt.get]

streamsize showmanyc();300

Returns: Оценка количества символов, доступных в последовательности, или -1. Если он возвращает положительное значение, то последовательные вызовы underflow() не будут возвращаться traits​::​eof() до тех пор, пока из потока не будет извлечено хотя бы это количество символов. Если showmanyc() возвращается -1, вызовы underflow() или uflow() завершатся ошибкой.301

Default behavior: Возвращает ноль.

Remarks: Использует traits​::​eof().

streamsize xsgetn(char_type* s, streamsize n);

Effects: Присваивает до n символов последовательным элементам массива, первый элемент которого обозначен s. Назначенные символы считываются из входной последовательности, как если бы при повторных вызовах sbumpc(). Назначение прекращается, когда либо n были назначены символы, либо sbumpc() возвращался вызов traits​::​eof().

Returns: Количество присвоенных символов.302

Remarks: Использует traits​::​eof().

int_type underflow();

Remarks: Открытые члены basic_­streambuf вызывают эту виртуальную функцию только в том случае, если она gptr() равна нулю или gptr() >= egptr()

Returns: traits​::​to_­int_­type(c), где c является первым character из pending sequence, без перемещения позиции входной последовательности за ним. Если ожидающая последовательность пуста, функция возвращается, traits​::​eof() чтобы указать на сбой.

pending sequence Символов определяется как конкатенация

  • пустая последовательность, если она gptr() равна нулю, в противном случае символы в [gptr(), egptr()), за которыми следует

  • некоторая (возможно, пустая) последовательность символов, прочитанная из входной последовательности.

Это result character первый символ ожидающей последовательности, если он не пуст, в противном случае - следующий символ, который будет считан из входной последовательности.

Это backup sequence пустая последовательность, если она eback() равна нулю, в противном случае символы в [eback(), gptr()).

Effects: Функция устанавливает gptr() и так egptr() , что если ожидающая последовательность непуста, то не egptr() является нулевой, а символы в [gptr(), egptr()) являются символами в ожидающей последовательности, в противном случае либо gptr() имеет значение null, либо gptr() == egptr().

Если eback() и не gptr() равны нулю, функция не ограничена в отношении их содержимого, но «обычное условие резервного копирования» состоит в том, что либо

  • резервная последовательность содержит как минимум gptr() - eback() символы, и в этом случае символы [eback(), gptr()) соответствуют последним gptr() - eback() символам резервной последовательности, или

  • символы [gptr() - n, gptr()) соответствуют резервной последовательности (где n - длина резервной последовательности).

Default behavior: Возврат traits​::​eof().

int_type uflow();

Requires: Ограничения те же, что и для underflow(), за исключением того, что символ результата должен быть перенесен из ожидающей последовательности в резервную последовательность, а ожидающая последовательность не должна быть пустой перед передачей.

Default behavior: Звонки underflow(). Если underflow() возвращается traits​::​eof(), возвращается traits​::​eof(). В противном случае возвращает значение traits​::​to_­int_­type(*gptr()) и увеличивает значение следующего указателя для входной последовательности.

Returns: traits​::​eof() для обозначения отказа.

Морфемы слова showmanyc «es-how-many-see», а не «show-manic».

underflow или uflow может потерпеть неудачу из-за преждевременного создания исключения. Намерение состоит не только в том, чтобы звонки не возвращались, eof() но и в том, чтобы они вернулись «немедленно».

Классы, производные от, basic_­streambuf могут предоставить более эффективные способы реализации xsgetn() и xsputn() переопределения этих определений из базового класса.

30.6.3.4.4 Putback [streambuf.virt.pback]

int_type pbackfail(int_type c = traits::eof());

Remarks: Общедоступные функции basic_­streambuf вызывают эту виртуальную функцию только тогда, когда возвращается значение gptr() null gptr() == eback(), или . Другие вызовы также должны удовлетворять этому ограничению.traits​::​eq(traits​::​to_­char_­type(c), gptr()[-1])false

pending sequence Определяется как для underflow(), с изменениями , которые

  • Если traits​::​eq_­int_­type(c, traits​::​eof()) возвращается true, то входная последовательность копируется на один символ до того, как будет определена ожидающая последовательность.

  • Если traits​::​eq_­int_­type(c, traits​::​eof()) возвращается false, то c добавляется. Не указано, выполняется ли резервная копия входной последовательности или изменяется каким-либо иным образом.

Postconditions: В свою очередь, ограничения gptr(), eback()и pptr() такие же , как для underflow().

Returns: traits​::​eof() для обозначения отказа. Сбой может произойти из-за невозможности резервного копирования входной последовательности или из-за того, что по какой-либо другой причине указатели не могут быть установлены в соответствии с ограничениями. pbackfail() вызывается только тогда, когда возвращение действительно не удалось.

Возвращает какое-то значение, отличное от traits​::​eof() успешного.

Default behavior: Возврат traits​::​eof().

30.6.3.4.5 Put area [streambuf.virt.put]

streamsize xsputn(const char_type* s, streamsize n);

Effects: Записывает до n символов в выходную последовательность, как если бы при повторных вызовах sputc(c). Записанные символы получаются из последовательных элементов массива, первый элемент которого обозначен знаком s. Запись останавливается, когда либо n символы были написаны, либо sputc(c) возвращался вызов traits​::​eof(). Не указано, вызывает ли функция, overflow() когда pptr() == epptr() становится, true или она достигает тех же результатов другими способами.

Returns: Количество написанных символов.

int_type overflow(int_type c = traits::eof());

Effects: Использует некоторую начальную подпоследовательность символов pending sequence. Ожидающая последовательность определяется как конкатенация

  • пустая последовательность, если pbase() не равна нулю, в противном случае pptr() - pbase() символы, начинающиеся с pbase(), за которыми следует

  • пустая последовательность, если traits​::​eq_­int_­type(c, traits​::​eof()) возвращается true, в противном случае последовательность, состоящая из c.

Remarks: Функции-члены sputc() и sputn() вызывают эту функцию в случае, если в буфере размещения нет места, достаточного для размещения последовательности символов аргумента.

Requires: Каждое преобладающее определение этой виртуальной функции должно подчиняться следующим ограничениям:

  1. 1.Указывается влияние употребления символа на связанную выходную последовательность.303

  2. 2.Позвольте r быть количеством символов в ожидающей последовательности, которые не используются. Если не r равно нулю , то pbase() и pptr() должен быть установлен таким образом, чтобы: pptr() - pbase() == r а r символы , начинающиеся на pbase() это соответствующий выходной поток. В случае, если он r равен нулю (все символы ожидающей последовательности были израсходованы), то либо pbase() устанавливается nullptr, либо pbase() и pptr() оба установлены на одно и то же ненулевое значение.

  3. 3.Функция может завершиться ошибкой, если не удается добавить какой-либо символ в связанный выходной поток или если он не может быть установлен pbase() и в pptr() соответствии с вышеуказанными правилами.

Returns: traits​::​eof() или выдает исключение, если функция не работает.

В противном случае возвращает какое-либо значение, отличное от traits​::​eof() указания успеха.304

Default behavior: Возврат traits​::​eof().

То есть для каждого класса, производного от экземпляра basic_­streambuf в этом разделе ( [stringbuf], [filebuf]), дается спецификация того, как потребление символа влияет на связанную выходную последовательность. Нет требований к программному классу.

Обычно overflow возвращается, c чтобы указать на успех, за исключением тех случаев, когда traits​::​eq_­int_­type(c, traits​::​eof()) возвращается true, и в этом случае он возвращается traits​::​not_­eof(c).

30.7 Formatting and manipulators [iostream.format]

30.7.1 Header <istream> synopsis [istream.syn]

namespace std {
  template <class charT, class traits = char_traits<charT>>
    class basic_istream;

  using istream  = basic_istream<char>;
  using wistream = basic_istream<wchar_t>;

  template <class charT, class traits = char_traits<charT>>
    class basic_iostream;

  using iostream  = basic_iostream<char>;
  using wiostream = basic_iostream<wchar_t>;

  template <class charT, class traits>
    basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);

  template <class charT, class traits, class T>
    basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&& is, T&& x);
}

30.7.2 Header <ostream> synopsis [ostream.syn]

namespace std {
  template <class charT, class traits = char_traits<charT>>
    class basic_ostream;

  using ostream  = basic_ostream<char>;
  using wostream = basic_ostream<wchar_t>;

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

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

30.7.3 Header <iomanip> synopsis [iomanip.syn]

namespace std {
  // types T1, T2, ... are unspecified implementation types
  T1 resetiosflags(ios_base::fmtflags mask);
  T2 setiosflags  (ios_base::fmtflags mask);
  T3 setbase(int base);
  template<charT> T4 setfill(charT c);
  T5 setprecision(int n);
  T6 setw(int n);
  template <class moneyT> T7 get_money(moneyT& mon, bool intl = false);
  template <class moneyT> T8 put_money(const moneyT& mon, bool intl = false);
  template <class charT> T9 get_time(struct tm* tmb, const charT* fmt);
  template <class charT> T10 put_time(const struct tm* tmb, const charT* fmt);

  template <class charT>
    T11 quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\'));

  template <class charT, class traits, class Allocator>
    T12 quoted(const basic_string<charT, traits, Allocator>& s,
               charT delim = charT('"'), charT escape = charT('\\'));

  template <class charT, class traits, class Allocator>
    T13 quoted(basic_string<charT, traits, Allocator>& s,
               charT delim = charT('"'), charT escape = charT('\\'));

  template <class charT, class traits>
    T14 quoted(basic_string_view<charT, traits> s,
               charT delim = charT('"'), charT escape = charT('\\'));
}

30.7.4 Input streams [input.streams]

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

30.7.4.1 Class template basic_­istream [istream]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class basic_istream : 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;

    // [istream.cons], constructor/destructor
    explicit basic_istream(basic_streambuf<charT, traits>* sb);
    virtual ~basic_istream();

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

    // [istream.formatted], formatted input
    basic_istream<charT, traits>&
      operator>>(basic_istream<charT, traits>& (*pf)(basic_istream<charT, traits>&));
    basic_istream<charT, traits>&
      operator>>(basic_ios<charT, traits>& (*pf)(basic_ios<charT, traits>&));
    basic_istream<charT, traits>&
      operator>>(ios_base& (*pf)(ios_base&));

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

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

    // [istream.unformatted], unformatted input
    streamsize gcount() const;
    int_type get();
    basic_istream<charT, traits>& get(char_type& c);
    basic_istream<charT, traits>& get(char_type* s, streamsize n);
    basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);
    basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);
    basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb, char_type delim);

    basic_istream<charT, traits>& getline(char_type* s, streamsize n);
    basic_istream<charT, traits>& getline(char_type* s, streamsize n, char_type delim);

    basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::eof());
    int_type                      peek();
    basic_istream<charT, traits>& read    (char_type* s, streamsize n);
    streamsize                    readsome(char_type* s, streamsize n);

    basic_istream<charT, traits>& putback(char_type c);
    basic_istream<charT, traits>& unget();
    int sync();

    pos_type tellg();
    basic_istream<charT, traits>& seekg(pos_type);
    basic_istream<charT, traits>& seekg(off_type, ios_base::seekdir);

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

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

  // [istream.extractors], character extraction templates
  template<class charT, class traits>
    basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&, charT&);
  template<class traits>
    basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, unsigned char&);
  template<class traits>
    basic_istream<char, traits>& operator>>(basic_istream<char, traits>&, signed char&);

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

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

Две группы сигнатур функций-членов имеют общие свойства: formatted input functions (или extractors) и unformatted input functions. Обе группы функций ввода описываются так, как если бы они получали (или extract) ввод с characters помощью вызова rdbuf()->sbumpc() или rdbuf()->sgetc(). Они могут использовать других публичных членов istream.

Если rdbuf()->sbumpc() или rdbuf()->sgetc() возвращает traits​::​eof(), то функция ввода, если явно не указано иное, завершает свои действия и выполняет setstate(eofbit), что может вызвать throw ios_­base​::​failure ( [iostate.flags]), перед возвратом.

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

30.7.4.1.1 basic_­istream constructors [istream.cons]

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

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

Postconditions: gcount() == 0.

basic_istream(basic_istream&& rhs);

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

virtual ~basic_istream();

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

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

30.7.4.1.2 Class basic_­istream assign and swap [istream.assign]

basic_istream& operator=(basic_istream&& rhs);

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

Returns: *this.

void swap(basic_istream& rhs);

Effects: Звонки basic_­ios<charT, traits>​::​swap(rhs). Меняет значения, возвращаемые gcount() и rhs.gcount().

30.7.4.1.3 Class basic_­istream​::​sentry [istream::sentry]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class basic_istream<charT, traits>::sentry {
    using traits_type = traits;
    bool ok_; // exposition only
  public:
    explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false);
    ~sentry();
    explicit operator bool() const { return ok_; }
    sentry(const sentry&) = delete;
    sentry& operator=(const sentry&) = delete;
  };
}

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

explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false);

Effects: Если is.good() есть false, звонит is.setstate(failbit). В противном случае готовится к форматированному или неформатированному вводу. Во-первых, если is.tie() это не нулевой указатель, функция вызывает is.tie()->flush() синхронизацию выходной последовательности с любым связанным внешним потоком C. За исключением того, что этот вызов может быть подавлен, если область размещения is.tie() пуста. Кроме того, реализации разрешается отложить вызов до flush тех пор, пока не is.rdbuf()->underflow() произойдет вызов . Если такой вызов не происходит до того, как sentry объект будет уничтожен, вызов flush может быть полностью исключен. 305 Если noskipws равен нулю и is.flags() & ios_­base​::​skipws отличен от нуля, функция извлекает и отбрасывает каждый символ до тех пор, пока следующий доступный входной символ c является пробельным символом. Если is.rdbuf()->sbumpc() или is.rdbuf()->sgetc() возвращается traits​::​eof(), функция вызывает setstate(failbit | eofbit) (который может бросить ios_­base​::​failure).

Remarks: Конструктор

explicit sentry(basic_istream<charT, traits>& is, bool noskipws = false)

использует текущий встроенный языковой стандарт в is, чтобы определить, является ли следующий входной символ пробелом или нет.

Чтобы определить, является ли данный символ c пробельным символом, конструктор работает так, как если бы он выполнял следующий фрагмент кода:

const ctype<charT>& ctype = use_facet<ctype<charT>>(is.getloc());
if (ctype.is(ctype.space, c) != 0)
  // c is a whitespace character.

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

~sentry();

Effects: Никто.

explicit operator bool() const;

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

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

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

30.7.4.2 Formatted input functions [istream.formatted]

30.7.4.2.1 Common requirements [istream.formatted.reqmts]

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

Это делается без ios​::​failure броска.

30.7.4.2.2 Arithmetic extractors [istream.formatted.arithmetic]

operator>>(unsigned short& 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>>(bool& val); operator>>(void*& val);

Как и в случае со средствами вставки, эти экстракторы зависят от num_­get<> объекта локали для выполнения синтаксического анализа данных входного потока. Эти экстракторы действуют как функции форматированного ввода (как описано в разделе [istream.formatted.reqmts]). После создания объекта-часового преобразование происходит так, как если бы оно выполнялось следующим фрагментом кода:

using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
iostate err = iostate::goodbit;
use_facet<numget>(loc).get(*this, 0, *this, err, val);
setstate(err);

В приведенном выше фрагменте loc это закрытый член basic_­ios класса. [ Note: Первый аргумент предоставляет объект istreambuf_­iterator класса, который является итератором, указывающим на входной поток. Он обходит istreams и напрямую использует streambufs. ] Класс полагается на этот тип как на свой интерфейс , поэтому нет необходимости напрямую зависеть от него . end notelocaleistreamistream

operator>>(short& val);

Преобразование происходит так, как если бы оно было выполнено следующим фрагментом кода (с использованием тех же обозначений, что и для предыдущего фрагмента кода):

using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
iostate err = ios_base::goodbit;
long lval;
use_facet<numget>(loc).get(*this, 0, *this, err, lval);
if (lval < numeric_limits<short>::min()) {
  err |= ios_base::failbit;
  val = numeric_limits<short>::min();
} else if (numeric_limits<short>::max() < lval) {
  err |= ios_base::failbit;
  val = numeric_limits<short>::max();
}  else
  val = static_cast<short>(lval);
setstate(err);

operator>>(int& val);

Преобразование происходит так, как если бы оно было выполнено следующим фрагментом кода (с использованием тех же обозначений, что и для предыдущего фрагмента кода):

using numget = num_get<charT, istreambuf_iterator<charT, traits>>;
iostate err = ios_base::goodbit;
long lval;
use_facet<numget>(loc).get(*this, 0, *this, err, lval);
if (lval < numeric_limits<int>::min()) {
  err |= ios_base::failbit;
  val = numeric_limits<int>::min();
} else if (numeric_limits<int>::max() < lval) {
  err |= ios_base::failbit;
  val = numeric_limits<int>::max();
}  else
  val = static_cast<int>(lval);
setstate(err);

30.7.4.2.3 basic_­istream​::​operator>> [istream.extractors]

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

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

Returns: pf(*this).308

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

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

Returns: *this.

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

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

Returns: *this.

template<class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& in, charT* s); template<class traits> basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, unsigned char* s); template<class traits> basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char* s);

Effects: Ведет себя как отформатированный входной член (как описано в [istream.formatted.reqmts]) of in. После создания sentry объекта operator>> извлекает символы и сохраняет их в последовательных местах массива, первый элемент которого обозначен знаком s. Если width() больше нуля, то n есть width(). В противном случае n - это количество элементов самого большого массива, в char_­type котором может храниться завершение charT(). n - максимальное количество хранимых символов.

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

  • n-1 символы сохраняются;

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

  • пусть ct будет use_­facet<ctype<charT>>(in.getloc()), ct.is(ct.space, c) есть true.

operator>> затем сохраняет нулевой байт ( charT()) в следующей позиции, которая может быть первой позицией, если символы не были извлечены. operator>> потом звонит width(0).

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

Returns: in.

template<class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& in, charT& c); template<class traits> basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, unsigned char& c); template<class traits> basic_istream<char, traits>& operator>>(basic_istream<char, traits>& in, signed char& c);

Effects: Ведет себя как отформатированный входной член (как описано в [istream.formatted.reqmts]) of in. После создания sentry объекта из него извлекается символ in, если он доступен, и сохраняется в c. В противном случае функция вызывает in.setstate(failbit).

Returns: in.

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

Effects: Ведет себя как unformatted input function. Если sb равно нулю, вызывает setstate(failbit), который может throw ios_­base​::​failure ( [iostate.flags]). После того, как часовой объект построен, извлекает символы из *this и вставляет их в выходную последовательность, управляемую sb. Символы извлекаются и вставляются до тех пор, пока не произойдет одно из следующих событий:

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

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

  • возникает исключение (в этом случае исключение перехватывается).

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

Returns: *this.

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

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

30.7.4.3 Unformatted input functions [istream.unformatted]

Каждая неформатированная функция ввода начинает выполнение с создания объекта класса sentry с аргументом по умолчанию noskipws (вторым) аргументом true. Если sentry объект возвращается trueпри преобразовании в значение типа bool, функция пытается получить запрошенный ввод. В противном случае, если конструктор часового выходит, генерируя исключение, или если объект часового возвращается false, при преобразовании в значение типа boolфункция возвращается, не пытаясь получить какие-либо входные данные. В любом случае количество извлеченных символов равно 0; неформатированные входные функции, принимающие в качестве аргумента массив символов ненулевого размера, также должны сохранять нулевой символ (использование charT()) в первом месте массива. Если во время ввода возникает исключение, то ios​::​badbit он включается 310 в *thisсостоянии ошибки. ( basic_­ios<>​::​clear() Выброшенные исключения не перехватываются и не генерируются повторно.) Если (exceptions()&badbit) != 0 тогда исключение генерируется повторно. Он также считает количество извлеченных символов. Если исключение не было создано, оно заканчивается сохранением счетчика в объекте-члене и возвратом указанного значения. В любом случае sentry объект уничтожается до выхода из неформатированной функции ввода.

streamsize gcount() const;

Effects: Никто. Эта функция-член не ведет себя как неформатированная функция ввода (как описано выше).

Returns: Число символов, извлеченных последней неформатированной входной функцией-членом, вызванной для объекта.

int_type get();

Effects: Ведет себя как неформатированная функция ввода (как описано выше). После создания сторожевого объекта извлекает персонажа c, если он доступен. В противном случае вызовы функции setstate(failbit), которая может throw ios_­base​::​failure ( [iostate.flags]),

Returns: c если доступно, в противном случае traits​::​eof().

basic_istream<charT, traits>& get(char_type& c);

Effects: Ведет себя как неформатированная функция ввода (как описано выше). После создания сторожевого объекта извлекает персонажа, если он доступен, и назначает его c. 311 В противном случае вызывается функция setstate(failbit) (которая может throw ios_­base​::​failure ( [iostate.flags])).

Returns: *this.

basic_istream<charT, traits>& get(char_type* s, streamsize n, char_type delim);

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

  • n меньше единицы или n - 1 символы сохраняются;

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

  • traits​::​eq(c, delim) для следующего доступного входного символа c (в этом случае c не извлекается).

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

Returns: *this.

basic_istream<charT, traits>& get(char_type* s, streamsize n);

Effects: Звонки get(s, n, widen('\n')).

Returns: Значение, возвращаемое вызовом.

basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb, char_type delim);

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

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

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

  • traits​::​eq(c, delim) для следующего доступного входного символа c (в этом случае c не извлекается);

  • возникает исключение (в этом случае исключение перехватывается, но не генерируется повторно).

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

Returns: *this.

basic_istream<charT, traits>& get(basic_streambuf<char_type, traits>& sb);

Effects: Звонки get(sb, widen('\n')).

Returns: Значение, возвращаемое вызовом.

basic_istream<charT, traits>& getline(char_type* s, streamsize n, char_type delim);

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

  1. 1.конец файла происходит во входной последовательности (в этом случае функция вызывает setstate(eofbit));

  2. 2.traits​::​eq(c, delim) для следующего доступного входного символа c (в этом случае входной символ извлекается, но не сохраняется);314

  3. 3.n меньше единицы или n - 1 символы сохраняются (в этом случае функция вызывает setstate(​failbit)).

Эти условия проверяются в указанном порядке.315

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

В любом случае, если n он больше нуля, он затем сохраняет нулевой символ (использование charT()) в следующем последовательном месте массива.

Returns: *this.

[Example:

#include <iostream>

int main() {
  using namespace std;
  const int line_buffer_size = 100;

  char buffer[line_buffer_size];
  int line_number = 0;
  while (cin.getline(buffer, line_buffer_size, '\n') || cin.gcount()) {
    int count = cin.gcount();
    if (cin.eof())
      cout << "Partial final line";   // cin.fail() is false
    else if (cin.fail()) {
      cout << "Partial long line";
      cin.clear(cin.rdstate() & ~ios_base::failbit);
    } else {
      count--;                        // Don't include newline in count
      cout << "Line " << ++line_number;
    }
    cout << " (" << count << " chars): " << buffer << endl;
  }
}

end example]

basic_istream<charT, traits>& getline(char_type* s, streamsize n);

Returns: getline(s, n, widen('\n'))

basic_istream<charT, traits>& ignore(streamsize n = 1, int_type delim = traits::eof());

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

  • n != numeric_­limits<streamsize>​::​max() и n персонажи были извлечены до сих пор

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

  • traits​::​eq_­int_­type(traits​::​to_­int_­type(c), delim) для следующего доступного входного символа c (в этом случае c извлекается).

Remarks: Последнее условие никогда не произойдет, если traits​::​eq_­int_­type(delim, traits​::​eof()).

Returns: *this.

int_type peek();

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

Returns: traits​::​eof() если good() есть false. В противном случае возвращается rdbuf()->sgetc().

basic_istream<charT, traits>& read(char_type* s, streamsize n);

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

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

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

Returns: *this.

streamsize readsome(char_type* s, streamsize n);

Effects: Ведет себя как неформатированная функция ввода (как описано выше). После создания сторожевого объекта, если !good() вызовы, setstate(failbit) которые могут вызвать исключение, и возврат. В противном случае извлекает символы и сохраняет их в последовательных местах массива, первый элемент которого обозначен знаком s. Если rdbuf()->in_­avail() == -1, вызывает setstate(eofbit) (который может throw ios_­base​::​failure ( [iostate.flags])) и не извлекает символы;

  • Если rdbuf()->in_­avail() == 0, не извлекает символы

  • Если rdbuf()->in_­avail() > 0, извлекает min(rdbuf()->in_­avail(), n)).

Returns: Количество извлеченных символов.

basic_istream<charT, traits>& putback(char_type c);

Effects: Ведет себя как неформатированная функция ввода (как описано выше), за исключением того, что функция сначала очищается eofbit. После создания сторожевого объекта, если !good() вызовы, setstate(failbit) которые могут вызвать исключение, и возврат. Если rdbuf() не равно нулю, вызывает rdbuf->sputbackc(). Если rdbuf() имеет значение null, или если sputbackc() возвращается traits​::​eof(), вызывает setstate(badbit) (который может throw ios_­base​::​failure ( [iostate.flags])). [ Note: Эта функция не извлекает символы, поэтому при следующем вызове возвращается значение gcount() 0. ]end note

Returns: *this.

basic_istream<charT, traits>& unget();

Effects: Ведет себя как неформатированная функция ввода (как описано выше), за исключением того, что функция сначала очищается eofbit. После создания сторожевого объекта, если !good() вызовы, setstate(failbit) которые могут вызвать исключение, и возврат. Если rdbuf() не равно нулю, вызывает rdbuf()->sungetc(). Если rdbuf() имеет значение null, или если sungetc() возвращается traits​::​eof(), вызывает setstate(badbit) (который может throw ios_­base​::​failure ( [iostate.flags])). [ Note: Эта функция не извлекает символы, поэтому при следующем вызове возвращается значение gcount() 0. ]end note

Returns: *this.

int sync();

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

pos_type tellg();

Effects: Ведет себя как неформатированная функция ввода (как описано выше), за исключением того, что она не подсчитывает количество извлеченных символов и не влияет на значение, возвращаемое последующими вызовами gcount().

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

basic_istream<charT, traits>& seekg(pos_type pos);

Effects: Ведет себя как неформатированная функция ввода (как описано выше), за исключением того, что функция сначала очищает eofbit, она не подсчитывает количество извлеченных символов и не влияет на значение, возвращаемое последующими вызовами gcount(). После создания сторожевого объекта if fail() != trueвыполняется rdbuf()->pubseekpos(pos, ios_­base​::​in). В случае неудачи вызовы функции setstate(failbit) (которые могут выкинуть ios_­base​::​failure).

Returns: *this.

basic_istream<charT, traits>& seekg(off_type off, ios_base::seekdir dir);

Effects: Ведет себя как неформатированная функция ввода (как описано выше), за исключением того, что функция сначала очищает eofbit, не подсчитывает количество извлеченных символов и не влияет на значение, возвращаемое последующими вызовами gcount(). После создания сторожевого объекта if fail() != trueвыполняется rdbuf()->pubseekoff(off, dir, ios_­base​::​in). В случае неудачи вызовы функции setstate(​failbit) (которые могут выкинуть ios_­base​::​failure).

Returns: *this.

Это делается без ios​::​failure броска.

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

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

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

Поскольку последний входной символ «извлекается», он засчитывается в gcount(), даже если он не сохраняется.

Это позволяет вводной строке, которая точно заполняет буфер, без настройки failbit. Это отличается от исторической реализации AT&T.

Это означает, что пустая строка ввода не failbit требует установки.

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

30.7.4.4 Standard basic_­istream manipulators [istream.manip]

template <class charT, class traits> basic_istream<charT, traits>& ws(basic_istream<charT, traits>& is);

Effects: Ведет себя как an unformatted input function, за исключением того, что он не считает количество извлеченных символов и не влияет на значение, возвращаемое последующими вызовами is.gcount (). После создания сторожевой объект извлекает символы до тех пор, пока следующий доступный символ c является пробелом, или до тех пор, пока в последовательности не останется символов. Пробельные символы различаются по тому же критерию, что и символы sentry​::​sentry. Если ws прекращает извлечение символов, потому что их больше нет, он устанавливает eofbit, но не failbit.

Returns: is.

30.7.4.5 Rvalue stream extraction [istream.rvalue]

template <class charT, class traits, class T> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>&& is, T&& x);

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

is >> std::forward<T>(x);
return is;

Remarks: Эта функция не должна участвовать в разрешении перегрузки, если выражение is >> std​::​forward<T>(x) не сформировано правильно.

30.7.4.6 Class template basic_­iostream [iostreamclass]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class basic_iostream
    : public basic_istream<charT, traits>,
      public basic_ostream<charT, traits> {
  public:
    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;

    // [iostream.cons], constructor
    explicit basic_iostream(basic_streambuf<charT, traits>* sb);

    // [iostream.dest], destructor
    virtual ~basic_iostream();

  protected:
    // [iostream.cons], constructor
    basic_iostream(const basic_iostream& rhs) = delete;
    basic_iostream(basic_iostream&& rhs);

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

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

30.7.4.6.1 basic_­iostream constructors [iostream.cons]

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

Effects: Создает объект класса basic_­iostream, инициализируя подобъекты базового класса с помощью basic_­istream<charT, traits>(sb) и basic_­ostream<charT, traits>(sb).

Postconditions: rdbuf() == sb и gcount() == 0.

basic_iostream(basic_iostream&& rhs);

Effects: Перемещение конструкций из RValue rhs путем построения basic_­istream базового класса с move(rhs).

30.7.4.6.2 basic_­iostream destructor [iostream.dest]

virtual ~basic_iostream();

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

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

30.7.4.6.3 basic_­iostream assign and swap [iostream.assign]

basic_iostream& operator=(basic_iostream&& rhs);

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

void swap(basic_iostream& rhs);

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

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: Переместите конструкции из rvalue rhs. Это выполняется по умолчанию путем создания базового класса и вызова 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();

When val 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 не сформировано правильно.

30.7.6 Standard manipulators [std.manip]

Заголовок <iomanip> определяет несколько функций, которые поддерживают экстракторы и средства вставки, которые изменяют информацию, поддерживаемую классом ios_­base и его производными классами.

unspecified resetiosflags(ios_base::fmtflags mask);

Returns: Объект неопределенного типа, такой, что если out это объект типа, basic_­ostream<charT, traits> тогда выражение out << resetiosflags(mask) ведет себя так, как если бы оно было вызвано f(out, mask), или если in это объект типа, basic_­istream<charT, traits> тогда выражение in >> resetiosflags(​mask) ведет себя так, как если бы оно было вызвано f(in, mask), где функция f определяется как:326

void f(ios_base& str, ios_base::fmtflags mask) {
  // reset specified flags
  str.setf(ios_base::fmtflags(0), mask);
}

Выражение out << resetiosflags(mask) должно иметь тип basic_­ostream<charT, traits>& и значение out. Выражение in >> resetiosflags(mask) должно иметь тип basic_­istream<charT, traits>& и значение in.

unspecified setiosflags(ios_base::fmtflags mask);

Returns: Объект неопределенного типа, такой, что если out это объект типа, basic_­ostream<charT, traits> тогда выражение out << setiosflags(mask) ведет себя так, как если бы оно было вызвано f(out, mask), или если in это объект типа, basic_­istream<charT, traits> тогда выражение in >> setiosflags(mask) ведет себя так, как если бы оно было вызвано f(in, mask), где функция f определяется как:

void f(ios_base& str, ios_base::fmtflags mask) {
  // set specified flags
  str.setf(mask);
}

Выражение out << setiosflags(mask) должно иметь тип basic_­ostream<charT, traits>& и значение out. Выражение in >> setiosflags(mask) должно иметь тип basic_­istream<charT,
traits>&
и значение in.

unspecified setbase(int base);

Returns: Объект неопределенного типа, такой, что если out это объект типа, basic_­ostream<charT, traits> тогда выражение out << setbase(base) ведет себя так, как если бы оно было вызвано f(out, base), или если in это объект типа, basic_­istream<charT, traits> тогда выражение in >> setbase(base) ведет себя так, как если бы оно было вызвано f(in, base), где функция f определяется как:

void f(ios_base& str, int base) {
  // set basefield
  str.setf(base ==  8 ? ios_base::oct :
      base == 10 ? ios_base::dec :
      base == 16 ? ios_base::hex :
      ios_base::fmtflags(0), ios_base::basefield);
}

Выражение out << setbase(base) должно иметь тип basic_­ostream<charT, traits>& и значение out. Выражение in >> setbase(base) должно иметь тип basic_­istream<charT, traits>& и значение in.

unspecified setfill(char_type c);

Returns: Объект неопределенного типа, такой, что if out является объектом типа basic_­ostream<charT, traits> и c имеет тип, charT тогда выражение out << setfill(c) ведет себя так, как если бы оно было вызвано f(out, c), где функция f определяется как:

template<class charT, class traits>
void f(basic_ios<charT, traits>& str, charT c) {
  // set fill character
  str.fill(c);
}

Выражение out << setfill(c) должно иметь тип basic_­ostream<charT, traits>& и значение out.

unspecified setprecision(int n);

Returns: Объект неопределенного типа, такой, что если out это объект типа, basic_­ostream<charT, traits> тогда выражение out << setprecision(n) ведет себя так, как если бы оно было вызвано f(out, n), или если in это объект типа, basic_­istream<charT, traits> тогда выражение in >> setprecision(n) ведет себя так, как если бы оно было вызвано f(in, n), где функция f определяется как:

void f(ios_base& str, int n) {
  // set precision
  str.precision(n);
}

Выражение out << setprecision(n) должно иметь тип basic_­ostream<charT, traits>& и значение out. Выражение in >> setprecision(n) должно иметь тип basic_­istream<charT, traits>& и значение in.

unspecified setw(int n);

Returns: Объект неопределенного типа, такой, что если out является экземпляром, basic_­ostream<charT, traits> тогда выражение out << setw(n) ведет себя так, как если бы оно было вызвано f(out, n), или если in это объект типа, basic_­istream<charT, traits> то выражение in >> setw(n) ведет себя так, как если бы оно было вызвано f(in, n), где функция f определяется как:

void f(ios_base& str, int n) {
  // set width
  str.width(n);
}

Выражение out << setw(n) должно иметь тип basic_­ostream<charT, traits>& и значение out. Выражение in >> setw(n) должно иметь тип basic_­istream<charT, traits>& и значение in.

Выражение cin >> resetiosflags(ios_­base​::​skipws) очищается ios_­base​::​skipws во флагах формата, хранящихся в basic_­istream<charT, traits> объекте cin (так же, как cin >> noskipws), а выражение cout << resetiosflags(ios_­base​::​showbase) очищается ios_­base​::​showbase во флагах формата, хранящихся в basic_­ostream<charT, traits> объекте cout (как cout << noshowbase).

30.7.7 Extended manipulators [ext.manip]

Заголовок <iomanip> определяет несколько функций, которые поддерживают экстракторы и вставщики, которые позволяют анализировать и форматировать последовательности и значения за деньги и время.

template <class moneyT> unspecified get_money(moneyT& mon, bool intl = false);

Requires: Тип moneyT должен быть либо long double специализацией basic_­string шаблона (пункт [strings]), либо его специализацией .

Effects: Выражение, in >> get_­money(mon, intl) описанное ниже, ведет себя как formatted input function.

Returns: Объект неопределенного типа, такой что if in является объектом типа, basic_­istream<charT, traits> тогда выражение in >> get_­money(mon, intl) ведет себя так, как если бы оно было вызвано f(in, mon, intl), где функция f определяется как:

template <class charT, class traits, class moneyT>
void f(basic_ios<charT, traits>& str, moneyT& mon, bool intl) {
  using Iter     = istreambuf_iterator<charT, traits>;
  using MoneyGet = money_get<charT, Iter>;

  ios_base::iostate err = ios_base::goodbit;
  const MoneyGet& mg = use_facet<MoneyGet>(str.getloc());

  mg.get(Iter(str.rdbuf()), Iter(), intl, str, err, mon);

  if (ios_base::goodbit != err)
    str.setstate(err);
}

Выражение in >> get_­money(mon, intl) должно иметь тип basic_­istream<charT, traits>& и значение in.

template <class moneyT> unspecified put_money(const moneyT& mon, bool intl = false);

Requires: Тип moneyT должен быть либо long double специализацией basic_­string шаблона (пункт [strings]), либо его специализацией .

Returns: Объект неопределенного типа, такой что if out является объектом типа, basic_­ostream<charT, traits> тогда выражение out << put_­money(mon, intl) ведет себя как formatted output function вызывающий объект f(out, mon, intl), где функция f определяется как:

template <class charT, class traits, class moneyT>
void f(basic_ios<charT, traits>& str, const moneyT& mon, bool intl) {
  using Iter     = ostreambuf_iterator<charT, traits>;
  using MoneyPut = money_put<charT, Iter>;

  const MoneyPut& mp = use_facet<MoneyPut>(str.getloc());
  const Iter end = mp.put(Iter(str.rdbuf()), intl, str, str.fill(), mon);

  if (end.failed())
    str.setstate(ios::badbit);
}

Выражение out << put_­money(mon, intl) должно иметь тип basic_­ostream<charT, traits>& и значение out.

template <class charT> unspecified get_time(struct tm* tmb, const charT* fmt);

Requires: Аргумент tmb должен быть действительным указателем на объект типа struct tm. Аргумент fmt должен быть действительным указателем на массив объектов типа charT с char_­traits<charT>​::​length(fmt) элементами.

Returns: Объект неопределенного типа, такой что if in является объектом типа, basic_­istream<charT, traits> тогда выражение in >> get_­time(tmb, fmt) ведет себя так, как если бы оно было вызвано f(in, tmb, fmt), где функция f определяется как:

template <class charT, class traits>
void f(basic_ios<charT, traits>& str, struct tm* tmb, const charT* fmt) {
  using Iter    = istreambuf_iterator<charT, traits>;
  using TimeGet = time_get<charT, Iter>;

  ios_base::iostate err = ios_base::goodbit;
  const TimeGet& tg = use_facet<TimeGet>(str.getloc());

  tg.get(Iter(str.rdbuf()), Iter(), str, err, tmb,
    fmt, fmt + traits::length(fmt));

  if (err != ios_base::goodbit)
    str.setstate(err);
}

Выражение in >> get_­time(tmb, fmt) должно иметь тип basic_­istream<charT, traits>& и значение in.

template <class charT> unspecified put_time(const struct tm* tmb, const charT* fmt);

Requires: Аргумент tmb должен быть действительным указателем на объект типа struct tm, а аргумент fmt должен быть действительным указателем на массив объектов типа charT с char_­traits<charT>​::​length(​fmt) элементами.

Returns: Объект неопределенного типа, такой что if out является объектом типа, basic_­ostream<charT, traits> тогда выражение out << put_­time(tmb, fmt) ведет себя так, как если бы оно было вызвано f(out, tmb, fmt), где функция f определяется как:

template <class charT, class traits>
void f(basic_ios<charT, traits>& str, const struct tm* tmb, const charT* fmt) {
  using Iter    = ostreambuf_iterator<charT, traits>;
  using TimePut = time_put<charT, Iter>;

  const TimePut& tp = use_facet<TimePut>(str.getloc());
  const Iter end = tp.put(Iter(str.rdbuf()), str, str.fill(), tmb,
    fmt, fmt + traits::length(fmt));

  if (end.failed())
    str.setstate(ios_base::badbit);
}

Выражение out << put_­time(tmb, fmt) должно иметь тип basic_­ostream<charT, traits>& и значение out.

30.7.8 Quoted manipulators [quoted.manip]

[ Note: Манипуляторы с кавычками обеспечивают вставку и извлечение строк в кавычках (например, в форматах XML и CSV). Цитированные манипуляторы полезны для обеспечения того, чтобы содержимое строки со встроенными пробелами оставалось неизменным, если оно вставлено и затем извлечено с помощью потокового ввода-вывода. ] end note

template <class charT> unspecified quoted(const charT* s, charT delim = charT('"'), charT escape = charT('\\')); template <class charT, class traits, class Allocator> unspecified quoted(const basic_string<charT, traits, Allocator>& s, charT delim = charT('"'), charT escape = charT('\\')); template <class charT, class traits> unspecified quoted(basic_string_view<charT, traits> s, charT delim = charT('"'), charT escape = charT('\\'));

Returns: Объект неопределенного типа, такой что if out является экземпляром basic_­ostream с типом члена, char_­type таким же, как charT и с типом члена traits_­type, который во второй и третьей формах совпадает с traits, тогда выражение out << quoted(s, delim, escape) ведет себя как a formatted output function of out. Это формирует последовательность символов seq, изначально состоящую из следующих элементов:

  • delim.

  • Каждый персонаж в s. Если выводимый символ равен escape или delim, как определено traits_­type​::​eq, первый вывод escape.

  • delim.

Позвольте x быть количество элементов первоначально в seq. Затем определяется заполнение, seq как описано в [ostream.formatted.reqmts], seq вставляется, как если бы при вызове out.rdbuf()->sputn(seq, n), где n больше из out.width() и x, и out.width(0) вызывается. Выражение out << quoted(s, delim, escape) должно иметь тип basic_­ostream<charT, traits>& и значение out.

template <class charT, class traits, class Allocator> unspecified quoted(basic_string<charT, traits, Allocator>& s, charT delim = charT('"'), charT escape = charT('\\'));

Returns: Объект неопределенного типа, такой что:

  • Если in это экземпляр basic_­istream с типами членов char_­type и traits_­type то же самое, что charT и traits, соответственно, тогда выражение in >> quoted(s, delim, escape) ведет себя так, как если бы оно извлекало следующие символы из in using operator>>(basic_­istream<charT, traits>&, charT&) ( [istream.extractors]), которое может throw ios_­base​::​failure ( [ios::failure]):

    • Если первый извлеченный символ равен delim, как определено traits_­type​::​eq, то:

      • Снимите skipws флаг.

      • s.clear()

      • Пока не будет delim достигнут неэкранированный символ или !in, извлеките символы из in и добавьте их s, за исключением того, что если escape достигнут, игнорируйте его и добавляйте следующий символ к s.

      • Отбросьте последний delim символ.

      • Восстановите skipws исходное значение флага.

    • В противном случае in >> s.

  • Если out - это экземпляр basic_­ostream с типами членов char_­type и traits_­type то же самое, что charT и и traits, соответственно, тогда выражение out << quoted(s, delim, escape) ведет себя так, как указано для const basic_­string<charT, traits, Allocator>& перегрузки quoted функции.

Выражение in >> quoted(s, delim, escape) должно иметь тип basic_­istream<charT, traits>& и значение in. Выражение out << quoted(s, delim, escape) должно иметь тип basic_­ostream​<charT, traits>& и значение out.

30.8 String-based streams [string.streams]

30.8.1 Header <sstream> synopsis [sstream.syn]

namespace std {
  template <class charT, class traits = char_traits<charT>,
            class Allocator = allocator<charT>>
    class basic_stringbuf;

  using stringbuf  = basic_stringbuf<char>;
  using wstringbuf = basic_stringbuf<wchar_t>;

  template <class charT, class traits = char_traits<charT>,
            class Allocator = allocator<charT>>
    class basic_istringstream;

  using istringstream  = basic_istringstream<char>;
  using wistringstream = basic_istringstream<wchar_t>;

  template <class charT, class traits = char_traits<charT>,
            class Allocator = allocator<charT>>
    class basic_ostringstream;
  using ostringstream  = basic_ostringstream<char>;
  using wostringstream = basic_ostringstream<wchar_t>;

  template <class charT, class traits = char_traits<charT>,
            class Allocator = allocator<charT>>
    class basic_stringstream;
  using stringstream  = basic_stringstream<char>;
  using wstringstream = basic_stringstream<wchar_t>;
}

Заголовок <sstream> определяет четыре шаблона классов и восемь типов, которые связывают буферы потока с объектами класса basic_­string, как описано в [string.classes].

30.8.2 Class template basic_­stringbuf [stringbuf]

namespace std {
  template <class charT, class traits = char_traits<charT>,
            class Allocator = allocator<charT>>
  class basic_stringbuf : public basic_streambuf<charT, traits> {
  public:
    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;
    using allocator_type = Allocator;

    // [stringbuf.cons], constructors
    explicit basic_stringbuf(
      ios_base::openmode which = ios_base::in | ios_base::out);
    explicit basic_stringbuf(
      const basic_string<charT, traits, Allocator>& str,
      ios_base::openmode which = ios_base::in | ios_base::out);
    basic_stringbuf(const basic_stringbuf& rhs) = delete;
    basic_stringbuf(basic_stringbuf&& rhs);

    // [stringbuf.assign], assign and swap
    basic_stringbuf& operator=(const basic_stringbuf& rhs) = delete;
    basic_stringbuf& operator=(basic_stringbuf&& rhs);
    void swap(basic_stringbuf& rhs);

    // [stringbuf.members], get and set
    basic_string<charT, traits, Allocator> str() const;
    void str(const basic_string<charT, traits, Allocator>& s);

  protected:
    // [stringbuf.virtuals], overridden virtual functions
    int_type underflow() override;
    int_type pbackfail(int_type c = traits::eof()) override;
    int_type overflow (int_type c = traits::eof()) override;
    basic_streambuf<charT, traits>* setbuf(charT*, streamsize) 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;

  private:
    ios_base::openmode mode;  // exposition only
  };

  template <class charT, class traits, class Allocator>
    void swap(basic_stringbuf<charT, traits, Allocator>& x,
              basic_stringbuf<charT, traits, Allocator>& y);
}

Класс basic_­stringbuf является производным от, basic_­streambuf чтобы связать, возможно, входную последовательность и, возможно, выходную последовательность с произвольной последовательностью characters. Последовательность может быть инициализирована или сделана доступной как объект класса basic_­string.

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

  • ios_­base​::​openmode mode, in установлен, если входная последовательность может быть прочитана, и out установлена, если выходная последовательность может быть записана.

30.8.2.1 basic_­stringbuf constructors [stringbuf.cons]

explicit basic_stringbuf( ios_base::openmode which = ios_base::in | ios_base::out);

Effects: Создает объект класса basic_­stringbuf, инициализируя базовый класс с помощью basic_­streambuf() ( [streambuf.cons]) и инициализируя mode с помощью which.

Postconditions: str() == "".

explicit basic_stringbuf( const basic_string<charT, traits, Allocator>& s, ios_base::openmode which = ios_base::in | ios_base::out);

Effects: Создает объект класса basic_­stringbuf, инициализируя базовый класс с помощью basic_­streambuf() ( [streambuf.cons]) и инициализируя mode с помощью which. Потом звонит str(s).

basic_stringbuf(basic_stringbuf&& rhs);

Effects: Переместите конструкции из rvalue rhs. Это определяется реализация ли указатели последовательности в *this ( eback(), gptr(), egptr(), pbase(), pptr(), epptr()) получить значение , которые rhs имели. Независимо от того, работают они или нет, *this и rhs ссылаются на отдельные буферы (если они вообще есть) после построения. Также копируются режим openmode, locale и любое другое состояние rhs .

Postconditions: Позвольте rhs_­p ссылаться на состояние rhs непосредственно перед этой конструкцией и позвольте rhs_­a ссылаться на состояние rhs сразу после этой конструкции.

  • str() == rhs_­p.str()

  • gptr() - eback() == rhs_­p.gptr() - rhs_­p.eback()

  • egptr() - eback() == rhs_­p.egptr() - rhs_­p.eback()

  • pptr() - pbase() == rhs_­p.pptr() - rhs_­p.pbase()

  • epptr() - pbase() == rhs_­p.epptr() - rhs_­p.pbase()

  • if (eback()) eback() != rhs_­a.eback()

  • if (gptr()) gptr() != rhs_­a.gptr()

  • if (egptr()) egptr() != rhs_­a.egptr()

  • if (pbase()) pbase() != rhs_­a.pbase()

  • if (pptr()) pptr() != rhs_­a.pptr()

  • if (epptr()) epptr() != rhs_­a.epptr()

30.8.2.2 Assign and swap [stringbuf.assign]

basic_stringbuf& operator=(basic_stringbuf&& rhs);

Effects: После того, как присвоение хода *this приобрело наблюдаемое состояние, оно было бы, если бы оно было построено из rhs (см. [stringbuf.cons]).

Returns: *this.

void swap(basic_stringbuf& rhs);

Effects: Меняет состояние *this и rhs.

template <class charT, class traits, class Allocator> void swap(basic_stringbuf<charT, traits, Allocator>& x, basic_stringbuf<charT, traits, Allocator>& y);

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

30.8.2.3 Member functions [stringbuf.members]

basic_string<charT, traits, Allocator> str() const;

Returns: basic_­string Объект, содержание которого равна basic_­stringbuf базовой последовательности символов. Если basic_­stringbuf был создан только в режиме ввода, результат будет basic_­string содержать последовательность символов в диапазоне [eback(), egptr()). Если basic_­stringbuf был создан с which & ios_­base​::​out ненулевым значением, то результат basic_­string содержит последовательность символов в диапазоне [pbase(), high_­mark), где high_­mark представляет позицию после самого высокого инициализированного символа в буфере. Символы можно инициализировать путем записи в поток, создания с basic_­stringbuf помощью a basic_­stringили вызова str(basic_­string) функции-члена. В случае вызова str(basic_­string) функции-члена все символы, инициализированные до вызова, теперь считаются неинициализированными (за исключением тех символов, которые повторно инициализированы новым basic_­string). В противном случае basic_­stringbuf объект не был создан ни в режиме ввода, ни в режиме вывода, и basic_­string возвращается нулевая длина .

void str(const basic_string<charT, traits, Allocator>& s);

Effects: Копирует содержимое s в basic_­stringbuf базовую последовательность символов и инициализирует входные и выходные последовательности в соответствии с mode.

Postconditions: Если mode & ios_­base​::​out не ноль, pbase() указывает на первый базовый символ и epptr() >= pbase() + s.size() удерживается; кроме того, если не mode & ios_­base​::​ate равно нулю, то pptr() == pbase() + s.size() имеет место, иначе pptr() == pbase() - нет true. Если не mode & ios_­base​::​in равно нулю, eback() указывает на первый базовый символ, и оба gptr() == eback() и egptr() == eback() + s.size() удерживаются.

30.8.2.4 Overridden virtual functions [stringbuf.virtuals]

int_type underflow() override;

Returns: Если входная последовательность имеет доступную позицию чтения, возвращается traits​::​to_­int_­type(*gptr()). В противном случае возвращается traits​::​eof(). Любой инициализированный символ в нижележащем буфере считается частью входной последовательности.

int_type pbackfail(int_type c = traits::eof()) override;

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

  • Если traits​::​eq_­int_­type(c, traits​::​eof()) возвращается , false и если входная последовательность имеет место Putback доступный, и если traits​::​eq(to_­char_­type(c), gptr()[-1]) возвращается true, правопреемники gptr() - 1 в gptr().

    Возвращает: c.

  • Если traits​::​eq_­int_­type(c, traits​::​eof()) возвращается , false и если входная последовательность имеет место Putback доступный, и если не mode & ios_­base​::​out равен нулю, правопреемников c к *--gptr().

    Возвращает: c.

  • Если traits​::​eq_­int_­type(c, traits​::​eof()) возвращается , true и если входная последовательность имеет место Putback доступный, правопреемники gptr() - 1 к gptr().

    Возвращает: traits​::​not_­eof(c).

Returns: traits​::​eof() для обозначения отказа.

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

int_type overflow(int_type c = traits::eof()) override;

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

  • Если traits​::​eq_­int_­type(c, traits​::​eof()) возвращается, false и если либо выходная последовательность имеет доступную позицию записи, либо функция делает доступной позицию записи (как описано ниже), функция вызывает sputc(c).

    Сигнализирует об успехе, возвращаясь c.

  • Если traits​::​eq_­int_­type(c, traits​::​eof()) возвращается true, нет символа для добавления.

    Сигнализирует об успехе, возвращая значение, отличное от traits​::​eof().

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

Returns: traits​::​eof() для обозначения отказа.

Функция может сделать позицию записи доступной, только если (mode & ios_­base​::​out) != 0. Чтобы сделать позицию записи доступной, функция перераспределяет (или первоначально выделяет) объект массива с достаточным количеством элементов, чтобы удерживать текущий объект массива (если есть), плюс по крайней мере одну дополнительную позицию записи. Если (mode & ios_­base​::​in) != 0, функция изменяет указатель конца чтения так, egptr() чтобы он указывал сразу за новой позицией записи.

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

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

Стол 115 - seekoff позиционирование
УсловияРезультат
(which & ios_­base​::​in) == ios_­base​::​in позиционирует входную последовательность
(which & ios_­base​::​out) == ios_­base​::​out позиционирует выходную последовательность
(which & (ios_­base​::​in |
ios_­base​::​out)) ==
(ios_­base​::​in) |
ios_­base​::​out))
и way == либо,
ios_­base​::​beg либо
ios_­base​::​end
позиционирует как входную, так и выходную последовательности
Иначе операция позиционирования не выполняется.

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

Таблица 116 - newoff значения
Состояниеnewoff Ценить
way == ios_­base​::​beg 0
way == ios_­base​::​cur следующий указатель минус указатель начала ( xnext - xbeg).
way == ios_­base​::​end указатель верхней отметки минус указатель начала ( high_­mark - xbeg).

Если (newoff + off) < 0или если newoff + off относится к неинициализированному символу ( [stringbuf.members]), операция позиционирования завершается ошибкой. В противном случае функция присваивает 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: Эквивалентно seekoff(off_­type(sp), ios_­base​::​beg, which).

Returns: sp для обозначения успеха или pos_­type(off_­type(-1)) неудачи.

basic_streambuf<charT, traits>* setbuf(charT* s, streamsize n);

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

Returns: this.

30.8.3 Class template basic_­istringstream [istringstream]

namespace std {
  template <class charT, class traits = char_traits<charT>,
            class Allocator = allocator<charT>>
  class basic_istringstream : public basic_istream<charT, traits> {
  public:
    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;
    using allocator_type = Allocator;

    // [istringstream.cons], constructors
    explicit basic_istringstream(
      ios_base::openmode which = ios_base::in);
    explicit basic_istringstream(
      const basic_string<charT, traits, Allocator>& str,
      ios_base::openmode which = ios_base::in);
    basic_istringstream(const basic_istringstream& rhs) = delete;
    basic_istringstream(basic_istringstream&& rhs);

    // [istringstream.assign], assign and swap
    basic_istringstream& operator=(const basic_istringstream& rhs) = delete;
    basic_istringstream& operator=(basic_istringstream&& rhs);
    void swap(basic_istringstream& rhs);

    // [istringstream.members], members
    basic_stringbuf<charT, traits, Allocator>* rdbuf() const;

    basic_string<charT, traits, Allocator> str() const;
    void str(const basic_string<charT, traits, Allocator>& s);
  private:
    basic_stringbuf<charT, traits, Allocator> sb; // exposition only
  };

  template <class charT, class traits, class Allocator>
    void swap(basic_istringstream<charT, traits, Allocator>& x,
              basic_istringstream<charT, traits, Allocator>& y);
}

Класс basic_­istringstream<charT, traits, Allocator> поддерживает чтение объектов класса basic_­string<​charT, traits, Allocator>. Он использует basic_­stringbuf<charT, traits, Allocator> объект для управления связанным хранилищем. Для демонстрации поддерживаемые данные представлены здесь как:

  • sb, stringbuf объект.

30.8.3.1 basic_­istringstream constructors [istringstream.cons]

explicit basic_istringstream(ios_base::openmode which = ios_base::in);

Effects: Создает объект класса basic_­istringstream<charT, traits>, инициализируя базовый класс с помощью basic_­istream(&sb) и инициализируя sb с помощью basic_­stringbuf<charT, traits, Allocator>(which | ios_­base​::​in)) ( [stringbuf.cons]).

explicit basic_istringstream( const basic_string<charT, traits, Allocator>& str, ios_base::openmode which = ios_base::in);

Effects: Создает объект класса basic_­istringstream<charT, traits>, инициализируя базовый класс с помощью basic_­istream(&sb) и инициализируя sb с помощью basic_­stringbuf<charT, traits, Allocator>(str, which | ios_­base​::​in)) ( [stringbuf.cons]).

basic_istringstream(basic_istringstream&& rhs);

Effects: Переместите конструкции из rvalue rhs. Это достигается перемещением конструирования базового класса и содержащегося в нем basic_­stringbuf. Далее basic_­istream<charT, traits>​::​set_­rdbuf(&sb) вызывается для установки содержащегося basic_­stringbuf.

30.8.3.2 Assign and swap [istringstream.assign]

basic_istringstream& operator=(basic_istringstream&& rhs);

Effects: Move назначает базу и членов *this из базы и членов-корреспондентов rhs.

Returns: *this.

void swap(basic_istringstream& rhs);

Effects: Меняет состояние *this и rhs по вызову basic_­istream<charT, traits>​::​swap(rhs) и sb.swap(rhs.sb).

template <class charT, class traits, class Allocator> void swap(basic_istringstream<charT, traits, Allocator>& x, basic_istringstream<charT, traits, Allocator>& y);

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

30.8.3.3 Member functions [istringstream.members]

basic_stringbuf<charT, traits, Allocator>* rdbuf() const;

Returns: const_­cast<basic_­stringbuf<charT, traits, Allocator>*>(&sb).

basic_string<charT, traits, Allocator> str() const;

Returns: rdbuf()->str().

void str(const basic_string<charT, traits, Allocator>& s);

Effects: Звонки rdbuf()->str(s).

30.8.4 Class template basic_­ostringstream [ostringstream]

namespace std {
  template <class charT, class traits = char_traits<charT>,
            class Allocator = allocator<charT>>
  class basic_ostringstream : public basic_ostream<charT, traits> {
  public:
    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;
    using allocator_type = Allocator;

    // [ostringstream.cons], constructors
    explicit basic_ostringstream(
      ios_base::openmode which = ios_base::out);
    explicit basic_ostringstream(
      const basic_string<charT, traits, Allocator>& str,
      ios_base::openmode which = ios_base::out);
    basic_ostringstream(const basic_ostringstream& rhs) = delete;
    basic_ostringstream(basic_ostringstream&& rhs);

    // [ostringstream.assign], assign and swap
    basic_ostringstream& operator=(const basic_ostringstream& rhs) = delete;
    basic_ostringstream& operator=(basic_ostringstream&& rhs);
    void swap(basic_ostringstream& rhs);

    // [ostringstream.members], members
    basic_stringbuf<charT, traits, Allocator>* rdbuf() const;

    basic_string<charT, traits, Allocator> str() const;
    void str(const basic_string<charT, traits, Allocator>& s);
   private:
    basic_stringbuf<charT, traits, Allocator> sb; // exposition only
  };

  template <class charT, class traits, class Allocator>
    void swap(basic_ostringstream<charT, traits, Allocator>& x,
              basic_ostringstream<charT, traits, Allocator>& y);
}

Класс basic_­ostringstream<charT, traits, Allocator> поддерживает запись объектов класса basic_­string<​charT, traits, Allocator>. Он использует basic_­stringbuf объект для управления связанным хранилищем. Для демонстрации поддерживаемые данные представлены здесь как:

  • sb, stringbuf объект.

30.8.4.1 basic_­ostringstream constructors [ostringstream.cons]

explicit basic_ostringstream( ios_base::openmode which = ios_base::out);

Effects: Создает объект класса basic_­ostringstream, инициализируя базовый класс с помощью basic_­ostream(​&sb) и инициализируя sb с помощью basic_­stringbuf<charT, traits, Allocator>(which | ​ios_­base​::​out)) ( [stringbuf.cons]).

explicit basic_ostringstream( const basic_string<charT, traits, Allocator>& str, ios_base::openmode which = ios_base::out);

Effects: Создает объект класса basic_­ostringstream<charT, traits>, инициализируя базовый класс с помощью basic_­ostream(&sb) и инициализируя sb с помощью basic_­stringbuf<charT, traits, Allocator>(str, which | ios_­base​::​out)) ( [stringbuf.cons]).

basic_ostringstream(basic_ostringstream&& rhs);

Effects: Переместите конструкции из rvalue rhs. Это достигается перемещением конструирования базового класса и содержащегося в нем basic_­stringbuf. Далее basic_­ostream<charT, traits>​::​set_­rdbuf(&sb) вызывается для установки содержащегося basic_­stringbuf.

30.8.4.2 Assign and swap [ostringstream.assign]

basic_ostringstream& operator=(basic_ostringstream&& rhs);

Effects: Move назначает базу и членов *this из базы и членов-корреспондентов rhs.

Returns: *this.

void swap(basic_ostringstream& rhs);

Effects: Меняет состояние *this и rhs по вызову basic_­ostream<charT, traits>​::​swap(rhs) и sb.swap(rhs.sb).

template <class charT, class traits, class Allocator> void swap(basic_ostringstream<charT, traits, Allocator>& x, basic_ostringstream<charT, traits, Allocator>& y);

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

30.8.4.3 Member functions [ostringstream.members]

basic_stringbuf<charT, traits, Allocator>* rdbuf() const;

Returns: const_­cast<basic_­stringbuf<charT, traits, Allocator>*>(&sb).

basic_string<charT, traits, Allocator> str() const;

Returns: rdbuf()->str().

void str(const basic_string<charT, traits, Allocator>& s);

Effects: Звонки rdbuf()->str(s).

30.8.5 Class template basic_­stringstream [stringstream]

namespace std {
  template <class charT, class traits = char_traits<charT>,
            class Allocator = allocator<charT>>
  class basic_stringstream : public basic_iostream<charT, traits> {
  public:
    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;
    using allocator_type = Allocator;

    // [stringstream.cons], constructors
    explicit basic_stringstream(
      ios_base::openmode which = ios_base::out | ios_base::in);
    explicit basic_stringstream(
      const basic_string<charT, traits, Allocator>& str,
      ios_base::openmode which = ios_base::out | ios_base::in);
    basic_stringstream(const basic_stringstream& rhs) = delete;
    basic_stringstream(basic_stringstream&& rhs);

    // [stringstream.assign], assign and swap
    basic_stringstream& operator=(const basic_stringstream& rhs) = delete;
    basic_stringstream& operator=(basic_stringstream&& rhs);
    void swap(basic_stringstream& rhs);

    // [stringstream.members], members
    basic_stringbuf<charT, traits, Allocator>* rdbuf() const;
    basic_string<charT, traits, Allocator> str() const;
    void str(const basic_string<charT, traits, Allocator>& str);

  private:
    basic_stringbuf<charT, traits> sb;  // exposition only
  };

  template <class charT, class traits, class Allocator>
    void swap(basic_stringstream<charT, traits, Allocator>& x,
              basic_stringstream<charT, traits, Allocator>& y);
}

Шаблон класса basic_­stringstream<charT, traits> поддерживает чтение и запись из объектов класса basic_­string<charT, traits, Allocator>. Он использует basic_­stringbuf<charT, traits, Allocator> объект для управления связанной последовательностью. Для наглядности сохраненные данные представлены здесь как

  • sb, stringbuf объект.

30.8.5.1 basic_­stringstream constructors [stringstream.cons]

explicit basic_stringstream( ios_base::openmode which = ios_base::out | ios_base::in);

Effects: Создает объект класса basic_­stringstream<charT, traits>, инициализируя базовый класс basic_­iostream(&sb) и инициализируя sb с помощью basic_­stringbuf<charT, traits, Allocator>(which).

explicit basic_stringstream( const basic_string<charT, traits, Allocator>& str, ios_base::openmode which = ios_base::out | ios_base::in);

Effects: Создает объект класса basic_­stringstream<charT, traits>, инициализируя базовый класс basic_­iostream(&sb) и инициализируя sb с помощью basic_­stringbuf<charT, traits, Allocator>(str, which).

basic_stringstream(basic_stringstream&& rhs);

Effects: Переместите конструкции из rvalue rhs. Это достигается перемещением конструирования базового класса и содержащегося в нем basic_­stringbuf. Далее basic_­istream<charT, traits>​::​set_­rdbuf(&sb) вызывается для установки содержащегося basic_­stringbuf.

30.8.5.2 Assign and swap [stringstream.assign]

basic_stringstream& operator=(basic_stringstream&& rhs);

Effects: Move назначает базу и членов *this из базы и членов-корреспондентов rhs.

Returns: *this.

void swap(basic_stringstream& rhs);

Effects: Меняет состояние *this и rhs по вызову basic_­iostream<charT,traits>​::​swap(rhs) и sb.swap(rhs.sb).

template <class charT, class traits, class Allocator> void swap(basic_stringstream<charT, traits, Allocator>& x, basic_stringstream<charT, traits, Allocator>& y);

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

30.8.5.3 Member functions [stringstream.members]

basic_stringbuf<charT, traits, Allocator>* rdbuf() const;

Returns: const_­cast<basic_­stringbuf<charT, traits, Allocator>*>(&sb)

basic_string<charT, traits, Allocator> str() const;

Returns: rdbuf()->str().

void str(const basic_string<charT, traits, Allocator>& str);

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

30.9 File-based streams [file.streams]

30.9.1 Header <fstream> synopsis [fstream.syn]

namespace std {
  template <class charT, class traits = char_traits<charT>>
    class basic_filebuf;
  using filebuf  = basic_filebuf<char>;
  using wfilebuf = basic_filebuf<wchar_t>;

  template <class charT, class traits = char_traits<charT>>
    class basic_ifstream;
  using ifstream  = basic_ifstream<char>;
  using wifstream = basic_ifstream<wchar_t>;

  template <class charT, class traits = char_traits<charT>>
    class basic_ofstream;
  using ofstream  = basic_ofstream<char>;
  using wofstream = basic_ofstream<wchar_t>;

  template <class charT, class traits = char_traits<charT>>
    class basic_fstream;
  using fstream  = basic_fstream<char>;
  using wfstream = basic_fstream<wchar_t>;
}

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

[ Note: Шаблон класса basic_­filebuf рассматривает файл как источник или приемник байтов. В среде, в которой используется большой набор символов, файл обычно содержит многобайтовые последовательности символов, и basic_­filebuf объект преобразует эти многобайтовые последовательности в последовательности широких символов. ]end note

В этом подпункте функции-члены, принимающие аргументы, предоставляются const filesystem​::​path​::​value_­type* только в системах, где filesystem​::​path​::​value_­type ( [fs.class.path]) нет char. [ Note: Эти функции включают path поддержку классов для систем с широким типом символов собственного пути, например wchar_­t. ]end note

30.9.2 Class template basic_­filebuf [filebuf]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class basic_filebuf : public basic_streambuf<charT, traits> {
  public:
    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;

    // [filebuf.cons], constructors/destructor
    basic_filebuf();
    basic_filebuf(const basic_filebuf& rhs) = delete;
    basic_filebuf(basic_filebuf&& rhs);
    virtual ~basic_filebuf();

    // [filebuf.assign], assign and swap
    basic_filebuf& operator=(const basic_filebuf& rhs) = delete;
    basic_filebuf& operator=(basic_filebuf&& rhs);
    void swap(basic_filebuf& rhs);

    // [filebuf.members], members
    bool is_open() const;
    basic_filebuf* open(const char* s, ios_base::openmode mode);
    basic_filebuf* open(const filesystem::path::value_type* s,
                        ios_base::openmode mode);  // wide systems only; see [fstream.syn]
    basic_filebuf* open(const string& s,
                        ios_base::openmode mode);
    basic_filebuf* open(const filesystem::path& s,
                        ios_base::openmode mode);
    basic_filebuf* close();

  protected:
    // [filebuf.virtuals], overridden virtual functions
    streamsize showmanyc() override;
    int_type underflow() override;
    int_type uflow() override;
    int_type pbackfail(int_type c = traits::eof()) override;
    int_type overflow (int_type c = traits::eof()) override;

    basic_streambuf<charT, traits>* setbuf(char_type* s,
                                           streamsize n) 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;
    int      sync() override;
    void     imbue(const locale& loc) override;
  };

  template <class charT, class traits>
    void swap(basic_filebuf<charT, traits>& x,
              basic_filebuf<charT, traits>& y);
}

Класс basic_­filebuf<charT, traits> связывает как входную, так и выходную последовательность с файлом.

Ограничения на чтение и запись последовательности , управляемый объект класса basic_­filebuf<charT, traits> такие же , как для чтения и записи с помощью стандартной библиотеки C FILEс.

Особенно:

  • Если файл не открыт для чтения, входная последовательность не может быть прочитана.

  • Если файл не открыт для записи, выходная последовательность не может быть записана.

  • Позиция в совместном файле сохраняется как для входной, так и для выходной последовательности.

Экземпляр basic_­filebuf ведет себя , как описано в [filebuf] предусмотренных traits​::​pos_­type IS fpos<traits​::​​state_­type>. В противном случае поведение не определено.

Для поддержки файлового ввода-вывода и преобразования многобайтовых / широких символов преобразования выполняются с использованием элементов фасета, упомянутых a_­codecvt в следующих разделах, полученных, как если бы

const codecvt<charT, char, typename traits::state_type>& a_codecvt =
  use_facet<codecvt<charT, char, typename traits::state_type>>(getloc());

30.9.2.1 basic_­filebuf constructors [filebuf.cons]

basic_filebuf();

Effects: Создает объект класса basic_­filebuf<charT, traits>, инициализируя базовый класс с помощью basic_­streambuf<charT, traits>() ( [streambuf.cons]).

Postconditions: is_­open() == false.

basic_filebuf(basic_filebuf&& rhs);

Effects: Переместите конструкции из rvalue rhs. Это определяется реализация ли указатели последовательности в *this ( eback(), gptr(), egptr(), pbase(), pptr(), epptr()) получить значение , которые rhs имели. Независимо от того, работают они или нет, *this и rhs ссылаются на отдельные буферы (если они вообще есть) после построения. Дополнительно *this ссылается на файл, который rhs был создан до построения, и не rhs ссылается на файл после построения. Также копируются режим openmode, locale и любое другое состояние rhs .

Postconditions: Позвольте rhs_­p ссылаться на состояние rhs непосредственно перед этой конструкцией и позвольте rhs_­a ссылаться на состояние rhs сразу после этой конструкции.

  • is_­open() == rhs_­p.is_­open()

  • rhs_­a.is_­open() == false

  • gptr() - eback() == rhs_­p.gptr() - rhs_­p.eback()

  • egptr() - eback() == rhs_­p.egptr() - rhs_­p.eback()

  • pptr() - pbase() == rhs_­p.pptr() - rhs_­p.pbase()

  • epptr() - pbase() == rhs_­p.epptr() - rhs_­p.pbase()

  • if (eback()) eback() != rhs_­a.eback()

  • if (gptr()) gptr() != rhs_­a.gptr()

  • if (egptr()) egptr() != rhs_­a.egptr()

  • if (pbase()) pbase() != rhs_­a.pbase()

  • if (pptr()) pptr() != rhs_­a.pptr()

  • if (epptr()) epptr() != rhs_­a.epptr()

virtual ~basic_filebuf();

Effects: Уничтожает объект класса basic_­filebuf<charT, traits>. Звонки close(). Если во время уничтожения объекта, включая вызов close(), возникает исключение, исключение перехватывается, но не генерируется повторно (см [res.on.exception.handling]. Раздел "Ресурсы" ).

30.9.2.2 Assign and swap [filebuf.assign]

basic_filebuf& operator=(basic_filebuf&& rhs);

Effects: close() Затем вызовы перемещают назначенных из rhs. После того, как присвоение хода *this приобрело наблюдаемое состояние, оно было бы, если бы оно было построено из rhs (см. [filebuf.cons]).

Returns: *this.

void swap(basic_filebuf& rhs);

Effects: Меняет состояние *this и rhs.

template <class charT, class traits> void swap(basic_filebuf<charT, traits>& x, basic_filebuf<charT, traits>& y);

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

30.9.2.3 Member functions [filebuf.members]

bool is_open() const;

Returns: true если предыдущий вызов open завершился успешно (вернул ненулевое значение) и не было промежуточного вызова для закрытия.

basic_filebuf* open(const char* s, ios_base::openmode mode); basic_filebuf* open(const filesystem::path::value_type* s, ios_base::openmode mode); // wide systems only; see [fstream.syn]

Effects: Если is_­open() != false, возвращает нулевой указатель. В противном случае инициализирует при filebuf необходимости. Затем он открывает файл, если это возможно, с именем ntbs s (как если бы при вызове fopen(s, modstr)). В НТБ определяется , как указано в табл . Если в таблице не указана комбинация флагов, то открытие не выполняется. modstr mode & ~ios_­base​::​ate 117 mode

Таблица 117 - Режимы открытия файла
ios_­base комбинация флагов stdio эквивалент
binary in out trunc app
+ "w"
+ + "a"
+ "a"
+ + "w"
+ "r"
+ + "r+"
+ + + "w+"
+ + + "a+"
+ + "a+"
+ + "wb"
+ + + "ab"
+ + "ab"
+ + + "wb"
+ + "rb"
+ + + "r+b"
+ + + + "w+b"
+ + + + "a+b"
+ + + "a+b"

Если операция открытия завершается успешно и (mode & ios_­base​::​ate) != 0, помещает файл в конец (как если бы при вызове fseek(file, 0, SEEK_­END)).327

Если операция изменения положения завершается неудачно, вызывает close() и возвращает нулевой указатель, указывающий на сбой.

Returns: this в случае успеха - нулевой указатель.

basic_filebuf* open(const string& s, ios_base::openmode mode); basic_filebuf* open(const filesystem::path& s, ios_base::openmode mode);

Returns: open(s.c_­str(), mode);

basic_filebuf* close();

Effects: Если is_­open() == false, возвращает нулевой указатель. Если область размещения существует, вызывает overflow(traits​::​​eof()) сброс символов. Если последняя функция виртуального члена призвала *this (между underflow, overflow, seekoffи seekpos) был overflow тогда вызовы a_­codecvt.unshift (возможно , несколько раз) , чтобы определить последовательность терминации, вставляет эти символы и вызовы overflow(traits​::​​eof()) снова. Наконец, независимо от того, завершается ли какой-либо из предыдущих вызовов сбоем или возникает исключение, функция закрывает файл (как если бы путем вызова fclose(file)). Если какой-либо из вызовов, выполненных функцией, в том числе fclose, завершается ошибкой, close завершается ошибкой, возвращая нулевой указатель. Если один из этих вызовов вызывает исключение, исключение перехватывается и генерируется повторно после закрытия файла.

Returns: this в случае успеха - нулевой указатель.

Postconditions: is_­open() == false.

Макрос SEEK_­END определен, а сигнатуры функций fopen(const char*, const char*) и объявлены в .fseek(FILE*, long, int) <cstdio>

30.9.2.4 Overridden virtual functions [filebuf.virtuals]

streamsize showmanyc() override;

Effects: Ведет себя так же, как basic_­streambuf​::​showmanyc() ( [streambuf.virtuals]).

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

int_type underflow() override;

Effects: Ведет себя в соответствии с описанием basic_­streambuf<charT, traits>​::​underflow()со специализацией, согласно которой последовательность символов считывается из входной последовательности, как если бы она считывала из связанного файла во внутренний буфер ( extern_­buf), а затем как если бы выполнялась:

char   extern_buf[XSIZE];
char*  extern_end;
charT  intern_buf[ISIZE];
charT* intern_end;
codecvt_base::result r =
  a_codecvt.in(state, extern_buf, extern_buf+XSIZE, extern_end,
               intern_buf, intern_buf+ISIZE, intern_end);

Это должно быть сделано таким образом, чтобы класс мог восстановить позицию ( fpos_­t), соответствующую каждому символу между intern_­buf и intern_­end. Если значение r указывает, что в нем не a_­codecvt.in() хватает места intern_­buf, повторите попытку с большим intern_­buf.

int_type uflow() override;

Effects: Ведет себя в соответствии с описанием basic_­streambuf<charT, traits>​::​uflow(), со специализацией, заключающейся в том , что последовательность символов считывается из ввода тем же методом, что и underflow.

int_type pbackfail(int_type c = traits::eof()) override;

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

  • Если traits​::​eq_­int_­type(c, traits​::​eof()) возвращается false и , если функция делает позицию Putback доступную и если traits​::​eq(to_­char_­type(c), gptr()[-1]) возвращается true, вычитает следующий указатель для входной последовательности, gptr().

    Возвращает: c.

  • Если traits​::​eq_­int_­type(c, traits​::​eof()) возвращается, false и если функция делает доступной позицию возврата и если функции разрешено назначать позицию возврата, уменьшает следующий указатель для входной последовательности и сохраняет c его.

    Возвращает: c.

  • Если traits​::​eq_­int_­type(c, traits​::​eof()) возвращается true, и если либо входная последовательность имеет место Putback доступны или функция делает положение Putback доступна, вычитает следующий указатель для входной последовательности, gptr().

    Возвращает: traits​::​not_­eof(c).

Returns: traits​::​eof() для обозначения отказа.

Remarks: Если is_­open() == false, функция всегда терпит неудачу.

Функция не возвращает символ непосредственно во входную последовательность.

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

int_type overflow(int_type c = traits::eof()) override;

Effects: Ведет себя в соответствии с описанием basic_­streambuf<charT, traits>​::​overflow(c), за исключением того, что поведение «потребляющих символов» выполняется путем предварительного преобразования, как если бы:

charT* b = pbase();
charT* p = pptr();
charT* end;
char   xbuf[XSIZE];
char*  xbuf_end;
codecvt_base::result r =
  a_codecvt.out(state, b, p, end, xbuf, xbuf+XSIZE, xbuf_end);

а потом

  • Если r == codecvt_­base​::​error тогда не получится.

  • Если r == codecvt_­base​::​noconv тогда вывести символы от b до (и не включая) p.

  • Если r == codecvt_­base​::​partial затем вывести в файл символы от xbuf до xbuf_­endи повторить, используя символы от end до p. Если вывести не удалось, завершитесь ошибкой (без повторения).

  • В противном случае вывести из xbuf в xbuf_­endи потерпеть неудачу, если вывести не удалось . На этом этапе, если b != p и b == end ( xbuf недостаточно большое), увеличьте XSIZE и повторите сначала.

Returns: traits​::​not_­eof(c) для обозначения успеха и traits​::​eof() для обозначения неудачи. Если is_­open() == false, функция всегда терпит неудачу.

basic_streambuf* setbuf(char_type* s, streamsize n) override;

Effects: Если setbuf(0, 0) вызывается в потоке до того, как в этом потоке произошел какой-либо ввод-вывод, поток становится небуферизованным. В противном случае результаты определяются реализацией. «Unbuffered» означает , что pbase() и pptr() всегда возвращают нуль и вывод в файл должен появиться как можно скорее.

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

Effects: Пусть width обозначают a_­codecvt.encoding(). Если is_­open() == false, или off != 0 && width <= 0, то операция позиционирования не выполняется. В противном случае, если way != basic_­ios​::​cur или off != 0, и если была выведена последняя операция, обновите выходную последовательность и запишите любую несмещенную последовательность. Далее ищем новую позицию: если width > 0звоните fseek(file, width * off, whence), в противном случае звоните fseek(file, 0, whence).

Remarks: «Последняя операция была выведена» означает, что либо последняя виртуальная операция была переполнена, либо буфер размещения не пуст. «Записать любую последовательность без сдвига» означает, что width если меньше нуля, то вызвать a_­codecvt.unshift(state, xbuf, xbuf+XSIZE, xbuf_­end) и вывести результирующую последовательность без сдвига. Функция определяет одно из трех значений аргумента whenceтипа int, как указано в таблице 118.

Таблица 118 - seekoff эффекты
way Ценитьstdio Эквивалент
basic_­ios​::​beg SEEK_­SET
basic_­ios​::​cur SEEK_­CUR
basic_­ios​::​end SEEK_­END

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

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

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

  1. 1.если (om & ios_­base​::​out) != 0, то обновить выходную последовательность и записать любую несмещенную последовательность;

  2. 2.установить позицию файла, sp как если бы при вызове fsetpos;

  3. 3.если (om & ios_­base​::​in) != 0, то обновить входную последовательность;

где om открытый режим передан последнему вызову open(). При is_­open() возврате операция завершается ошибкой false.

Если sp это недопустимая позиция потока или функция не позиционирует ни одну последовательность, операция позиционирования завершается ошибкой. Если sp не был получен предыдущим успешным вызовом одной из функций позиционирования ( seekoff или seekpos) в том же файле, эффекты не определены.

Returns: sp об успехе. В противном случае возвращается pos_­type(off_­type(-1)).

int sync() override;

Effects: Если область размещения существует, вызывает filebuf​::​overflow запись символов в файл, а затем сбрасывает файл, как если бы путем вызова fflush(file). Если область получения существует, эффект определяется реализацией.

void imbue(const locale& loc) override;

Requires: Если файл не расположен в начале и кодировка текущей локали, определяемая с помощью, зависит от a_­codecvt.encoding() состояния ( [locale.codecvt.virtuals]), то этот фасет совпадает с соответствующим фасетом loc.

Effects: Заставляет символы, вставленные или извлеченные после этого вызова, преобразовываться loc до следующего вызова imbue.

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

30.9.3 Class template basic_­ifstream [ifstream]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class basic_ifstream : public basic_istream<charT, traits> {
  public:
    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;

    // [ifstream.cons], constructors
    basic_ifstream();
    explicit basic_ifstream(const char* s,
                            ios_base::openmode mode = ios_base::in);
    explicit basic_ifstream(const filesystem::path::value_type* s,
                            ios_base::openmode mode = ios_base::in);  // wide systems only; see [fstream.syn]
    explicit basic_ifstream(const string& s,
                            ios_base::openmode mode = ios_base::in);
    explicit basic_ifstream(const filesystem::path& s,
                            ios_base::openmode mode = ios_base::in);
    basic_ifstream(const basic_ifstream& rhs) = delete;
    basic_ifstream(basic_ifstream&& rhs);

    // [ifstream.assign], assign and swap
    basic_ifstream& operator=(const basic_ifstream& rhs) = delete;
    basic_ifstream& operator=(basic_ifstream&& rhs);
    void swap(basic_ifstream& rhs);

    // [ifstream.members], members
    basic_filebuf<charT, traits>* rdbuf() const;

    bool is_open() const;
    void open(const char* s, ios_base::openmode mode = ios_base::in);
    void open(const filesystem::path::value_type* s,
              ios_base::openmode mode = ios_base::in);  // wide systems only; see [fstream.syn]
    void open(const string& s, ios_base::openmode mode = ios_base::in);
    void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);
    void close();
  private:
    basic_filebuf<charT, traits> sb; // exposition only
  };

  template <class charT, class traits>
    void swap(basic_ifstream<charT, traits>& x,
              basic_ifstream<charT, traits>& y);
}

Класс basic_­ifstream<charT, traits> поддерживает чтение из именованных файлов. Он использует basic_­filebuf<​charT, traits> объект для управления связанной последовательностью. Для демонстрации поддерживаемые данные представлены здесь как:

  • sb, filebuf объект.

30.9.3.1 basic_­ifstream constructors [ifstream.cons]

basic_ifstream();

Effects: Создает объект класса basic_­ifstream<charT, traits>, инициализируя базовый класс с помощью basic_­istream(&sb) и инициализируя sb с помощью basic_­filebuf<charT, traits>()) ( [istream.cons], [filebuf.cons]).

explicit basic_ifstream(const char* s, ios_base::openmode mode = ios_base::in); explicit basic_ifstream(const filesystem::path::value_type* s, ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]

Effects: Создает объект класса basic_­ifstream, инициализируя базовый класс с помощью basic_­istream(&sb) и инициализируя sb с помощью basic_­filebuf<charT, traits>()) ( [istream.cons], [filebuf.cons]), затем вызывает rdbuf()->open(s, mode | ios_­base​::​in). Если эта функция возвращает нулевой указатель, вызывает setstate(failbit).

explicit basic_ifstream(const string& s, ios_base::openmode mode = ios_base::in); explicit basic_ifstream(const filesystem::path& s, ios_base::openmode mode = ios_base::in);

Effects: То же, что и basic_­ifstream(s.c_­str(), mode).

basic_ifstream(basic_ifstream&& rhs);

Effects: Переместите конструкции из rvalue rhs. Это достигается перемещением конструирования базового класса и содержащегося в нем basic_­filebuf. Далее basic_­istream<charT, traits>​::​set_­rdbuf(&sb) вызывается для установки содержащегося basic_­filebuf.

30.9.3.2 Assign and swap [ifstream.assign]

basic_ifstream& operator=(basic_ifstream&& rhs);

Effects: Move назначает базу и членов *this из базы и членов-корреспондентов rhs.

Returns: *this.

void swap(basic_ifstream& rhs);

Effects: Меняет состояние *this и rhs по вызову basic_­istream<charT, traits>​::​swap(rhs) и sb.swap(rhs.sb).

template <class charT, class traits> void swap(basic_ifstream<charT, traits>& x, basic_ifstream<charT, traits>& y);

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

30.9.3.3 Member functions [ifstream.members]

basic_filebuf<charT, traits>* rdbuf() const;

Returns: const_­cast<basic_­filebuf<charT, traits>*>(&sb).

bool is_open() const;

Returns: rdbuf()->is_­open().

void open(const char* s, ios_base::openmode mode = ios_base::in); void open(const filesystem::path::value_type* s, ios_base::openmode mode = ios_base::in); // wide systems only; see [fstream.syn]

Effects: Звонки rdbuf()->open(s, mode | ios_­base​::​in). Если эта функция не возвращает вызовы нулевого указателя clear(), в противном случае вызывает setstate(failbit) (который может вызывать ios_­base​::​failure) ( [iostate.flags]).

void open(const string& s, ios_base::openmode mode = ios_base::in); void open(const filesystem::path& s, ios_base::openmode mode = ios_base::in);

Effects: Звонки open(s.c_­str(), mode).

void close();

Effects: Вызывает rdbuf()->close() и, если эта функция возвращает нулевой указатель, вызывает setstate(failbit) (который может вызывать ios_­base​::​failure) ( [iostate.flags]).

30.9.4 Class template basic_­ofstream [ofstream]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class basic_ofstream : public basic_ostream<charT, traits> {
  public:
    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;

    // [ofstream.cons], constructors
    basic_ofstream();
    explicit basic_ofstream(const char* s,
                            ios_base::openmode mode = ios_base::out);
    explicit basic_ofstream(const filesystem::path::value_type* s,
                            ios_base::openmode mode = ios_base::out);  // wide systems only; see [fstream.syn]
    explicit basic_ofstream(const string& s,
                            ios_base::openmode mode = ios_base::out);
    explicit basic_ofstream(const filesystem::path& s,
                            ios_base::openmode mode = ios_base::out);
    basic_ofstream(const basic_ofstream& rhs) = delete;
    basic_ofstream(basic_ofstream&& rhs);

    // [ofstream.assign], assign and swap
    basic_ofstream& operator=(const basic_ofstream& rhs) = delete;
    basic_ofstream& operator=(basic_ofstream&& rhs);
    void swap(basic_ofstream& rhs);

    // [ofstream.members], members
    basic_filebuf<charT, traits>* rdbuf() const;

    bool is_open() const;
    void open(const char* s, ios_base::openmode mode = ios_base::out);
    void open(const filesystem::path::value_type* s,
              ios_base::openmode mode = ios_base::out);  // wide systems only; see [fstream.syn]
    void open(const string& s, ios_base::openmode mode = ios_base::out);
    void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);
    void close();
  private:
    basic_filebuf<charT, traits> sb; // exposition only
  };

  template <class charT, class traits>
    void swap(basic_ofstream<charT, traits>& x,
              basic_ofstream<charT, traits>& y);
}

Класс basic_­ofstream<charT, traits> поддерживает запись в именованные файлы. Он использует basic_­filebuf<​charT, traits> объект для управления связанной последовательностью. Для демонстрации поддерживаемые данные представлены здесь как:

  • sb, filebuf объект.

30.9.4.1 basic_­ofstream constructors [ofstream.cons]

basic_ofstream();

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

explicit basic_ofstream(const char* s, ios_base::openmode mode = ios_base::out); explicit basic_ofstream(const filesystem::path::value_type* s, ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]

Effects: Создает объект класса basic_­ofstream<charT, traits>, инициализируя базовый класс с помощью basic_­ostream(&sb) и инициализируя sb с помощью basic_­filebuf<charT, traits>()) ( [ostream.cons], [filebuf.cons]), затем вызывает rdbuf()->open(s, mode | ios_­base​::​out). Если эта функция возвращает нулевой указатель, вызывает setstate(​failbit).

explicit basic_ofstream(const string& s, ios_base::openmode mode = ios_base::out); explicit basic_ofstream(const filesystem::path& s, ios_base::openmode mode = ios_base::out);

Effects: То же, что и basic_­ofstream(s.c_­str(), mode).

basic_ofstream(basic_ofstream&& rhs);

Effects: Переместите конструкции из rvalue rhs. Это достигается перемещением конструирования базового класса и содержащегося в нем basic_­filebuf. Далее basic_­ostream<charT, traits>​::​set_­rdbuf(&sb) вызывается для установки содержащегося basic_­filebuf.

30.9.4.2 Assign and swap [ofstream.assign]

basic_ofstream& operator=(basic_ofstream&& rhs);

Effects: Move назначает базу и членов *this из базы и членов-корреспондентов rhs.

Returns: *this.

void swap(basic_ofstream& rhs);

Effects: Меняет состояние *this и rhs по вызову basic_­ostream<charT, traits>​::​swap(rhs) и sb.swap(rhs.sb).

template <class charT, class traits> void swap(basic_ofstream<charT, traits>& x, basic_ofstream<charT, traits>& y);

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

30.9.4.3 Member functions [ofstream.members]

basic_filebuf<charT, traits>* rdbuf() const;

Returns: const_­cast<basic_­filebuf<charT, traits>*>(&sb).

bool is_open() const;

Returns: rdbuf()->is_­open().

void open(const char* s, ios_base::openmode mode = ios_base::out); void open(const filesystem::path::value_type* s, ios_base::openmode mode = ios_base::out); // wide systems only; see [fstream.syn]

Effects: Звонки rdbuf()->open(s, mode | ios_­base​::​out). Если эта функция не возвращает вызовы нулевого указателя clear(), в противном случае вызывает setstate(​failbit) (который может вызывать ios_­base​::​failure) ( [iostate.flags]).

void close();

Effects: Вызывает rdbuf()->close() и, если эта функция дает сбой (возвращает нулевой указатель), вызывает setstate(​failbit) (который может вызывать ios_­base​::​failure) ( [iostate.flags]).

void open(const string& s, ios_base::openmode mode = ios_base::out); void open(const filesystem::path& s, ios_base::openmode mode = ios_base::out);

Effects: Звонки open(s.c_­str(), mode).

30.9.5 Class template basic_­fstream [fstream]

namespace std {
  template <class charT, class traits = char_traits<charT>>
  class basic_fstream : public basic_iostream<charT, traits> {
  public:
    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;

    // [fstream.cons], constructors
    basic_fstream();
    explicit basic_fstream(
      const char* s,
      ios_base::openmode mode = ios_base::in | ios_base::out);
    explicit basic_fstream(
      const std::filesystem::path::value_type* s,
      ios_base::openmode mode = ios_base::in|ios_base::out);  // wide systems only; see [fstream.syn]
    explicit basic_fstream(
      const string& s,
      ios_base::openmode mode = ios_base::in | ios_base::out);
    explicit basic_fstream(
      const filesystem::path& s,
      ios_base::openmode mode = ios_base::in | ios_base::out);
    basic_fstream(const basic_fstream& rhs) = delete;
    basic_fstream(basic_fstream&& rhs);

    // [fstream.assign], assign and swap
    basic_fstream& operator=(const basic_fstream& rhs) = delete;
    basic_fstream& operator=(basic_fstream&& rhs);
    void swap(basic_fstream& rhs);

    // [fstream.members], members
    basic_filebuf<charT, traits>* rdbuf() const;
    bool is_open() const;
    void open(
      const char* s,
      ios_base::openmode mode = ios_base::in | ios_base::out);
    void open(
      const std::filesystem::path::value_type* s,
      ios_base::openmode mode = ios_base::in|ios_base::out);  // wide systems only; see [fstream.syn]
    void open(
      const string& s,
      ios_base::openmode mode = ios_base::in | ios_base::out);
    void open(
      const filesystem::path& s,
      ios_base::openmode mode = ios_base::in | ios_base::out);
    void close();

  private:
    basic_filebuf<charT, traits> sb; // exposition only
  };

  template <class charT, class traits>
    void swap(basic_fstream<charT, traits>& x,
              basic_fstream<charT, traits>& y);
}

Шаблон класса basic_­fstream<charT, traits> поддерживает чтение и запись из именованных файлов. Он использует basic_­filebuf<charT, traits> объект для управления связанными последовательностями. Для демонстрации поддерживаемые данные представлены здесь как:

  • sb, basic_­filebuf объект.

30.9.5.1 basic_­fstream constructors [fstream.cons]

basic_fstream();

Effects: Создает объект класса basic_­fstream<charT, traits>, инициализируя базовый класс basic_­iostream(&sb) и инициализируя sb с помощью basic_­filebuf<charT, traits>().

explicit basic_fstream( const char* s, ios_base::openmode mode = ios_base::in | ios_base::out); explicit basic_fstream( const filesystem::path::value_type* s, ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]

Effects: Создает объект класса basic_­fstream<charT, traits>, инициализируя базовый класс basic_­iostream(&sb) и инициализируя sb с помощью basic_­filebuf<charT, traits>(). Потом звонит rdbuf()->open(s, mode). Если эта функция возвращает нулевой указатель, вызывает setstate(failbit).

explicit basic_fstream( const string& s, ios_base::openmode mode = ios_base::in | ios_base::out); explicit basic_fstream( const filesystem::path& s, ios_base::openmode mode = ios_base::in | ios_base::out);

Effects: То же, что и basic_­fstream(s.c_­str(), mode).

basic_fstream(basic_fstream&& rhs);

Effects: Переместите конструкции из rvalue rhs. Это достигается перемещением конструирования базового класса и содержащегося в нем basic_­filebuf. Далее basic_­istream<charT, traits>​::​set_­rdbuf(&sb) вызывается для установки содержащегося basic_­filebuf.

30.9.5.2 Assign and swap [fstream.assign]

basic_fstream& operator=(basic_fstream&& rhs);

Effects: Move назначает базу и членов *this из базы и членов-корреспондентов rhs.

Returns: *this.

void swap(basic_fstream& rhs);

Effects: Меняет состояние *this и rhs по вызову basic_­iostream<charT,traits>​::​swap(rhs) и sb.swap(rhs.sb).

template <class charT, class traits> void swap(basic_fstream<charT, traits>& x, basic_fstream<charT, traits>& y);

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

30.9.5.3 Member functions [fstream.members]

basic_filebuf<charT, traits>* rdbuf() const;

Returns: const_­cast<basic_­filebuf<charT, traits>*>(&sb).

bool is_open() const;

Returns: rdbuf()->is_­open().

void open( const char* s, ios_base::openmode mode = ios_base::in | ios_base::out); void open( const filesystem::path::value_type* s, ios_base::openmode mode = ios_base::in | ios_base::out); // wide systems only; see [fstream.syn]

Effects: Звонки rdbuf()->open(s, mode). Если эта функция не возвращает вызовы нулевого указателя clear(), в противном случае вызывает setstate(failbit) (который может вызывать ios_­base​::​failure) ( [iostate.flags]).

void open( const string& s, ios_base::openmode mode = ios_base::in | ios_base::out); void open( const filesystem::path& s, ios_base::openmode mode = ios_base::in | ios_base::out);

Effects: Звонки open(s.c_­str(), mode).

void close();

Effects: Вызывает rdbuf()->close() и, если эта функция возвращает нулевой указатель, вызывает setstate(failbit) (который может вызывать ios_­base​::​failure) ( [iostate.flags]).

30.10 File systems [filesystems]

30.10.1 General [fs.general]

В этом подпункте описываются операции с файловыми системами и их компонентами, такими как пути, обычные файлы и каталоги.

30.10.2 Conformance [fs.conformance]

Соответствие определяется поведением. Идеальное поведение не всегда реализуемо, поэтому в подразделах о соответствии это учтено.

30.10.2.1 POSIX conformance [fs.conform.9945]

Некоторое поведение определяется ссылкой на POSIX ( [fs.norm.ref]). Как на самом деле реализуется такое поведение, не уточняется. [ Note: Это составляет правило «как если бы», позволяющее реализациям вызывать собственную операционную систему или другие API. ] end note

Реализациям рекомендуется обеспечивать такое поведение, как оно определено в POSIX. Реализации должны документировать любое поведение, которое отличается от поведения, определенного POSIX. Реализациям, которые не поддерживают точное поведение POSIX, рекомендуется обеспечивать поведение, максимально приближенное к поведению POSIX, насколько это разумно с учетом ограничений реальных операционных систем и файловых систем. Если реализация не может обеспечить какое-либо разумное поведение, реализация должна сообщить об ошибке, как указано в [fs.err.report]. [ Note: Это позволяет пользователям полагаться на возникшее исключение или установленный код ошибки, когда реализация не может обеспечить какое-либо разумное поведение. ]end note

Реализации не обязаны обеспечивать поведение, которое не поддерживается конкретной файловой системой. [ Example: Файловая система FAT, используемая некоторыми картами памяти, памятью камеры и гибкими дисками, не поддерживает жесткие ссылки, символические ссылки и многие другие функции более функциональных файловых систем, поэтому не требуются реализации для поддержки этих функций в файловой системе FAT, но вместо этого требуется сообщить об ошибке, как описано выше. ]end example

30.10.2.2 Operating system dependent behavior conformance [fs.conform.os]

Некоторое поведение указывается как имеющееся operating system dependent. Операционная система, от которой зависит реализация, определяется реализацией.

Допускается, чтобы реализация зависела от эмулятора операционной системы, а не от фактической базовой операционной системы.

30.10.2.3 File system race behavior [fs.race.behavior]

Поведение не определено, если вызовы функций, предоставленные этим подпунктом, вводят file system race.

Если возможность гонки файловой системы сделает для программы ненадежной проверку предусловия перед вызовом функции, описанной здесь, Requires: для функции не указано. [ Note: В соответствии с практикой проектирования предварительные условия не указываются, когда программа не имеет смысла обнаруживать их до вызова функции. ]end note

30.10.3 Normative references [fs.norm.ref]

В этом подпункте для демонстрации упоминаются коммерчески доступные операционные системы.328

POSIX® - зарегистрированная торговая марка IEEE. Windows® является зарегистрированным товарным знаком Microsoft Corporation. Эта информация дается для удобства пользователей этого документа и не означает одобрения этих продуктов со стороны ISO или IEC.

30.10.4 Terms and definitions [fs.definitions]

30.10.5 absolute path [fs.def.absolute.path]

Путь, который однозначно определяет местоположение файла без ссылки на дополнительное начальное местоположение. Элементы пути, определяющие, является ли он абсолютным, зависят от операционной системы.

30.10.6 directory [fs.def.directory]

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

30.10.7 file [fs.def.file]

Объект в файловой системе, содержащий пользовательские или системные данные. Файлы можно записывать, читать из них или и то, и другое. У файла есть определенные атрибуты, включая тип. Типы файлов включают обычные файлы и каталоги. Другие типы файлов, например symbolic links, могут поддерживаться реализацией.

30.10.8 file system [fs.def.filesystem]

Коллекция файлов и их атрибутов.

30.10.9 file system race [fs.def.race]

Состояние, которое возникает, когда несколько потоков, процессов или компьютеров чередуют доступ и изменение одного и того же объекта в файловой системе.

30.10.10 filename [fs.def.filename]

Имя файла. Имена файлов dot и dot-dot, состоящие только из одного и двух символов точки соответственно, имеют особое значение. Следующие характеристики имен файлов зависят от операционной системы:

  • Разрешенные символы. [ Example: Некоторые операционные системы запрещают использование управляющих символов ASCII (0x00 - 0x1F) в именах файлов. ] end example

  • Максимально допустимая длина.

  • Запрещенные имена файлов.

  • Имена файлов, имеющие особое значение.

  • Знание регистра и чувствительность при разрешении пути.

  • Специальные правила, которые могут применяться к типам файлов, отличных от обычных файлов, например к каталогам.

30.10.13 native encoding [fs.def.native.encode]

Для узких символьных строк текущая кодировка путей ( [fs.def.pathname]) зависит от операционной системы . Для строк широких символов определяется реализация кодировки расширенного набора символов ( [lex.charset]).

30.10.14 native pathname format [fs.def.native]

Формат пути, зависящий от операционной системы, принимаемый операционной системой хоста.

30.10.15 normal form [fs.def.normal.form]

Путь в нормальной форме называется normalized. Вызывается процесс получения нормализованного пути из пути, который не находится в нормальной форме normalization.

Нормализация имени пути общего формата означает:

  1. Если путь пуст, остановитесь.

  2. Замените каждый символ косой черты в root-nameсимволе preferred-separator.

  3. Замените каждый directory-separatorна preferred-separator. [ Note: Общая грамматика имени пути ( [fs.path.generic]) определяет directory-separatorкак одну или несколько косых черт и preferred-separators. ] end note

  4. Удалите каждое dot имя файла и все сразу после него directory-separator.

  5. Если появятся какие-либо, удалите не dot-dot имя файла, за которым сразу следует имя directory-separatorи dot-dot имя файла, а также все, что непосредственно следует за ним directory-separator.

  6. Если есть root-directory, удалите все dot-dot имена файлов и все, что directory-separators сразу после них. [ Note: Эти dot-dot имена файлов пытаются ссылаться на несуществующие родительские каталоги. ] end note

  7. Если последним именем файла является dot-dot, удалите все завершающие directory-separator.

  8. Если путь пуст, добавьте dot.

30.10.16 operating system dependent behavior [fs.def.osdep]

Поведение, зависящее от поведения и характеристик операционной системы. Смотрите [fs.conform.os].

30.10.17 parent directory [fs.def.parent]

& langle; каталога & rangle; каталог, который содержит запись каталога для данного каталога и представлен именем файла dot-dot в данном каталоге.

30.10.18 parent directory [fs.def.parent.other]

& langle; других типов файлов & rangle; каталог, содержащий запись каталога для обсуждаемого файла.

30.10.19 path [fs.def.path]

Последовательность элементов, определяющих расположение файла в файловой системе. Эти элементы являются root-nameopt, root-directoryoptи необязательной последовательностью имен файлов. Максимальное количество элементов в последовательности зависит от операционной системы.

30.10.20 pathname [fs.def.pathname]

Строка символов, представляющая имя пути. Имена путей форматируются в соответствии с generic pathname format грамматикой или собственным форматом имени пути, зависящим от операционной системы.

30.10.21 pathname resolution [fs.def.pathres]

Разрешение имени пути - это зависимый от операционной системы механизм для разрешения имени пути к определенному файлу в файловой иерархии. Может быть несколько имен пути, которые разрешаются в один и тот же файл. [ Example: POSIX определяет механизм в разделе 4.11, Разрешение пути. ]end example

30.10.22 relative path [fs.def.rel.path]

Путь, который не является абсолютным и как таковой, только однозначно определяет местоположение файла при разрешении ( [fs.def.pathres]) относительно предполагаемого начального местоположения. Элементы пути, определяющие, является ли он относительным, зависят от операционной системы. [ Note: Пути "." и «..» - относительные пути. ]end note

30.10.24 Requirements [fs.req]

На протяжении всего этого подпункта, char, wchar_­t, char16_­t, и char32_­t собирательно называют encoded character types.

Функции с указанными параметрами шаблона EcharT не должны участвовать в разрешении перегрузки, если EcharT это не один из типов закодированных символов.

Именованные параметры шаблона InputIterator должны соответствовать input iterator requirements и должны иметь тип значения, который является одним из типов кодированных символов.

[ Note: Использование кодированного типа символа подразумевает связанный набор символов и кодировку. Поскольку signed char и не unsigned char имеют подразумеваемого набора символов и кодировки, они не включены как разрешенные типы. ] end note

Названные параметры шаблона Allocator должны соответствовать стандарту Allocator requirements.

30.10.24.1 Namespaces and headers [fs.req.namespace]

Если не указано иное, предполагается, что ссылки на сущности, описанные в этом подпункте, дополнены ​::​std​::​filesystem​::​.

30.10.25 Header <filesystem> synopsis [fs.filesystem.syn]

namespace std::filesystem {
  // [fs.class.path], paths
  class path;

  // [fs.path.nonmember], path non-member functions
  void swap(path& lhs, path& rhs) noexcept;
  size_t hash_value(const path& p) noexcept;

  bool operator==(const path& lhs, const path& rhs) noexcept;
  bool operator!=(const path& lhs, const path& rhs) noexcept;
  bool operator< (const path& lhs, const path& rhs) noexcept;
  bool operator<=(const path& lhs, const path& rhs) noexcept;
  bool operator> (const path& lhs, const path& rhs) noexcept;
  bool operator>=(const path& lhs, const path& rhs) noexcept;

  path operator/ (const path& lhs, const path& rhs);

  // [fs.path.io], path inserter and extractor
  template <class charT, class traits>
    basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& os, const path& p);
  template <class charT, class traits>
    basic_istream<charT, traits>&
      operator>>(basic_istream<charT, traits>& is, path& p);

  // [fs.path.factory], path factory functions
  template <class Source>
    path u8path(const Source& source);
  template <class InputIterator>
    path u8path(InputIterator first, InputIterator last);

  // [fs.class.filesystem_error], filesystem errors
  class filesystem_error;

  // [fs.class.directory_entry], directory entries
  class directory_entry;

  // [fs.class.directory_iterator], directory iterators
  class directory_iterator;

  // [fs.dir.itr.nonmembers], range access for directory iterators
  directory_iterator begin(directory_iterator iter) noexcept;
  directory_iterator end(const directory_iterator&) noexcept;

  // [fs.class.rec.dir.itr], recursive directory iterators
  class recursive_directory_iterator;

  // [fs.rec.dir.itr.nonmembers], range access for recursive directory iterators
  recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;
  recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;

  // [fs.class.file_status], file status
  class file_status;

  struct space_info {
    uintmax_t capacity;
    uintmax_t free;
    uintmax_t available;
  };

  // [fs.enum], enumerations
  enum class file_type;
  enum class perms;
  enum class perm_options;
  enum class copy_options;
  enum class directory_options;

  using file_time_type = chrono::time_point<trivial-clock>;

  // [fs.op.funcs], filesystem operations
  path absolute(const path& p, const path& base = current_path());

  path canonical(const path& p, const path& base = current_path());
  path canonical(const path& p, error_code& ec);
  path canonical(const path& p, const path& base, error_code& ec);

  void copy(const path& from, const path& to);
  void copy(const path& from, const path& to, error_code& ec) noexcept;
  void copy(const path& from, const path& to, copy_options options);
  void copy(const path& from, const path& to, copy_options options,
            error_code& ec) noexcept;

  bool copy_file(const path& from, const path& to);
  bool copy_file(const path& from, const path& to, error_code& ec) noexcept;
  bool copy_file(const path& from, const path& to, copy_options option);
  bool copy_file(const path& from, const path& to, copy_options option,
                 error_code& ec) noexcept;

  void copy_symlink(const path& existing_symlink, const path& new_symlink);
  void copy_symlink(const path& existing_symlink, const path& new_symlink,
                    error_code& ec) noexcept;

  bool create_directories(const path& p);
  bool create_directories(const path& p, error_code& ec) noexcept;

  bool create_directory(const path& p);
  bool create_directory(const path& p, error_code& ec) noexcept;

  bool create_directory(const path& p, const path& attributes);
  bool create_directory(const path& p, const path& attributes,
                        error_code& ec) noexcept;

  void create_directory_symlink(const path& to, const path& new_symlink);
  void create_directory_symlink(const path& to, const path& new_symlink,
                                error_code& ec) noexcept;

  void create_hard_link(const path& to, const path& new_hard_link);
  void create_hard_link(const path& to, const path& new_hard_link,
                        error_code& ec) noexcept;

  void create_symlink(const path& to, const path& new_symlink);
  void create_symlink(const path& to, const path& new_symlink,
                      error_code& ec) noexcept;

  path current_path();
  path current_path(error_code& ec);
  void current_path(const path& p);
  void current_path(const path& p, error_code& ec) noexcept;

  bool exists(file_status s) noexcept;
  bool exists(const path& p);
  bool exists(const path& p, error_code& ec) noexcept;

  bool equivalent(const path& p1, const path& p2);
  bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;

  uintmax_t file_size(const path& p);
  uintmax_t file_size(const path& p, error_code& ec) noexcept;

  uintmax_t hard_link_count(const path& p);
  uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;

  bool is_block_file(file_status s) noexcept;
  bool is_block_file(const path& p);
  bool is_block_file(const path& p, error_code& ec) noexcept;

  bool is_character_file(file_status s) noexcept;
  bool is_character_file(const path& p);
  bool is_character_file(const path& p, error_code& ec) noexcept;

  bool is_directory(file_status s) noexcept;
  bool is_directory(const path& p);
  bool is_directory(const path& p, error_code& ec) noexcept;

  bool is_empty(const path& p);
  bool is_empty(const path& p, error_code& ec) noexcept;

  bool is_fifo(file_status s) noexcept;
  bool is_fifo(const path& p);
  bool is_fifo(const path& p, error_code& ec) noexcept;

  bool is_other(file_status s) noexcept;
  bool is_other(const path& p);
  bool is_other(const path& p, error_code& ec) noexcept;

  bool is_regular_file(file_status s) noexcept;
  bool is_regular_file(const path& p);
  bool is_regular_file(const path& p, error_code& ec) noexcept;

  bool is_socket(file_status s) noexcept;
  bool is_socket(const path& p);
  bool is_socket(const path& p, error_code& ec) noexcept;

  bool is_symlink(file_status s) noexcept;
  bool is_symlink(const path& p);
  bool is_symlink(const path& p, error_code& ec) noexcept;

  file_time_type last_write_time(const path& p);
  file_time_type last_write_time(const path& p, error_code& ec) noexcept;
  void last_write_time(const path& p, file_time_type new_time);
  void last_write_time(const path& p, file_time_type new_time,
                       error_code& ec) noexcept;

  void permissions(const path& p, perms prms, perm_options opts=perm_options::replace);
  void permissions(const path& p, perms prms, error_code& ec) noexcept;
  void permissions(const path& p, perms prms, perm_options opts, error_code& ec);

  path proximate(const path& p, error_code& ec);
  path proximate(const path& p, const path& base = current_path());
  path proximate(const path& p, const path& base, error_code& ec);

  path read_symlink(const path& p);
  path read_symlink(const path& p, error_code& ec);

  path relative(const path& p, error_code& ec);
  path relative(const path& p, const path& base = current_path());
  path relative(const path& p, const path& base, error_code& ec);

  bool remove(const path& p);
  bool remove(const path& p, error_code& ec) noexcept;

  uintmax_t remove_all(const path& p);
  uintmax_t remove_all(const path& p, error_code& ec) noexcept;

  void rename(const path& from, const path& to);
  void rename(const path& from, const path& to, error_code& ec) noexcept;

  void resize_file(const path& p, uintmax_t size);
  void resize_file(const path& p, uintmax_t size, error_code& ec) noexcept;

  space_info space(const path& p);
  space_info space(const path& p, error_code& ec) noexcept;

  file_status status(const path& p);
  file_status status(const path& p, error_code& ec) noexcept;

  bool status_known(file_status s) noexcept;

  file_status symlink_status(const path& p);
  file_status symlink_status(const path& p, error_code& ec) noexcept;

  path temp_directory_path();
  path temp_directory_path(error_code& ec);

  path weakly_canonical(const path& p);
  path weakly_canonical(const path& p, error_code& ec);
}

trivial-clock - это определяемый реализацией тип, который удовлетворяет требованиям TrivialClock requirements и может представлять и измерять значения времени файла. Реализации должны гарантировать, что разрешение и диапазон file_­time_­type отражают разрешение, зависящее от операционной системы, и диапазон значений времени файла.

30.10.26 Error reporting [fs.err.report]

Функции библиотеки файловой системы часто предоставляют две перегрузки: одна генерирует исключение для сообщения об ошибках файловой системы, а другая устанавливает файл error_­code. [ Note: Это поддерживает два распространенных варианта использования:

  • Используется там, где ошибки файловой системы действительно исключительны и указывают на серьезный сбой. Выброс исключения - это подходящий ответ.

  • Используется там, где ошибки файловой системы являются обычными и не обязательно означают сбой. Наиболее подходящим ответом является возврат кода ошибки. Это позволяет обрабатывать ошибки приложения, в том числе просто игнорировать ошибку.

end note]

Функции, не имеющие аргумента типа, error_­code& обрабатывают ошибки следующим образом, если не указано иное:

  • Когда вызов реализацией операционной системы или другого базового API приводит к ошибке, которая не позволяет функции соответствовать ее спецификациям, filesystem_­error должно быть выброшено исключение типа . Для функций с одним аргументом пути этот аргумент должен быть передан filesystem_­error конструктору с одним аргументом пути. Для функций с двумя аргументами пути первый из этих аргументов должен быть передан filesystem_­error конструктору как path1 аргумент, а второй должен быть передан как path2 аргумент. В filesystem_­error конструкторском error_­code аргумент устанавливается в зависимости от обстоятельств зависимой ошибки конкретной операционной системы.

  • О невозможности выделить хранилище сообщается путем выдачи исключения, как описано в [res.on.exception.handling].

  • Деструкторы ничего не выкидывают.

Функции, имеющие аргумент типа, error_­code& обрабатывают ошибки следующим образом, если не указано иное:

  • Если вызов реализацией операционной системы или другого базового API приводит к ошибке, которая не позволяет функции соответствовать ее спецификациям, error_­code& аргумент устанавливается в соответствии с конкретной зависимой от операционной системы ошибкой. В противном случае clear() вызывается error_­code& аргумент.

30.10.27 Class path [fs.class.path]

Объект класса path представляет собой path и содержит pathname. Такой объект касается только лексических и синтаксических аспектов пути. Путь не обязательно существует во внешнем хранилище, и путь не обязательно действителен для текущей операционной системы или для конкретной файловой системы.

[ Note: Класс path используется для поддержки различий между типами строк, используемых разными операционными системами для представления имен путей, и для выполнения преобразований между кодировками, когда это необходимо. ]end note

namespace std::filesystem {
  class path {
  public:
    using value_type  = see below;
    using string_type = basic_string<value_type>;
    static constexpr value_type preferred_separator = see below;

    // [fs.enum.path.format], enumeration format
    enum format;

    // [fs.path.construct], constructors and destructor
    path() noexcept;
    path(const path& p);
    path(path&& p) noexcept;
    path(string_type&& source, format fmt = auto_format);
    template <class Source>
      path(const Source& source, format fmt = auto_format);
    template <class InputIterator>
      path(InputIterator first, InputIterator last, format fmt = auto_format);
    template <class Source>
      path(const Source& source, const locale& loc, format fmt = auto_format);
    template <class InputIterator>
      path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);
    ~path();

    // [fs.path.assign], assignments
    path& operator=(const path& p);
    path& operator=(path&& p) noexcept;
    path& operator=(string_type&& source);
    path& assign(string_type&& source);
    template <class Source>
      path& operator=(const Source& source);
    template <class Source>
      path& assign(const Source& source)
    template <class InputIterator>
      path& assign(InputIterator first, InputIterator last);

    // [fs.path.append], appends
    path& operator/=(const path& p);
    template <class Source>
      path& operator/=(const Source& source);
    template <class Source>
      path& append(const Source& source);
    template <class InputIterator>
      path& append(InputIterator first, InputIterator last);

    // [fs.path.concat], concatenation
    path& operator+=(const path& x);
    path& operator+=(const string_type& x);
    path& operator+=(basic_string_view<value_type> x);
    path& operator+=(const value_type* x);
    path& operator+=(value_type x);
    template <class Source>
      path& operator+=(const Source& x);
    template <class EcharT>
      path& operator+=(EcharT x);
    template <class Source>
      path& concat(const Source& x);
    template <class InputIterator>
      path& concat(InputIterator first, InputIterator last);

    // [fs.path.modifiers], modifiers
    void  clear() noexcept;
    path& make_preferred();
    path& remove_filename();
    path& replace_filename(const path& replacement);
    path& replace_extension(const path& replacement = path());
    void  swap(path& rhs) noexcept;

    // [fs.path.native.obs], native format observers
    const string_type& native() const noexcept;
    const value_type*  c_str() const noexcept;
    operator string_type() const;

    template <class EcharT, class traits = char_traits<EcharT>,
              class Allocator = allocator<EcharT>>
      basic_string<EcharT, traits, Allocator>
        string(const Allocator& a = Allocator()) const;
    std::string    string() const;
    std::wstring   wstring() const;
    std::string    u8string() const;
    std::u16string u16string() const;
    std::u32string u32string() const;

    // [fs.path.generic.obs], generic format observers
    template <class EcharT, class traits = char_traits<EcharT>,
              class Allocator = allocator<EcharT>>
      basic_string<EcharT, traits, Allocator>
        generic_string(const Allocator& a = Allocator()) const;
    std::string    generic_string() const;
    std::wstring   generic_wstring() const;
    std::string    generic_u8string() const;
    std::u16string generic_u16string() const;
    std::u32string generic_u32string() const;

    // [fs.path.compare], compare
    int  compare(const path& p) const noexcept;
    int  compare(const string_type& s) const;
    int  compare(basic_string_view<value_type> s) const;
    int  compare(const value_type* s) const;

    // [fs.path.decompose], decomposition
    path root_name() const;
    path root_directory() const;
    path root_path() const;
    path relative_path() const;
    path parent_path() const;
    path filename() const;
    path stem() const;
    path extension() const;

    // [fs.path.query], query
    bool empty() const noexcept;
    bool has_root_name() const;
    bool has_root_directory() const;
    bool has_root_path() const;
    bool has_relative_path() const;
    bool has_parent_path() const;
    bool has_filename() const;
    bool has_stem() const;
    bool has_extension() const;
    bool is_absolute() const;
    bool is_relative() const;

    // [fs.path.gen], generation
    path lexically_normal() const;
    path lexically_relative(const path& base) const;
    path lexically_proximate(const path& base) const;

    // [fs.path.itr], iterators
    class iterator;
    using const_iterator = iterator;

    iterator begin() const;
    iterator end() const;
  };
}

value_­type - это typedef тип кодированных символов, зависящий от операционной системы, используемый для представления имен путей.

Значение preferred_­separator члена - это зависимый от операционной системы preferred-separatorсимвол ( [fs.path.generic]).

[ Example: Для операционных систем на базе POSIX value_­type есть char и preferred_­separator остается косая черта ( '/'). В операционных системах Windows value_­type есть wchar_­t и preferred_­separator остается символ обратной косой черты ( L'\\'). ]end example

30.10.27.1 Generic pathname format [fs.path.generic]

pathname:
	root-nameopt root-directoryopt relative-path
root-name:
	operating system dependent sequences of characters
	implementation-defined sequences of characters
root-directory:
	directory-separator
relative-path:
	filename
	filename directory-separator relative-path
	an empty path
filename:
	non-empty sequence of characters other than directory-separator characters
directory-separator:
	preferred-separator directory-separatoropt
	fallback-separator directory-separatoropt
preferred-separator:
	operating system dependent directory separator character
fallback-separator:
	/, if preferred-separator is not /

[ Note: Операционные системы часто накладывают ограничения на символы, которые могут использоваться в файле filename. Для широкой переносимости пользователи могут захотеть ограничить количество filename символов набором символов переносимого имени файла POSIX: ]
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
a b c d e f g h i j k l m n o p q r s t u v w x y z
0 1 2 3 4 5 6 7 8 9 . _­ - end note

За исключением a root-name, несколько следующих друг за другом directory-separatorсимволов считаются одним directory-separatorсимволом.

Имя файла dot ( [fs.def.filename]) рассматривается как ссылка на текущий каталог. Имя файла dot-dot ( [fs.def.filename]) рассматривается как ссылка на родительский каталог. То , что имя файл dot-dot относится к относительно root-directoryявляется реализацией. Определенные имена файлов могут иметь особое значение для конкретной операционной системы.

A root-nameопределяет начальное местоположение для разрешения имени пути ( [fs.def.pathres]). Если нет зависимостей от операционной системы root-names, требуется по крайней мере одна реализация, определяемая root-name. [ Note: Многие операционные системы определяют имя, начинающееся с двух directory-separatorсимволов, как, root-nameкоторое идентифицирует расположение сети или других ресурсов. Некоторые операционные системы определяют одну букву, за которой следует двоеточие, как спецификатор диска - root-name идентифицирующий конкретное устройство, такое как диск. ]end note

Если a root-nameв остальном неоднозначно, выбирается вариант с самой длинной последовательностью символов. [ Note: В операционной системе, подобной POSIX, невозможно иметь root-nameи relative-path без промежуточных root-directoryэлементов. ]end note

30.10.27.2 path conversions [fs.path.cvt]

30.10.27.2.1 path argument format conversions [fs.path.fmt.cvt]

[ Note: Преобразования формата, описанные в этом разделе, не применяются в операционных системах на базе POSIX, потому что в этих системах:

  • Общий формат приемлем как собственный путь.

  • Нет необходимости различать собственный формат и общий формат в аргументах функции.

  • Пути к обычным файлам и пути к каталогам имеют одинаковый синтаксис.

end note]

Некоторые функции определены для приема detected-format аргументов, которые представляют собой последовательности символов. Аргумент обнаруженного формата представляет путь с использованием либо имени пути в, generic format либо имени пути в native format. Такой аргумент считается имеющимся в общем формате тогда и только тогда, когда он соответствует универсальному формату и неприемлем для операционной системы в качестве собственного пути.

[ Note: Некоторые операционные системы могут не иметь однозначного способа различить аргументы собственного формата и универсального формата. Это сделано специально, поскольку упрощает использование операционных систем, не требующих устранения неоднозначности. Реализации для операционной системы, где требуется разрешение неоднозначности, разрешено различать форматы. ]end note

При необходимости имена путей преобразуются между общим и собственным форматами в зависимости от операционной системы. Пусть G(n) и N(g) в математическом смысле будут функциями реализации, которые преобразуют родной формат в общий и общий в собственный формат соответственно. Если g=G(n) для некоторых n, то G(N(g))=g; если n=N(g) для некоторых g, то N(G(n))=n. [ Note: Ни и G не N должны быть обратимыми. ] end note

Если собственный формат требует, чтобы пути к обычным файлам были отформатированы иначе, чем пути к каталогам, путь должен рассматриваться как путь к каталогу, если его последний элемент - a directory-separator, в противном случае он должен рассматриваться как путь к обычному файлу.

[ Note: Путь хранит имя пути в собственном формате ( [fs.path.native.obs]) и действует так, как если бы он также хранит имя пути общего формата, как указано ниже. Реализация может сгенерировать имя пути общего формата на основе имени пути в собственном формате (и, возможно, другой информации) по запросу. ]end note

Когда путь строится из или ему назначается одно представление, отдельное от любого пути, другое представление выбирается соответствующей функцией преобразования ( G или N).

Когда (новое) значение p одного представления пути получается из представления того или иного пути, значение q выбирается для другого представления. Значение q преобразуется в p (по G или N в зависимости от обстоятельств), если это делает какое-либо такое значение; q иначе не указано. [ Note: Если q это результат преобразования любого пути, то это результат преобразования p. ]end note

30.10.27.2.2 path type and encoding conversions [fs.path.type.cvt]

Для аргументов функций-членов, которые принимают последовательности символов, представляющих пути, и для функций-членов, возвращающих строки, преобразование типа значения и кодировки выполняется, если тип значения аргумента или возвращаемого значения отличается от path​::​value_­type. Для аргумента или возвращаемого значения метод преобразования и кодировка, в которую нужно преобразовать, определяются его типом значения:

  • char: Кодировка является собственной узкой кодировкой ( [fs.def.native.encode]). Метод преобразования, если таковой имеется, зависит от операционной системы. [ Note: Для POSIX операционных систем на основе path​::​value_­type является char поэтому не преобразование из char аргументов типа значения или char значений типа возвращаемого значения не выполняется. Для операционных систем на базе Windows собственная узкая кодировка определяется путем вызова функции Windows API. ] [ Это приводит к поведению, аналогичному поведению других стандартных библиотечных функций C и C ++, которые выполняют файловые операции с использованием узких строк символов для определения путей. Изменение такого поведения может вызвать удивление и привести к ошибкам. ] end noteNote: end note

  • wchar_­t: Кодировка native wide encoding. Метод преобразования не указан. [ Note: Для операционных систем на базе Windows не path​::​value_­type выполняется wchar_­t преобразование из wchar_­t аргументов типа значения или в wchar_­t возвращаемые значения типа значения. ] end note

  • char16_­t: Кодировка - UTF-16. Метод преобразования не указан.

  • char32_­t: Кодировка - UTF-32. Метод преобразования не указан.

Если преобразуемая кодировка не имеет представления для исходных символов, результирующие преобразованные символы, если таковые имеются, не определены. Реализации не должны изменять аргументы функций-членов, если они уже имеют тип path​::​value_­type.

30.10.27.3 path requirements [fs.path.req]

В дополнение к требованиям ( [fs.req]), указанные параметры шаблона функции Source должны быть одним из следующих:

  • basic_­string<EcharT, traits, Allocator>. Аргумент функции const Source& source должен иметь эффективный диапазон [source.begin(), source.end()).

  • basic_­string_­view<EcharT, traits>. Аргумент функции const Source& source должен иметь эффективный диапазон [source.begin(), source.end()).

  • Тип, отвечающий требованиям итератора ввода, который выполняет итерацию по NTCTS. Тип значения должен быть типом закодированного символа. Аргумент функции const Source& source должен иметь эффективный диапазон, [source, end) где end - первое значение итератора со значением элемента, равным iterator_­traits<Source>​::​value_­type().

  • Символьный массив, который после преобразования массива в указатель приводит к указателю на начало NTCTS. Тип значения должен быть типом закодированного символа. Аргумент функции const Source& source должен иметь эффективный диапазон, [source, end) где end - первое значение итератора со значением элемента, равным iterator_­traits<decay_­t<Source>>​::​value_­type().

Функции, принимающие указанные параметры шаблона Source , не должны участвовать в разрешении перегрузки, если либо

  • Source является специализацией basic_­string или basic_­string_­view, или

  • qualified-id iterator_­traits<decay_­t<Source>>​::​value_­type является действительным , и обозначает , возможно , const закодированный тип символов ( [temp.deduct]).

[ Note: Посмотрите, path conversions как указанные выше типы значений и их кодировки преобразуются в path​::​value_­type и его кодировку. ]end note

Аргументы типа Source не должны быть нулевыми указателями.

30.10.27.4 path members [fs.path.member]

30.10.27.4.1 path constructors [fs.path.construct]

path() noexcept;

Effects: Создает объект класса path.

Postconditions: empty() == true.

path(const path& p); path(path&& p) noexcept;

Effects: Создает объект класса, path имеющий тот же путь в собственном и универсальном форматах, соответственно, что и исходное значение p. Во второй форме p остается в допустимом, но неуказанном состоянии.

path(string_type&& source, format fmt = auto_format);

Effects: Создает объект класса, path для которого имя пути в обнаруженном формате source имеет исходное значение source ( [fs.path.fmt.cvt]), преобразовывая формат, если требуется ( [fs.path.fmt.cvt]). source остается в допустимом, но неуказанном состоянии.

template <class Source> path(const Source& source, format fmt = auto_format); template <class InputIterator> path(InputIterator first, InputIterator last, format fmt = auto_format);

Effects: Позвольте s быть эффективным диапазоном source ( [fs.path.req]) или диапазоном [first, last)с преобразованной кодировкой, если требуется ( [fs.path.cvt]). Находит обнаруженный формат s ( [fs.path.fmt.cvt]) и создает объект класса, path для которого задан путь в этом формате s.

template <class Source> path(const Source& source, const locale& loc, format fmt = auto_format); template <class InputIterator> path(InputIterator first, InputIterator last, const locale& loc, format fmt = auto_format);

Requires: Тип значения Source и InputIterator есть char.

Effects: Позвольте s быть эффективным диапазоном source или диапазоном [first, last)после преобразования кодировки следующим образом:

  • Если value_­type есть wchar_­t, преобразуется в стандартную широкую кодировку ( [fs.def.native.encode]) с использованием codecvt<​wchar_­t, char, mbstate_­t> аспекта loc.

  • В противном случае выполняется преобразование с использованием codecvt<wchar_­t, char, mbstate_­t> фасета loc, а затем выполняется второе преобразование в текущую узкую кодировку.

Находит обнаруженный формат s ( [fs.path.fmt.cvt]) и создает объект класса, path для которого задан путь в этом формате s.

[ Example: Строка должна быть прочитана из базы данных, которая закодирована в ISO / IEC 8859-1, и использована для создания каталога:

namespace fs = std::filesystem;
std::string latin1_string = read_latin1_data();
codecvt_8859_1<wchar_t> latin1_facet;
std::locale latin1_locale(std::locale(), latin1_facet);
fs::create_directory(fs::path(latin1_string, latin1_locale));

Для операционных систем на основе POSIX путь создается путем использования сначала latin1_­facet для преобразования кодировки ISO / IEC 8859-1 latin1_­string в широкую символьную строку в собственной широкой кодировке ( [fs.def.native.encode]). Полученная в результате широкая строка затем преобразуется в строку узкого символьного имени пути в текущей собственной узкой кодировке. Если собственная широкая кодировка - UTF-16 или UTF-32, а текущая собственная узкая кодировка - UTF-8, все символы в наборе символов ISO / IEC 8859-1 будут преобразованы в их представление Unicode, но для других в родных узких кодировках некоторые символы могут не иметь представления.

Для операционных систем на базе Windows путь создается с использованием latin1_­facet преобразования ISO / IEC 8859-1 latin1_­string в строку имени пути с расширенными символами в кодировке UTF-16. Все символы в наборе символов ISO / IEC 8859-1 будут преобразованы в их представление Unicode. ] end example

30.10.27.4.2 path assignments [fs.path.assign]

path& operator=(const path& p);

Effects: Если *this и p являются одним и тем же объектом, не действует. В противном случае устанавливает оба соответствующих пути *this в соответствующие пути к p.

Returns: *this.

path& operator=(path&& p) noexcept;

Effects: Если *this и p являются одним и тем же объектом, не действует. В противном случае устанавливает оба соответствующих пути *this в соответствующие пути к p. p остается в допустимом, но неуказанном состоянии. [ Note: Допустимая реализация swap(p). ] end note

Returns: *this.

path& operator=(string_type&& source); path& assign(string_type&& source);

Effects: Устанавливает имя пути в обнаруженном формате source в исходное значение source. source остается в допустимом, но неуказанном состоянии.

Returns: *this.

template <class Source> path& operator=(const Source& source); template <class Source> path& assign(const Source& source); template <class InputIterator> path& assign(InputIterator first, InputIterator last);

Effects: Позвольте s быть эффективным диапазоном source ( [fs.path.req]) или диапазоном [first, last)с преобразованной кодировкой, если требуется ( [fs.path.cvt]). Находит обнаруженный формат s ( [fs.path.fmt.cvt]) и устанавливает путь в этом формате равным s.

Returns: *this.

30.10.27.4.3 path appends [fs.path.append]

Операции добавления используются operator/= для обозначения их семантического эффекта добавления preferred-separatorпри необходимости.

path& operator/=(const path& p);

Effects: Если p.is_­absolute() || (p.has_­root_­name() && p.root_­name() != root_­name()), то operator=(p).

В противном случае изменяется, *this как если бы эти шаги:

  • Если p.has_­root_­directory(), то удаляет любой корневой каталог и относительный путь из имени пути общего формата. В противном случае, если !has_­root_­directory() && is_­absolute() есть true или если has_­filename() есть true, то добавляется path​::​preferred_­separator к имени пути общего формата.

  • Затем добавляет путь в собственном формате p, исключая любые root-nameиз его имени пути общего формата, к имени пути в собственном формате.

[ Example: Даже если //host интерпретируются как root-name, оба пути path("//host")/"foo" и path("//host/")/"foo" равны "//host/foo".

Примеры выражений:

// On POSIX,
path("foo") / "";     // yields "foo/"
path("foo") / "/bar"; // yields "/bar"
// On Windows, backslashes replace slashes in the above yields

// On Windows,
path("foo") / "c:/bar";  // yields "c:/bar"
path("foo") / "c:";      // yields "c:"
path("c:") / "";         // yields "c:"
path("c:foo") / "/bar";  // yields "c:/bar"
path("c:foo") / "c:bar"; // yields "c:foo/bar"

end example]

Returns: *this.

template <class Source> path& operator/=(const Source& source); template <class Source> path& append(const Source& source);

Effects: Эквивалентен: return operator/=(path(source));

template <class InputIterator> path& append(InputIterator first, InputIterator last);

Effects: Эквивалентен: return operator/=(path(first, last));

30.10.27.4.4 path concatenation [fs.path.concat]

path& operator+=(const path& x); path& operator+=(const string_type& x); path& operator+=(basic_string_view<value_type> x); path& operator+=(const value_type* x); path& operator+=(value_type x); template <class Source> path& operator+=(const Source& x); template <class EcharT> path& operator+=(EcharT x); template <class Source> path& concat(const Source& x);

Effects: Добавляется path(x).native() к имени пути в собственном формате. [ Note: Это напрямую влияет на значение native() и может не переноситься между операционными системами. ]end note

Returns: *this.

template <class InputIterator> path& concat(InputIterator first, InputIterator last);

Effects: Эквивалентно return *this += path(first, last).

30.10.27.4.5 path modifiers [fs.path.modifiers]

void clear() noexcept;

Postconditions: empty() == true.

path& make_preferred();

Effects: Каждый directory-separator путь в общем формате преобразуется в preferred-separator.

Returns: *this.

[Example:

path p("foo/bar");
std::cout << p << '\n';
p.make_preferred();
std::cout << p << '\n';

В операционной системе, где preferred-separatorстоит косая черта, вывод будет следующим:

"foo/bar"
"foo/bar"

В операционной системе, где preferred-separatorиспользуется обратная косая черта, вывод будет следующим:

"foo/bar"
"foo\bar"

end example]

path& remove_filename();

Postconditions: !has_­filename().

Effects: Удалите путь filename() к общему формату из пути к общему формату.

Returns: *this.

[Example:

path("foo/bar").remove_filename(); // yields "foo/"
path("foo/").remove_filename();    // yields "foo/"
path("/foo").remove_filename();    // yields "/"
path("/").remove_filename();       // yields "/"

end example]

path& replace_filename(const path& replacement);

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

remove_filename();
operator/=(replacement);

Returns: *this.

[Example:

path("/foo").replace_filename("bar");  // yields "/bar" on POSIX
path("/").replace_filename("bar");     // yields "/bar" on POSIX

end example]

path& replace_extension(const path& replacement = path());

Effects:

  • Все существующие extension()([fs.path.decompose]) удаляются из пути в общем формате, затем

  • Если replacement не пусто и не начинается с точки, точка добавляется к имени пути в общем формате, затем

  • operator+=(replacement);.

Returns: *this.

void swap(path& rhs) noexcept;

Effects: Меняет местами содержимое (во всех форматах) двух путей.

Complexity: Постоянное время.

30.10.27.4.6 path native format observers [fs.path.native.obs]

Строка, возвращаемая всеми наблюдателями в собственном формате, находится в формате native pathname format.

const string_type& native() const noexcept;

Returns: Путь в собственном формате.

const value_type* c_str() const noexcept;

Returns: Эквивалентно native().c_­str().

operator string_type() const;

Returns: native().

[ Note: Преобразование в string_­type предусмотрено для того, чтобы объект класса path можно было передать в качестве аргумента существующим конструкторам файловых потоков стандартной библиотеки и открытым функциям. ] end note

template <class EcharT, class traits = char_traits<EcharT>, class Allocator = allocator<EcharT>> basic_string<EcharT, traits, Allocator> string(const Allocator& a = Allocator()) const;

Returns: native().

Remarks: Все выделение памяти, в том числе для возвращаемого значения, должно выполняться a. Преобразование, если оно есть, определяется [fs.path.cvt].

std::string string() const; std::wstring wstring() const; std::string u8string() const; std::u16string u16string() const; std::u32string u32string() const;

Returns: pathstring.

Remarks: Преобразование, если оно есть, выполняется в соответствии с указаниями [fs.path.cvt]. Кодировка строки, возвращаемой u8string() функцией, всегда UTF-8.

30.10.27.4.7 path generic format observers [fs.path.generic.obs]

Функции наблюдателя общего формата возвращают строки, отформатированные в соответствии с форматом generic pathname format. Одиночный '/'символ косой черты ( ) используется как directory-separator.

[ Example: В операционной системе, в которой используется обратная косая черта preferred-separator,

path("foo\\bar").generic_string()

возвращается "foo/bar". ] end example

template <class EcharT, class traits = char_traits<EcharT>, class Allocator = allocator<EcharT>> basic_string<EcharT, traits, Allocator> generic_string(const Allocator& a = Allocator()) const;

Returns: Путь в общем формате.

Remarks: Все выделение памяти, в том числе для возвращаемого значения, должно выполняться a. Преобразование, если оно есть, определяется [fs.path.cvt].

std::string generic_string() const; std::wstring generic_wstring() const; std::string generic_u8string() const; std::u16string generic_u16string() const; std::u32string generic_u32string() const;

Returns: Путь в общем формате.

Remarks: Преобразование, если оно есть, определяется [fs.path.cvt]. Кодировка строки, возвращаемой generic_­u8string() функцией, всегда UTF-8.

30.10.27.4.8 path compare [fs.path.compare]

int compare(const path& p) const noexcept;

Returns:

  • Значение меньше 0, если native() для элементов *this лексикографически меньше, чем native() для элементов p; иначе,

  • значение больше 0, если native() для элементов *this лексикографически больше, чем native() для элементов p; иначе,

  • 0.

Remarks: Элементы определяются как бы итерацией в полуоткрытом диапазоне [begin(), end()) для *this и p.

int compare(const string_type& s) const int compare(basic_string_view<value_type> s) const;

Returns: compare(path(s)).

int compare(const value_type* s) const

Returns: compare(path(s)).

30.10.27.4.9 path decomposition [fs.path.decompose]

path root_name() const;

Returns: root-name, если путь в универсальном формате включает root-name, в противном случае path().

path root_directory() const;

Returns: root-directory, если путь в универсальном формате включает root-directory, в противном случае path().

path root_path() const;

Returns: root_­name() / root_­directory().

path relative_path() const;

Returns: path Состоят из имени пути в общем формате, если !empty(), начиная с первым filenameAFTER root-path. В противном случае path().

path parent_path() const;

Returns: *this если !has_­relative_­path(), в противном случае путь, имя пути общего формата которого является самым длинным префиксом имени пути общего формата, *this который производит на один элемент меньше в своей итерации.

path filename() const;

Returns: relative_­path().empty() ? path() : *--end().

[Example:

path("/foo/bar.txt").filename();   // yields "bar.txt"
path("/foo/bar").filename();       // yields "bar"
path("/foo/bar/").filename();      // yields ""
path("/").filename();              // yields ""
path("//host").filename();         // yields ""
path(".").filename();              // yields "."
path("..").filename();             // yields ".."

end example]

path stem() const;

Returns: Позвольте f быть общим путем в формате filename(). Возвращает путь, имя которого в общем формате:

  • f, если он не содержит периодов, кроме начального периода, или состоит только из одного или двух периодов;

  • в противном случае - префикс f окончания перед последним периодом.

[Example:

std::cout << path("/foo/bar.txt").stem(); // outputs "bar"
path p = "foo.bar.baz.tar";
for (; !p.extension().empty(); p = p.stem())
  std::cout << p.extension() << '\n';
  // outputs: .tar
  //          .baz
  //          .bar

end example]

path extension() const;

Returns: путь, имя пути которого в общем формате является суффиксом, filename() не включенным в stem().

[Example:

path("/foo/bar.txt").extension();  // yields ".txt" and stem() is "bar"
path("/foo/bar").extension();      // yields "" and stem() is "bar"
path("/foo/.profile").extension(); // yields "" and stem() is ".profile"
path(".bar").extension();          // yields "" and stem() is ".bar"
path("..bar").extension();         // yields ".bar" and stem() is "."

end example]

[ Note: Точка включена в возвращаемое значение, чтобы можно было отличить отсутствие расширения от пустого расширения. ]end note

[ Note: В операционных системах, отличных от POSIX, для пути pэто может быть не так p.stem() + p.extension() == p.filename(), даже если имена путей общего формата совпадают. ] end note

30.10.27.4.10 path query [fs.path.query]

bool empty() const noexcept;

Returns: true если путь в общем формате пуст, иначе false.

bool has_root_path() const;

Returns: !root_­path().empty().

bool has_root_name() const;

Returns: !root_­name().empty().

bool has_root_directory() const;

Returns: !root_­directory().empty().

bool has_relative_path() const;

Returns: !relative_­path().empty().

bool has_parent_path() const;

Returns: !parent_­path().empty().

bool has_filename() const;

Returns: !filename().empty().

bool has_stem() const;

Returns: !stem().empty().

bool has_extension() const;

Returns: !extension().empty().

bool is_absolute() const;

Returns: true если путь в собственном формате содержит absolute path, иначе false.

[ Example: path("/").is_­absolute() предназначен true для операционных систем false на базе POSIX и для операционных систем на базе Windows. ] end example

bool is_relative() const;

Returns: !is_­absolute().

30.10.27.4.11 path generation [fs.path.gen]

path lexically_normal() const;

Returns: Путь, имя которого в универсальном формате normal form совпадает с именем пути в универсальном формате *this.

[Example:

assert(path("foo/./bar/..").lexically_normal() == "foo/");
assert(path("foo/.///bar/../").lexically_normal() == "foo/");

Вышеупомянутые утверждения будут успешными. В Windows directory-separatorсимволы возвращаемого пути будут обратной косой чертой, а не косой чертой, но это не влияет на path равенство. ] end example

path lexically_relative(const path& base) const;

Returns: *this сделано относительно base. Нет resolve символических ссылок. Не первое normalize *this или base.

Effects: Если root_­name() != base.root_­name() есть true или is_­absolute() != base.is_­absolute() есть true или !has_­root_­directory() && base.has_­root_­directory() есть true, возвращается path(). Определяет первый несовпадающий элемент *this и base как будто по:

auto [a, b] = mismatch(begin(), end(), base.begin(), base.end());

Потом,

  • если a == end() и b == base.end(), возвращается path("."); иначе

  • пусть n будет количество filenameэлементов [b, base.end()) , которых нет, dot или dot-dot минус количество, которые есть dot-dot. Если n<0, возвращается path(); иначе

  • возвращает объект класса path , созданный по умолчанию, за которым следует

    • приложение operator/=(path("..")) n времен, а затем

    • применение operator/= для каждого элемента в [a, end()).

[Example:

assert(path("/a/d").lexically_relative("/a/b/c") == "../../d");
assert(path("/a/b/c").lexically_relative("/a/d") == "../b/c");
assert(path("a/b/c").lexically_relative("a") == "b/c");
assert(path("a/b/c").lexically_relative("a/b/c/x/y") == "../..");
assert(path("a/b/c").lexically_relative("a/b/c") == ".");
assert(path("a/b").lexically_relative("c/d") == "../../a/b");

Вышеупомянутые утверждения будут успешными. В Windows directory-separatorсимволы возвращаемого пути будут обратной косой чертой, а не косой чертой, но это не влияет на path равенство. ]end example

[ Note: Если требуется символическая ссылка, следующая за семантикой, используйте операционную функцию relative(). ] end note

[ Note: Если normalization необходимо , чтобы обеспечить последовательное согласование элементов, применяются lexically_­normal() к *this, baseили обоих. ] end note

path lexically_proximate(const path& base) const;

Returns: Если значение lexically_­relative(base) не является пустым путем, верните его. В противном случае вернитесь *this.

[ Note: Если требуется символическая ссылка, следующая за семантикой, используйте операционную функцию proximate(). ] end note

[ Note: Если normalization необходимо , чтобы обеспечить последовательное согласование элементов, применяются lexically_­normal() к *this, baseили обоих. ] end note

30.10.27.5 path iterators [fs.path.itr]

Итераторы пути перебирают элементы имени пути в generic format.

A path​::​iterator - это постоянный итератор, удовлетворяющий всем требованиям a, bidirectional iterator за исключением того, что для разыменяемых итераторов a и b типа path​::​iterator with a == bнет требований, чтобы *a и *b были привязаны к одному и тому же объекту. Его value_­type это path.

Вызов любой неконстантной функции-члена path объекта делает недействительными все итераторы, ссылающиеся на элементы этого объекта.

Для элементов имени пути в универсальном формате порядок прямого обхода следующий:

  • root-nameЭлемент, если он присутствует.

  • root-directoryЭлемент, если он присутствует. [ Note: Общий формат необходим для правильной работы лексикографического сравнения. ] end note

  • Каждый последующий filenameэлемент, если присутствует.

  • Пустой элемент, если присутствует конечный некорневой элемент directory-separator .

Порядок обратного обхода обратен прямому обходу.

iterator begin() const;

Returns: Итератор для первого присутствующего элемента в списке обхода выше. Если элементы отсутствуют, конечный итератор.

iterator end() const;

Returns: Конечный итератор.

30.10.27.6 path non-member functions [fs.path.nonmember]

void swap(path& lhs, path& rhs) noexcept;

Effects: Эквивалентен: lhs.swap(rhs);

size_t hash_value (const path& p) noexcept;

Returns: Хэш-значение для пути p. Если по двум путям, p1 == p2 то hash_­value(p1) == hash_­value(p2).

bool operator< (const path& lhs, const path& rhs) noexcept;

Returns: lhs.compare(rhs) < 0.

bool operator<=(const path& lhs, const path& rhs) noexcept;

Returns: !(rhs < lhs).

bool operator> (const path& lhs, const path& rhs) noexcept;

Returns: rhs < lhs.

bool operator>=(const path& lhs, const path& rhs) noexcept;

Returns: !(lhs < rhs).

bool operator==(const path& lhs, const path& rhs) noexcept;

Returns: !(lhs < rhs) && !(rhs < lhs).

[ Note: Равенство путей и эквивалентность путей имеют разную семантику.

  • Равенство определяется тем, кто path не является членом operator==, который рассматривает только лексические представления двух путей. [ Example: path("foo") == "bar" никогда не бывает true. ] end example

  • Эквивалентность определяется equivalent() функцией, не являющейся членом, которая определяет, есть ли два пути resolve к одному и тому же объекту файловой системы. [ Example: equivalent("foo", "bar") будет, true когда оба пути разрешатся в один и тот же файл. ] end example

Программисты, желающие определить, являются ли два пути «одинаковыми», должны решить, означает ли «одинаковый» «одно и то же представление» или «разрешить один и тот же фактический файл», и выбрать соответствующую функцию соответственно. ] end note

bool operator!=(const path& lhs, const path& rhs) noexcept;

Returns: !(lhs == rhs).

path operator/ (const path& lhs, const path& rhs);

Effects: Эквивалентен: return path(lhs) /= rhs;

30.10.27.6.1 path inserter and extractor [fs.path.io]

template <class charT, class traits> basic_ostream<charT, traits>& operator<<(basic_ostream<charT, traits>& os, const path& p);

Effects: Эквивалент: os << quoted(p.string<charT, traits>()); [ функция описана в . ]Note: quoted [quoted.manip] end note

Returns: os.

template <class charT, class traits> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, path& p);

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

basic_string<charT, traits> tmp;
is >> quoted(tmp);
p = tmp;

Returns: is.

30.10.27.6.2 path factory functions [fs.path.factory]

template <class Source> path u8path(const Source& source); template <class InputIterator> path u8path(InputIterator first, InputIterator last);

Requires: Последовательности source и [first, last) кодируются в кодировке UTF-8. Тип значения Source и InputIterator есть char.

Returns:

  • Если value_­type есть, char а текущий native narrow encoding - UTF-8, вернуть path(source) или path(first, last); иначе,

  • если value_­type есть, wchar_­t а собственная широкая кодировка - UTF-16, или если value_­type есть, char16_­t или char32_­t, преобразовать source или [first, last) во временное, tmpтипа string_­type и возврата path(tmp); иначе,

  • преобразовать source или [first, last) во временное, tmpтипа u32string и возврата path(tmp).

Remarks: Argument format conversion применяется к аргументам этих функций. Как выполняется преобразование кодировки Unicode, не указано.

[ Example: Строка должна быть прочитана из базы данных, закодированной в UTF-8, и использована для создания каталога с использованием собственной кодировки для имен файлов:

namespace fs = std::filesystem;
std::string utf8_string = read_utf8_data();
fs::create_directory(fs::u8path(utf8_string));

Для операционных систем на основе POSIX с собственной узкой кодировкой, установленной на UTF-8, кодирование или преобразование типов не происходит.

Для операционных систем на основе POSIX, в которых для собственной узкой кодировки не задано значение UTF-8, происходит преобразование в UTF-32, за которым следует преобразование в текущую собственную узкую кодировку. Некоторые символы Unicode могут не иметь собственного представления набора символов.

Для операционных систем на базе Windows происходит преобразование из UTF-8 в UTF-16. ] end example

30.10.28 Class filesystem_­error [fs.class.filesystem_error]

namespace std::filesystem {
  class filesystem_error : public system_error {
  public:
    filesystem_error(const string& what_arg, error_code ec);
    filesystem_error(const string& what_arg,
                     const path& p1, error_code ec);
    filesystem_error(const string& what_arg,
                     const path& p1, const path& p2, error_code ec);

    const path& path1() const noexcept;
    const path& path2() const noexcept;
    const char* what() const noexcept override;
  };
}

Класс filesystem_­error определяет тип объектов, создаваемых как исключения для сообщения об ошибках файловой системы из функций, описанных в этом подпункте.

30.10.28.1 filesystem_­error members [filesystem_error.members]

Предоставляются конструкторы, которые хранят ноль, один или два пути, связанных с ошибкой.

filesystem_error(const string& what_arg, error_code ec);

Postconditions: Постусловия этой функции указаны в таблице 119.

Таблица 119 - filesystem_­error(const string&, error_­code) эффекты
ВыражениеЦенить
runtime_­error​::​what() what_­arg.c_­str()
code() ec
path1().empty() true
path2().empty() true

filesystem_error(const string& what_arg, const path& p1, error_code ec);

Postconditions: Постусловия этой функции указаны в таблице 120.

Таблица 120 - filesystem_­error(const string&, const path&, error_­code) эффекты
ВыражениеЦенить
runtime_­error​::​what() what_­arg.c_­str()
code() ec
path1() Ссылка на сохраненную копию p1
path2().empty() true

filesystem_error(const string& what_arg, const path& p1, const path& p2, error_code ec);

Postconditions: Постусловия этой функции указаны в таблице 121.

Таблица 121 - filesystem_­error(const string&, const path&, const path&, error_­code) эффекты
ВыражениеЦенить
runtime_­error​::​what() what_­arg.c_­str()
code() ec
path1() Ссылка на сохраненную копию p1
path2() Ссылка на сохраненную копию p2

const path& path1() const noexcept;

Returns: Ссылка на копию, p1 сохраненную конструктором, или, если ее нет, на пустой путь.

const path& path2() const noexcept;

Returns: Ссылка на копию, p2 сохраненную конструктором, или, если ее нет, на пустой путь.

const char* what() const noexcept override;

Returns: Строка, содержащая runtime_­error​::​what(). Точный формат не указан. Реализации приветствуются, но не обязаны включать в возвращаемую строку, path1.native_­string() если она не пуста, path2.native_­string() если не пуста, и system_­error​::​what() строки.

30.10.29 Enumerations [fs.enum]

30.10.29.1 Enum path​::​format [fs.enum.path.format]

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

Таблица 122 - Enum path​::​format
ИмяИмея в виду
native_­format Собственный формат имени пути.
generic_­format Общий формат имени пути.
auto_­format Интерпретация формата символьной последовательности определяется реализацией. Реализация может проверять содержимое последовательности символов, чтобы определить формат. [ Note: Для систем на основе POSIX собственный и общий форматы эквивалентны, и последовательность символов всегда должна интерпретироваться одинаково. ] end note

30.10.29.2 Enum class file_­type [fs.enum.file_type]

Этот класс перечисления определяет константы, используемые для идентификации типов файлов, со значениями, перечисленными в Табл 123.

Таблица 123 - класс Enum file_­type
ПостоянныйИмея в виду
none Тип файла не определен или произошла ошибка при попытке определить тип.
not_­found Псевдотип, указывающий, что файл не найден. [Если Note: файл не найден, это не считается ошибкой при определении типа файла. ] end note
regular Обычный файл
directory Каталог файлов
symlink Файл символьной ссылки
block Заблокировать специальный файл
character Специальный файл символов
fifo FIFO или файл трубы
socket Файл сокета
implementation-defined Реализации, которые поддерживают файловые системы, имеющие типы файлов в дополнение к вышеуказанным file_­type типам, должны предоставлять константы, определяемые реализацией, file_­type для отдельной идентификации каждого из этих дополнительных типов файлов.
unknown Файл существует, но тип не может быть определен

30.10.29.3 Enum class copy_­options [fs.enum.copy.opts]

enum class Тип copy_­options представляет собой тип битовой маски ( [bitmask.types]) , который определяет битовую маску константа используется для управления семантикой операций копирования. Константы указываются в группах опций со значениями, указанными в таблице 124. Константа none отображается в каждой группе опций с целью демонстрации; реализации должны предоставлять только одно определение.

Таблица 124 - класс Enum copy_­options
Группа опций, управляющая copy_­file эффектами функций для существующих целевых файлов
ПостоянныйИмея в виду
none (По умолчанию) Ошибка; Файл уже существует.
skip_­existing Не перезаписывать существующий файл, не сообщать об ошибке.
overwrite_­existing Перезаписать существующий файл.
update_­existing Замените существующий файл, если он старше заменяемого.
Группа опций, управляющая copy эффектами функций для подкаталогов
ПостоянныйИмея в виду
none (По умолчанию) Не копировать подкаталоги.
recursive Рекурсивно копируйте подкаталоги и их содержимое.
Группа опций, управляющая copy эффектами функций для символьных ссылок
ПостоянныйИмея в виду
none (По умолчанию) Переход по символическим ссылкам.
copy_­symlinks Копируйте символические ссылки как символические ссылки, а не копируйте файлы, на которые они указывают.
skip_­symlinks Игнорируйте символические ссылки.
Группа опций, управляющая copy эффектами функций для выбора формы копирования
ПостоянныйИмея в виду
none (По умолчанию) Копировать содержимое.
directories_­only Копировать только структуру каталогов, не копировать файлы, не являющиеся каталогами.
create_­symlinks Делайте символические ссылки вместо копий файлов. Исходный путь должен быть абсолютным, если путь назначения не находится в текущем каталоге.
create_­hard_­links Делайте жесткие ссылки вместо копий файлов.

30.10.29.4 Enum class perms [fs.enum.perms]

enum class Типа perms является , bitmask type что указывает Bitmask константы используются для идентификации прав доступа к файлам, со значениями , перечисленными в табл 125.

Таблица 125 - класс Enum perms
ИмяЦенитьPOSIXОпределение или примечания
(восьмеричный)макрос
none 0 Для файла не установлены разрешения.
owner_­read 0400 S_­IRUSR Разрешение на чтение, владелец
owner_­write 0200 S_­IWUSR Разрешение на запись, владелец
owner_­exec 0100 S_­IXUSR Разрешение на выполнение / поиск, владелец
owner_­all 0700 S_­IRWXU Читать, писать, выполнять / искать по владельцу;
owner_­read | owner_­write | owner_­exec
group_­read 040 S_­IRGRP Разрешение на чтение, группа
group_­write 020 S_­IWGRP Разрешение на запись, группа
group_­exec 010 S_­IXGRP Разрешение на выполнение / поиск, группа
group_­all 070 S_­IRWXG Чтение, запись, выполнение / поиск по группе;
group_­read | group_­write | group_­exec
others_­read 04 S_­IROTH Разрешение на чтение, другие
others_­write 02 S_­IWOTH Разрешение на запись, другие
others_­exec 01 S_­IXOTH Разрешение на выполнение / поиск, другие
others_­all 07 S_­IRWXO Читать, писать, выполнять / искать другие;
others_­read | others_­write | others_­exec
all 0777 owner_­all | group_­all | others_­all
set_­uid 04000 S_­ISUID Установить идентификатор пользователя при выполнении
set_­gid 02000 S_­ISGID Установить идентификатор группы при выполнении
sticky_­bit 01000 S_­ISVTX Зависит от операционной системы.
mask 07777 all | set_­uid | set_­gid | sticky_­bit
unknown 0xFFFF Разрешения неизвестны, например, когда file_­status объект создается без указания разрешений.

30.10.29.5 Enum class perm_­options [fs.enum.perm.opts]

enum class Тип perm_­options представляет собой тип битовой маски ( [bitmask.types]) , который определяет битовую маску константа используется для управления семантикой операций разрешений, со значениями , перечисленных в табле 126. Константы битовой маски являются элементами битовой маски. В таблице 126 perm обозначает значение perms переданного типа permissions.

Таблица 126 - класс Enum perm_­options
ИмяИмея в виду
replace permissions должен заменить биты разрешений файла на perm
add permissions должен заменить биты разрешения файла побитовым ИЛИ perm и текущими битами разрешения файла.
remove permissions должен заменить биты разрешений файла побитовым И дополнением perm и текущими битами разрешений файла.
nofollow permissions должен изменять разрешения самой символической ссылки, а не разрешения файла, к которому эта ссылка разрешает.

30.10.29.6 Enum class directory_­options [fs.enum.dir.opts]

enum class Тип directory_­options представляет собой тип битовая ( [bitmask.types]), задающий Bitmask константы используются для определения вариантов обхода каталога, со значениями , перечисленными в табл 127.

Таблица 127 - класс Enum directory_­options
ИмяИмея в виду
none (По умолчанию) Пропускать символические ссылки на каталог, отказано в разрешении - это ошибка.
follow_­directory_­symlink Следуйте, а не пропускайте символические ссылки на каталоги.
skip_­permission_­denied Пропускать каталоги, для которых в противном случае было бы отказано в разрешении.

30.10.30 Class file_­status [fs.class.file_status]

namespace std::filesystem {
  class file_status {
  public:
    // [fs.file_status.cons], constructors and destructor
    file_status() noexcept : file_status(file_type::none) {}
    explicit file_status(file_type ft,
                         perms prms = perms::unknown) noexcept;
    file_status(const file_status&) noexcept = default;
    file_status(file_status&&) noexcept = default;
    ~file_status();

    // assignments:
    file_status& operator=(const file_status&) noexcept = default;
    file_status& operator=(file_status&&) noexcept = default;

    // [fs.file_status.mods], modifiers
    void       type(file_type ft) noexcept;
    void       permissions(perms prms) noexcept;

    // [fs.file_status.obs], observers
    file_type  type() const noexcept;
    perms      permissions() const noexcept;
  };
}

Объект типа file_­status хранит информацию о типе и разрешениях файла.

30.10.30.1 file_­status constructors [fs.file_status.cons]

explicit file_status(file_type ft, perms prms = perms::unknown) noexcept;

Postconditions: type() == ft и permissions() == prms.

30.10.30.2 file_­status observers [fs.file_status.obs]

file_type type() const noexcept;

Returns: Значение, type() заданное постусловиями последнего вызова конструктора operator=, или type(file_­type) функции.

perms permissions() const noexcept;

Returns: Значение, permissions() заданное постусловиями последнего вызова конструктора operator=, или permissions(perms) функции.

30.10.30.3 file_­status modifiers [fs.file_status.mods]

void type(file_type ft) noexcept;

Postconditions: type() == ft.

void permissions(perms prms) noexcept;

Postconditions: permissions() == prms.

30.10.31 Class directory_­entry [fs.class.directory_entry]

namespace std::filesystem {
  class directory_entry {
  public:
    // [fs.dir.entry.cons], constructors and destructor
    directory_entry() noexcept = default;
    directory_entry(const directory_entry&) = default;
    directory_entry(directory_entry&&) noexcept = default;
    explicit directory_entry(const path& p);
    directory_entry(const path& p, error_code& ec);
    ~directory_entry();

    // assignments:
    directory_entry& operator=(const directory_entry&) = default;
    directory_entry& operator=(directory_entry&&) noexcept = default;

    // [fs.dir.entry.mods], modifiers
    void assign(const path& p);
    void assign(const path& p, error_code& ec);
    void replace_filename(const path& p);
    void replace_filename(const path& p, error_code& ec);
    void refresh();
    void refresh(error_code& ec) noexcept;

    // [fs.dir.entry.obs], observers
    const path& path() const noexcept;
    operator const path&() const noexcept;
    bool exists() const;
    bool exists(error_code& ec) const noexcept;
    bool is_block_file() const;
    bool is_block_file(error_code& ec) const noexcept;
    bool is_character_file() const;
    bool is_character_file(error_code& ec) const noexcept;
    bool is_directory() const;
    bool is_directory(error_code& ec) const noexcept;
    bool is_fifo() const;
    bool is_fifo(error_code& ec) const noexcept;
    bool is_other() const;
    bool is_other(error_code& ec) const noexcept;
    bool is_regular_file() const;
    bool is_regular_file(error_code& ec) const noexcept;
    bool is_socket() const;
    bool is_socket(error_code& ec) const noexcept;
    bool is_symlink() const;
    bool is_symlink(error_code& ec) const noexcept;
    uintmax_t file_size() const;
    uintmax_t file_size(error_code& ec) const noexcept;
    uintmax_t hard_link_count() const;
    uintmax_t hard_link_count(error_code& ec) const noexcept;
    file_time_type last_write_time() const;
    file_time_type last_write_time(error_code& ec) const noexcept;
    file_status status() const;
    file_status status(error_code& ec) const noexcept;
    file_status symlink_status() const;
    file_status symlink_status(error_code& ec) const noexcept;

    bool operator< (const directory_entry& rhs) const noexcept;
    bool operator==(const directory_entry& rhs) const noexcept;
    bool operator!=(const directory_entry& rhs) const noexcept;
    bool operator<=(const directory_entry& rhs) const noexcept;
    bool operator> (const directory_entry& rhs) const noexcept;
    bool operator>=(const directory_entry& rhs) const noexcept;

  private:
    path pathobject;                 // exposition only
    friend class directory_iterator; // exposition only
  };
}

А directory_­entry объект хранит path объект и могут хранить дополнительные объекты для атрибутов файлов , такими как жесткие ссылки, статус, SYMLINK статуса, размер файла и время последней записи.

Реализациям рекомендуется сохранять такие дополнительные атрибуты файлов во время итерации каталога, если их значения доступны, и сохранение значений позволило бы реализации исключить доступ к файловой системе со стороны directory_­entry функций наблюдателя ( [fs.op.funcs]). Такие сохраненные значения атрибутов файла называются cached.

[ Note: Для демонстрации class directory_­iterator ( [fs.class.directory_iterator]) показан выше как друг класса directory_­entry. Friendship позволяет directory_­iterator реализации кэшировать уже доступные значения атрибутов непосредственно в directory_­entry объект без затрат на ненужный вызов refresh(). ]end note

[Example:

using namespace std::filesystem;

// use possibly cached last write time to minimize disk accesses
for (auto&& x : directory_iterator("."))
{
  std::cout << x.path() << " " << x.last_write_time() << std::endl;
}

// call refresh() to refresh a stale cache
for (auto&& x : directory_iterator("."))
{
  lengthy_function(x.path());  // cache becomes stale
  x.refresh();
  std::cout << x.path() << " " << x.last_write_time() << std::endl;
}

В реализациях, которые не кэшируют время последней записи, оба цикла приведут к потенциально дорогостоящему вызову std​::​filesystem​::​last_­write_­time функции. В реализациях, которые кэшируют время последней записи, первый цикл будет использовать кешированное значение и поэтому не приведет к потенциально дорогостоящему вызову std​::​filesystem​::​last_­write_­time функции. Код переносим для любой реализации, независимо от того, использует ли он кеширование или нет. ]end example

30.10.31.1 directory_­entry constructors [fs.dir.entry.cons]

explicit directory_entry(const path& p); directory_entry(const path& p, error_code& ec);

Effects: Создает объект типа directory_­entrythen refresh() или refresh(ec)соответственно.

Postconditions: path() == p если ошибки не возникает, иначе path() == std​::​filesystem​::​path().

Throws: Как указано в [fs.err.report].

30.10.31.2 directory_­entry modifiers [fs.dir.entry.mods]

void assign(const path& p); void assign(const path& p, error_code& ec);

Effects: Эквивалентно pathobject = p, then refresh() или refresh(ec), соответственно. В случае ошибки значения любых кэшированных атрибутов не указываются.

Throws: Как указано в [fs.err.report].

void replace_filename(const path& p); void replace_filename(const path& p, error_code& ec);

Effects: Эквивалентно pathobject.replace_­filename(p), then refresh() или refresh(ec), соответственно. В случае ошибки значения любых кэшированных атрибутов не указываются.

Throws: Как указано в [fs.err.report].

void refresh(); void refresh(error_code& ec) noexcept;

Effects: Сохраняет текущие значения любых кэшированных атрибутов файла, в который p разрешается. При возникновении ошибки сообщается об ошибке ( [fs.err.report]), и значения любых кэшированных атрибутов не указываются.

Throws: Как указано в [fs.err.report].

[ Note: Реализациям directory_­iterator ( [fs.class.directory_iterator]) запрещено прямо или косвенно вызывать refresh функцию, поскольку она должна обращаться к внешней файловой системе, а цель кэширования - избежать ненужных обращений к файловой системе. ] end note

30.10.31.3 directory_­entry observers [fs.dir.entry.obs]

Неквалифицированные имена функций в Returns: элементах directory_­entry наблюдателей, описанных ниже, относятся к членам std​::​filesystem пространства имен.

const path& path() const noexcept; operator const path&() const noexcept;

Returns: pathobject.

bool exists() const; bool exists(error_code& ec) const noexcept;

Returns: exists(this->status()) или exists(this->status(), ec), соответственно.

Throws: Как указано в [fs.err.report].

bool is_block_file() const; bool is_block_file(error_code& ec) const noexcept;

Returns: is_­block_­file(this->status()) или is_­block_­file(this->status(), ec), соответственно.

Throws: Как указано в [fs.err.report].

bool is_character_file() const; bool is_character_file(error_code& ec) const noexcept;

Returns: is_­character_­file(this->status()) или is_­character_­file(this->status(), ec), соответственно.

Throws: Как указано в [fs.err.report].

bool is_directory() const; bool is_directory(error_code& ec) const noexcept;

Returns: is_­directory(this->status()) или is_­directory(this->status(), ec), соответственно.

Throws: Как указано в [fs.err.report].

bool is_fifo() const; bool is_fifo(error_code& ec) const noexcept;

Returns: is_­fifo(this->status()) или is_­fifo(this->status(), ec), соответственно.

Throws: Как указано в [fs.err.report].

bool is_other() const; bool is_other(error_code& ec) const noexcept;

Returns: is_­other(this->status()) или is_­other(this->status(), ec), соответственно.

Throws: Как указано в [fs.err.report].

bool is_regular_file() const; bool is_regular_file(error_code& ec) const noexcept;

Returns: is_­regular_­file(this->status()) или is_­regular_­file(this->status(), ec), соответственно.

Throws: Как указано в [fs.err.report].

bool is_socket() const; bool is_socket(error_code& ec) const noexcept;

Returns: is_­socket(this->status()) или is_­socket(this->status(), ec), соответственно.

Throws: Как указано в [fs.err.report].

bool is_symlink() const; bool is_symlink(error_code& ec) const noexcept;

Returns: is_­symlink(this->symlink_­status()) или is_­symlink(this->symlink_­status(), ec), соответственно.

Throws: Как указано в [fs.err.report].

uintmax_t file_size() const; uintmax_t file_size(error_code& ec) const noexcept;

Returns: Если кэшировано, значение атрибута размера файла. В противном случае file_­size(path()) или file_­size(path(), ec)соответственно.

Throws: Как указано в [fs.err.report].

uintmax_t hard_link_count() const; uintmax_t hard_link_count(error_code& ec) const noexcept;

Returns: Если кэшировано, значение атрибута количества жестких ссылок. В противном случае hard_­link_­count(path()) или hard_­link_­count(path(), ec)соответственно.

Throws: Как указано в [fs.err.report].

file_time_type last_write_time() const; file_time_type last_write_time(error_code& ec) const noexcept;

Returns: Если кэшировано, последнее значение атрибута времени записи. В противном случае last_­write_­time(path()) или last_­write_­time(path(), ec)соответственно.

Throws: Как указано в [fs.err.report].

file_status status() const; file_status status(error_code& ec) const noexcept;

Returns: Если кэшировано, значение атрибута статуса. В противном случае status(path()) или status(path(), ec)соответственно.

Throws: Как указано в [fs.err.report].

file_status symlink_status() const; file_status symlink_status(error_code& ec) const noexcept;

Returns: Если кэшировано, значение атрибута статуса символической ссылки. В противном случае symlink_­status(path()) или symlink_­status(path(), ec)соответственно.

Throws: Как указано в [fs.err.report].

bool operator==(const directory_entry& rhs) const noexcept;

Returns: pathobject == rhs.pathobject.

bool operator!=(const directory_entry& rhs) const noexcept;

Returns: pathobject != rhs.pathobject.

bool operator< (const directory_entry& rhs) const noexcept;

Returns: pathobject < rhs.pathobject.

bool operator<=(const directory_entry& rhs) const noexcept;

Returns: pathobject <= rhs.pathobject.

bool operator> (const directory_entry& rhs) const noexcept;

Returns: pathobject > rhs.pathobject.

bool operator>=(const directory_entry& rhs) const noexcept;

Returns: pathobject >= rhs.pathobject.

30.10.32 Class directory_­iterator [fs.class.directory_iterator]

Объект типа directory_­iterator предоставляет итератор для последовательности directory_­entry элементов, представляющих путь и любые кэшированные значения атрибутов ( [fs.class.directory_entry]) для каждого файла в каталоге или в определяемом реализацией типе файла, подобном каталогу. [ Note: Для перехода к подкаталогам см. Class recursive_­directory_­iterator ( [fs.class.rec.dir.itr]). ] end note

namespace std::filesystem {
  class directory_iterator {
  public:
    using iterator_category = input_iterator_tag;
    using value_type        = directory_entry;
    using difference_type   = ptrdiff_t;
    using pointer           = const directory_entry*;
    using reference         = const directory_entry&;

    // [fs.dir.itr.members], member functions
    directory_iterator() noexcept;
    explicit directory_iterator(const path& p);
    directory_iterator(const path& p, directory_options options);
    directory_iterator(const path& p, error_code& ec) noexcept;
    directory_iterator(const path& p, directory_options options,
                       error_code& ec) noexcept;
    directory_iterator(const directory_iterator& rhs);
    directory_iterator(directory_iterator&& rhs) noexcept;
    ~directory_iterator();

    directory_iterator& operator=(const directory_iterator& rhs);
    directory_iterator& operator=(directory_iterator&& rhs) noexcept;

    const directory_entry& operator*() const;
    const directory_entry* operator->() const;
    directory_iterator&    operator++();
    directory_iterator&    increment(error_code& ec) noexcept;

    // other members as required by [input.iterators], input iterators
  };
}

directory_­iterator удовлетворяет требованиям input iterator.

Если итератор типа directory_­iterator сообщает об ошибке или проходит мимо последнего элемента каталога, этот итератор должен стать равным конечному значению итератора. Конструктор по directory_­iterator умолчанию должен создать итератор, равный значению конечного итератора, и это должен быть единственный допустимый итератор для конечного условия.

Конечный итератор не может быть разыменован.

Два конечных итератора всегда равны. Конечный итератор не должен быть равен нескончаемому итератору.

Результатом вызова path() члена directory_­entry объекта, полученного путем разыменования a, directory_­iterator является ссылка на path объект, состоящий из аргумента каталога, из которого был создан итератор, с именем файла записи каталога, добавленным, как если бы operator/=.

Итерация каталога не должна приводить к появлению записей каталога для каталогов current ( dot) и parent ( dot-dot).

Порядок записей каталога, полученных путем разыменования последовательных приращений a, directory_­iterator не определен.

Конструкторы и неконстантные directory_­iterator функции - члены хранят значения любых кэшированных атрибутов ( [fs.class.directory_entry]) в directory_­entry элементе, возвращаемом operator*(). directory_­iterator функции-члены не должны прямо или косвенно вызывать какие-либо directory_­entry refresh функции. [ Note: Точный механизм хранения кэшированных значений атрибутов не предоставляется пользователям. Для directory_­iterator демонстрации класс показан [fs.class.directory_entry] как друг класса directory_­entry. ]end note

[ Note: Программы, выполняющие итерацию каталога, могут захотеть проверить, действительно ли существует путь, полученный путем разыменования итератора каталога. Это может быть символическая ссылка на несуществующий файл. Программы, рекурсивно проходящие по деревьям каталогов с целью удаления и переименования записей, могут не следовать символическим ссылкам. ]end note

[ Note: Если файл удаляется из каталога или добавляется в каталог после создания a directory_­iterator для каталога, не указано, приведет ли последующее увеличение итератора к тому, что итератор будет ссылаться на удаленную или добавленную запись каталога. См. POSIX readdir_­r. ]end note

30.10.32.1 directory_­iterator members [fs.dir.itr.members]

directory_iterator() noexcept;

Effects: Создает конечный итератор.

explicit directory_iterator(const path& p); directory_iterator(const path& p, directory_options options); directory_iterator(const path& p, error_code& ec) noexcept; directory_iterator(const path& p, directory_options options, error_code& ec) noexcept;

Effects: Для каталога, который p разрешается в, создает итератор для первого элемента в последовательности directory_­entry элементов, представляющих файлы в каталоге, если таковые имеются; в противном случае - конечный итератор. Однако если

(options & directory_options::skip_permission_denied) != directory_options::none

и конструкция обнаруживает ошибку, указывающую, что в доступе p отказано, создает конечный итератор и не сообщает об ошибке.

Throws: Как указано в [fs.err.report].

[ Note: Для перебора текущего каталога используйте directory_­iterator(".") вместо directory_­iterator(""). ] end note

directory_iterator(const directory_iterator& rhs); directory_iterator(directory_iterator&& rhs) noexcept;

Effects: Создает объект класса directory_­iterator.

Postconditions: *this имеет исходное значение rhs.

directory_iterator& operator=(const directory_iterator& rhs); directory_iterator& operator=(directory_iterator&& rhs) noexcept;

Effects: Если *this и rhs являются одним и тем же объектом, член не имеет никакого эффекта.

Postconditions: *this имеет исходное значение rhs.

Returns: *this.

directory_iterator& operator++(); directory_iterator& increment(error_code& ec) noexcept;

Effects: Как указано для операции увеличения префикса Input iterators.

Returns: *this.

Throws: Как указано в [fs.err.report].

30.10.32.2 directory_­iterator non-member functions [fs.dir.itr.nonmembers]

Эти функции обеспечивают доступ к диапазону для directory_­iterator.

directory_iterator begin(directory_iterator iter) noexcept;

Returns: iter.

directory_iterator end(const directory_iterator&) noexcept;

Returns: directory_­iterator().

30.10.33 Class recursive_­directory_­iterator [fs.class.rec.dir.itr]

Объект типа recursive_­directory_­iterator предоставляет итератор для последовательности directory_­entry элементов, представляющих файлы в каталоге или в определяемом реализацией типе файла, подобном каталогу, и его подкаталогам.

namespace std::filesystem {
  class recursive_directory_iterator {
  public:
    using iterator_category = input_iterator_tag;
    using value_type        = directory_entry;
    using difference_type   = ptrdiff_t;
    using pointer           = const directory_entry*;
    using reference         = const directory_entry&;

    // [fs.rec.dir.itr.members], constructors and destructor
    recursive_directory_iterator() noexcept;
    explicit recursive_directory_iterator(const path& p);
    recursive_directory_iterator(const path& p, directory_options options);
    recursive_directory_iterator(const path& p, directory_options options,
                                 error_code& ec) noexcept;
    recursive_directory_iterator(const path& p, error_code& ec) noexcept;
    recursive_directory_iterator(const recursive_directory_iterator& rhs);
    recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;
    ~recursive_directory_iterator();

    // [fs.rec.dir.itr.members], observers
    directory_options  options() const;
    int                depth() const;
    bool               recursion_pending() const;

    const directory_entry& operator*() const;
    const directory_entry* operator->() const;

    // [fs.rec.dir.itr.members], modifiers
    recursive_directory_iterator&
      operator=(const recursive_directory_iterator& rhs);
    recursive_directory_iterator&
      operator=(recursive_directory_iterator&& rhs) noexcept;

    recursive_directory_iterator& operator++();
    recursive_directory_iterator& increment(error_code& ec) noexcept;

    void pop();
    void pop(error_code& ec);
    void disable_recursion_pending();

    // other members as required by [input.iterators], input iterators
  };
}

Вызов options, depth, recursion_­pending, pop или disable_­recursion_­pending на итератора , который не разыменовываемое приводит к неопределенному поведению.

Поведение a recursive_­directory_­iterator такое же, как и для a, directory_­iterator если не указано иное.

[ Note: Если структура каталогов, по которой выполняется итерация, содержит циклы, то конечный итератор может быть недоступен. ] end note

30.10.33.1 recursive_­directory_­iterator members [fs.rec.dir.itr.members]

recursive_directory_iterator() noexcept;

Effects: Создает конечный итератор.

explicit recursive_directory_iterator(const path& p); recursive_directory_iterator(const path& p, directory_options options); recursive_directory_iterator(const path& p, directory_options options, error_code& ec) noexcept; recursive_directory_iterator(const path& p, error_code& ec) noexcept;

Effects: Создает итератор, представляющий первую запись в каталоге, в который p разрешается, если есть; в противном случае - конечный итератор. Однако если

(options & directory_options::skip_permission_denied) != directory_options::none

и конструкция обнаруживает ошибку, указывающую, что в доступе p отказано, создает конечный итератор и не сообщает об ошибке.

Postconditions: options() == options для подписей с directory_­options аргументом, иначе options() == directory_­options​::​none.

Throws: Как указано в [fs.err.report].

[ Note: Для перебора текущего каталога используйте recursive_­directory_­iterator(".") вместо recursive_­directory_­iterator(""). ] end note

[ Note: По умолчанию recursive_­directory_­iterator не следует символическим ссылкам на каталоги. Чтобы следовать символическим ссылкам каталога, укажите options как ] directory_­options​::​follow_­directory_­symlink end note

recursive_directory_iterator(const recursive_directory_iterator& rhs);

Effects: Создает объект класса recursive_­directory_­iterator.

Postconditions:

  • options() == rhs.options()

  • depth() == rhs.depth()

  • recursion_­pending() == rhs.recursion_­pending()

recursive_directory_iterator(recursive_directory_iterator&& rhs) noexcept;

Effects: Создает объект класса recursive_­directory_­iterator.

Postconditions: options(), depth()И recursion_­pending() имеет значение , которые rhs.options(), rhs.depth()и rhs.recursion_­pending(), соответственно, имели перед вызовом функции.

recursive_directory_iterator& operator=(const recursive_directory_iterator& rhs);

Effects: Если *this и rhs являются одним и тем же объектом, член не имеет никакого эффекта.

Postconditions:

  • options() == rhs.options()

  • depth() == rhs.depth()

  • recursion_­pending() == rhs.recursion_­pending()

Returns: *this.

recursive_directory_iterator& operator=(recursive_directory_iterator&& rhs) noexcept;

Effects: Если *this и rhs являются одним и тем же объектом, член не имеет никакого эффекта.

Postconditions: options(), depth()И recursion_­pending() имеет значение , которые rhs.options(), rhs.depth()и rhs.recursion_­pending(), соответственно, имели перед вызовом функции.

Returns: *this.

directory_options options() const;

Returns: Значение аргумента, переданного конструктору для options параметра, если он присутствует, в противном случае directory_­options​::​none.

Throws: Ничего такого.

int depth() const;

Returns: Текущая глубина просматриваемого дерева каталогов. [ Note: Начальный каталог - это глубина 0, его непосредственные подкаталоги - это глубина 1и так далее. ] end note

Throws: Ничего такого.

bool recursion_pending() const;

Returns: true if disable_­recursion_­pending() не был вызван после предыдущей операции построения или приращения, в противном случае false.

Throws: Ничего такого.

recursive_directory_iterator& operator++(); recursive_directory_iterator& increment(error_code& ec) noexcept;

Effects: Как указано для операции увеличения префикса Input iterators, за исключением того, что:

  • Если на текущей глубине больше нет записей, то если depth() != 0 итерация по родительскому каталогу возобновляется; иначе *this = recursive_­directory_­iterator().

  • В противном случае, если

    recursion_pending() && is_directory((*this)->status()) &&
    (!is_symlink((*this)->symlink_status()) ||
     (options() & directory_options::follow_directory_symlink) != directory_options::none)

    то либо каталог (*this)->path() рекурсивно перебирается, либо, если

    (options() & directory_options::skip_permission_denied) != directory_options::none

    и возникает ошибка, указывающая на то, что в разрешении на доступ к каталогу (*this)->path() отказано, тогда каталог (*this)->path() обрабатывается как пустой каталог и об ошибках не сообщается.

Returns: *this.

Throws: Как указано в [fs.err.report].

void pop(); void pop(error_code& ec);

Effects: Если depth() == 0установите *this в recursive_­directory_­iterator(). В противном случае прекратите итерацию каталога, по которому в настоящее время выполняется итерация, и продолжите итерацию по родительскому каталогу.

Throws: Как указано в [fs.err.report].

void disable_recursion_pending();

Postconditions: recursion_­pending() == false.

[ Note: disable_­recursion_­pending() используется для предотвращения нежелательной рекурсии в каталог. ] end note

30.10.33.2 recursive_­directory_­iterator non-member functions [fs.rec.dir.itr.nonmembers]

Эти функции позволяют использовать recursive_­directory_­iterator операторы for на основе диапазона.

recursive_directory_iterator begin(recursive_directory_iterator iter) noexcept;

Returns: iter.

recursive_directory_iterator end(const recursive_directory_iterator&) noexcept;

Returns: recursive_­directory_­iterator().

30.10.34 Filesystem operation functions [fs.op.funcs]

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

[ Note: Поскольку file system racesпри операциях файловой системы часто возникают сбои оборудования, сбои сети и многие другие виды ошибок, пользователи должны знать, что любая функция операции с файловой системой, независимо от того, насколько она кажется безобидной, может столкнуться с ошибкой; см [fs.err.report]. ] end note

30.10.34.1 Absolute [fs.op.absolute]

path absolute(const path& p); path absolute(const path& p, error_code& ec);

Effects: Создает абсолютный путь, ссылающийся на то же расположение файловой системы, что p и в операционной системе ( [fs.conform.os]).

Returns: Сложенный путь. Подпись с аргументом ec возвращается, path() если возникает ошибка.

[ Note: Для возвращаемого пути, rp, rp.is_­absolute() является , true если не возникает ошибка. ]end note

Throws: Как указано в [fs.err.report].

[ Note: Чтобы разрешить символические ссылки или выполнить другую очистку, которая может потребовать запросов к вторичному хранилищу, например жестким дискам, рассмотреть canonical ( [fs.op.canonical]). ]end note

[ Note: Реализациям настоятельно рекомендуется не запрашивать вторичное хранилище и не рассматривать !exists(p) ошибку. ]end note

[ Example: Для операционных систем на базе POSIX absolute(p) это просто current_­path()/p. Для операционных систем на базе Windows absolute может иметь ту же семантику, что и GetFullPathNameW. ] end example

30.10.34.2 Canonical [fs.op.canonical]

path canonical(const path& p, const path& base = current_path()); path canonical(const path& p, error_code& ec); path canonical(const path& p, const path& base, error_code& ec);

Effects: Преобразует p, который должен существовать, в абсолютный путь без символической ссылки dotили dot-dot элементов в имени пути в универсальном формате.

Returns: Путь, который относится к тому же объекту файловой системы, что и absolute(p, base). Для перегрузки без base аргумента base есть current_­path(). Подписи с аргументом ec возвращаются в path() случае ошибки.

Throws: Как указано в [fs.err.report].

Remarks: !exists(p) это ошибка.

30.10.34.3 Copy [fs.op.copy]

void copy(const path& from, const path& to);

Effects: Эквивалентно copy(from, to, copy_­options​::​none).

void copy(const path& from, const path& to, error_code& ec) noexcept;

Effects: Эквивалентно copy(from, to, copy_­options​::​none, ec).

void copy(const path& from, const path& to, copy_options options); void copy(const path& from, const path& to, copy_options options, error_code& ec) noexcept;

Requires: [fs.enum.copy.opts]Устанавливается не более одного элемента из каждой группы опций ( ) options.

Effects: Перед первым применением f и t:

  • Если

    (options & copy_options::create_symlinks) != copy_options::none ||
    (options & copy_options::skip_symlinks) != copy_options::none

    тогда auto f = symlink_­status(from) и при необходимости auto t = symlink_­status(to).

  • В противном случае, если

    (options & copy_options::copy_symlinks) != copy_options::none

    тогда auto f = symlink_­status(from) и при необходимости auto t = status(to).

  • В противном случае auto f = status(from) и при необходимости auto t = status(to).

Эффекты тогда следующие:

  • Если f.type() или t.type() является типом файла, определяемым реализацией ( [fs.enum.file_type]), то эффекты определяются реализацией.

  • В противном случае сообщается об ошибке, как указано в [fs.err.report] if:

    • !exists(f), или

    • equivalent(from, to), или

    • is_­other(f) || is_­other(t), или

    • is_­directory(f) && is_­regular_­file(t).

  • В противном случае, если is_­symlink(f), то:

    • Если (options & copy_­options​::​skip_­symlinks) != copy_­options​::​none потом вернемся.

    • В противном случае, если

      !exists(t) && (options & copy_options::copy_symlinks) != copy_options::none

      тогда copy_­symlink(from, to).

    • В противном случае сообщите об ошибке, как указано в [fs.err.report].

  • В противном случае, если is_­regular_­file(f), то:

    • Если (options & copy_­options​::​directories_­only) != copy_­options​::​none, то вернись.

    • В противном случае, если (options & copy_­options​::​create_­symlinks) != copy_­options​::​none, то создайте символическую ссылку на исходный файл.

    • В противном случае, если (options & copy_­options​::​create_­hard_­links) != copy_­options​::​none, то создайте жесткую ссылку на исходный файл.

    • Иначе если is_­directory(t), то copy_­file(from, to/from.filename(), options).

    • В противном случае copy_­file(from, to, options).

  • В противном случае, если

    is_directory(f) &&
    ((options & copy_options::recursive) != copy_options::none ||
     options == copy_options::none)

    тогда:

    • Если !exists(t), то create_­directory(to, from).

    • Затем перейдите по файлам from, как если бы

      for (const directory_entry& x : directory_iterator(from))
        copy(x.path(), to/x.path().filename(), options | copy_options::unspecified)
  • В противном случае, для подписи с аргументом ec, ec.clear().

  • В остальном никаких эффектов.

Throws: Как указано в [fs.err.report].

Remarks: Для подписи с аргументом ecлюбые библиотечные функции, вызываемые реализацией, должны иметь error_­code аргумент, если это применимо.

[ Example: Учитывая эту структуру каталогов:

/dir1
  file1
  file2
  dir2
    file3

Вызов copy("/dir1", "/dir3") приведет к:

/dir1
  file1
  file2
  dir2
    file3
/dir3
  file1
  file2

В качестве альтернативы вызов copy("/dir1", "/dir3", copy_­options​::​recursive) может привести к:

/dir1
  file1
  file2
  dir2
    file3
/dir3
  file1
  file2
  dir2
    file3

end example]

30.10.34.4 Copy file [fs.op.copy_file]

bool copy_file(const path& from, const path& to); bool copy_file(const path& from, const path& to, error_code& ec) noexcept;

Returns: copy_­file(from, to, copy_­options​::​none) или
copy_­file(from, to, copy_­options​::​none, ec), соответственно.

Throws: Как указано в [fs.err.report].

bool copy_file(const path& from, const path& to, copy_options options); bool copy_file(const path& from, const path& to, copy_options options, error_code& ec) noexcept;

Requires: [fs.enum.copy.opts]Устанавливается не более одного элемента из каждой группы опций ( ) options.

Effects: Следующее:

  • Сообщить об ошибке, что файл уже существует, [fs.err.report] если:

    • !is_­regular_­file(from), или

    • exists(to) и !is_­regular_­file(to), или

    • exists(to) и equivalent(from, to), или

    • exists(to) а также

      (options & (copy_options::skip_existing |
                  copy_options::overwrite_existing |
                  copy_options::update_existing)) == copy_options::none
  • В противном случае скопируйте содержимое и атрибуты файла, в который from разрешается, в файл, в который to разрешается, если:

    • !exists(to), или

    • (options & copy_­options​::​overwrite_­existing) != copy_­options​::​none, или

    • (options & copy_­options​::​update_­existing) != copy_­options​::​none и from является более поздним, чем toопределяется, как если бы с использованием last_­write_­time функции ( [fs.op.last_write_time]).

  • В остальном никаких эффектов.

Returns: true если from файл был скопирован, иначе false. Подпись с аргументом ec возвращается, false если возникает ошибка.

Throws: Как указано в [fs.err.report].

Complexity: Максимум один прямой или косвенный вызов status(to).

30.10.34.6 Create directories [fs.op.create_directories]

bool create_directories(const path& p); bool create_directories(const path& p, error_code& ec) noexcept;

Effects: Устанавливает постусловие, вызывая несуществующий create_­directory() элемент p .

Postconditions: is_­directory(p).

Returns: true если был создан новый каталог, иначе false. Подпись с аргументом ec возвращается, false если возникает ошибка.

Throws: Как указано в [fs.err.report].

Complexity: O(n) где n - количество элементов p , которых не существует.

30.10.34.7 Create directory [fs.op.create_directory]

bool create_directory(const path& p); bool create_directory(const path& p, error_code& ec) noexcept;

Effects: Устанавливает постусловие, пытаясь создать каталог, в который p разрешается, как если бы POSIX mkdir() со вторым аргументом static_­cast<int>(perms​::​all). Ошибка создания из- p за преобразования в существующий каталог не должна рассматриваться как ошибка.

Postconditions: is_­directory(p).

Returns: true если был создан новый каталог, иначе false. Подпись с аргументом ec возвращается, false если возникает ошибка.

Throws: Как указано в [fs.err.report].

bool create_directory(const path& p, const path& existing_p); bool create_directory(const path& p, const path& existing_p, error_code& ec) noexcept;

Effects: Устанавливает постусловие, пытаясь создать каталог, в который p разрешается, с атрибутами, скопированными из каталога existing_­p. Набор копируемых атрибутов зависит от операционной системы. Ошибка создания из- p за преобразования в существующий каталог не должна рассматриваться как ошибка. [ Note: Для операционных систем на базе POSIX это те атрибуты, которые копируются собственным API, stat(existing_­p.c_­str(), &attributes_­stat) за которыми следует mkdir(p.c_­str(), attributes_­stat.st_­mode). Для операционных систем на базе Windows атрибуты копируются собственным API CreateDirectoryExW(existing_­p.c_­str(), p.c_­str(), 0). ]end note

Postconditions: is_­directory(p).

Returns: true если был создан новый каталог, иначе false. Подпись с аргументом ec возвращается, false если возникает ошибка.

Throws: Как указано в [fs.err.report].

30.10.34.8 Create directory symlink [fs.op.create_dir_symlk]

void create_directory_symlink(const path& to, const path& new_symlink); void create_directory_symlink(const path& to, const path& new_symlink, error_code& ec) noexcept;

Effects: Устанавливает постусловие, как если бы POSIX symlink().

Postconditions: new_­symlink преобразуется в файл символьной ссылки, который содержит неопределенное представление to.

Throws: Как указано в [fs.err.report].

[ Note: Некоторые операционные системы требуют создания символической ссылки, чтобы идентифицировать ссылку на каталог. Переносимый код следует использовать create_­directory_­symlink() для создания символических ссылок на каталоги, а не ] create_­symlink() end note

[ Note: Некоторые операционные системы вообще не поддерживают символические ссылки или поддерживают их только для обычных файлов. Некоторые файловые системы (например, файловая система FAT) не поддерживают символические ссылки независимо от операционной системы. ] end note

30.10.34.9 Create hard link [fs.op.create_hard_lk]

void create_hard_link(const path& to, const path& new_hard_link); void create_hard_link(const path& to, const path& new_hard_link, error_code& ec) noexcept;

Effects: Устанавливает постусловие, как если бы POSIX link().

Postconditions:

  • exists(to) && exists(new_­hard_­link) && equivalent(to, new_­hard_­link)

  • Содержимое файла или каталога, в который to разрешается, не изменяется.

Throws: Как указано в [fs.err.report].

[ Note: Некоторые операционные системы вообще не поддерживают жесткие ссылки или поддерживают их только для обычных файлов. Некоторые файловые системы (например, файловая система FAT) не поддерживают жесткие ссылки независимо от операционной системы. Некоторые файловые системы ограничивают количество ссылок на файл. ] end note

30.10.34.11 Current path [fs.op.current_path]

path current_path(); path current_path(error_code& ec);

Returns: Абсолютный путь к текущему рабочему каталогу, имя которого в собственном формате получается, как если бы POSIX getcwd(). Подпись с аргументом ec возвращается, path() если возникает ошибка.

Throws: Как указано в [fs.err.report].

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

[ Название было выбрано , чтобы подчеркнуть , что возвращаемое значение представляет собой путь, а не только одно имя каталога. ]Note: current_­path() end note

[ Note: Текущий путь, возвращаемый многими операционными системами, является опасной глобальной переменной. Он может быть неожиданно изменен сторонними функциями, функциями системной библиотеки или другим потоком. ] end note

void current_path(const path& p); void current_path(const path& p, error_code& ec) noexcept;

Effects: Устанавливает постусловие, как если бы POSIX chdir().

Postconditions: equivalent(p, current_­path()).

Throws: Как указано в [fs.err.report].

[ Note: Текущий путь для многих операционных систем - опасное глобальное состояние. Он может быть неожиданно изменен сторонними функциями, функциями системной библиотеки или другим потоком. ] end note

30.10.34.12 Equivalent [fs.op.equivalent]

bool equivalent(const path& p1, const path& p2); bool equivalent(const path& p1, const path& p2, error_code& ec) noexcept;

Позвольте s1 и s2 быть file_­statuss, как если бы, status(p1) и status(p2), соответственно.

Effects: Определяет s1 и s2. Если (!exists(s1) && !exists(s2)) || (is_­other(s1) && is_­other(s2)) сообщается об ошибке ( [fs.err.report]).

Returns: true, если s1 == s2 и p1 и p2 разрешаются в один и тот же объект файловой системы, иначе false. Подпись с аргументом ec возвращается, false если возникает ошибка.

Считается, что два пути разрешаются к одному и тому же объекту файловой системы, если два объекта-кандидата находятся на одном устройстве в одном месте. Это определяется, как если бы, значениями stat структуры POSIX , полученными, как если бы, stat() для двух путей, имеющих равные st_­dev значения и равные st_­ino значения.

Throws: Как указано в [fs.err.report].

30.10.34.13 Exists [fs.op.exists]

bool exists(file_status s) noexcept;

Returns: status_­known(s) && s.type() != file_­type​::​not_­found.

bool exists(const path& p); bool exists(const path& p, error_code& ec) noexcept;

Позвольте s быть a file_­status, определяемым, как если бы по status(p) или status(p, ec), соответственно.

Effects: Подпись с аргументом ec вызывает ec.clear() if status_­known(s).

Returns: exists(s).

Throws: Как указано в [fs.err.report].

30.10.34.14 File size [fs.op.file_size]

uintmax_t file_size(const path& p); uintmax_t file_size(const path& p, error_code& ec) noexcept;

Returns:

  • Если !exists(p) сообщается об ошибке ( [fs.err.report]).

  • В противном случае, если is_­regular_­file(p), размер файла в байтах p преобразуется в, определяемый, как если бы, значением элемента stat структуры POSIX, st_­size полученным, как если бы POSIX stat().

  • В противном случае результат определяется реализацией.

Подпись с аргументом ec возвращается, static_­cast<uintmax_­t>(-1) если возникает ошибка.

Throws: Как указано в [fs.err.report].

30.10.34.15 Hard link count [fs.op.hard_lk_ct]

uintmax_t hard_link_count(const path& p); uintmax_t hard_link_count(const path& p, error_code& ec) noexcept;

Returns: Количество жестких ссылок для p. Подпись с аргументом ec возвращается, static_­cast<uintmax_­t>(-1) если возникает ошибка.

Throws: Как указано в [fs.err.report].

30.10.34.16 Is block file [fs.op.is_block_file]

bool is_block_file(file_status s) noexcept;

Returns: s.type() == file_­type​::​block.

bool is_block_file(const path& p); bool is_block_file(const path& p, error_code& ec) noexcept;

Returns: is_­block_­file(status(p)) или is_­block_­file(status(p, ec)), соответственно. Подпись с аргументом ec возвращается, false если возникает ошибка.

Throws: Как указано в [fs.err.report].

30.10.34.17 Is character file [fs.op.is_char_file]

bool is_character_file(file_status s) noexcept;

Returns: s.type() == file_­type​::​character.

bool is_character_file(const path& p); bool is_character_file(const path& p, error_code& ec) noexcept;

Returns: is_­character_­file(status(p)) или is_­character_­file(status(p, ec)), соответственно.
Подпись с аргументом ec возвращается, false если возникает ошибка.

Throws: Как указано в [fs.err.report].

30.10.34.18 Is directory [fs.op.is_directory]

bool is_directory(file_status s) noexcept;

Returns: s.type() == file_­type​::​directory.

bool is_directory(const path& p); bool is_directory(const path& p, error_code& ec) noexcept;

Returns: is_­directory(status(p)) или is_­directory(status(p, ec)), соответственно. Подпись с аргументом ec возвращается, false если возникает ошибка.

Throws: Как указано в [fs.err.report].

30.10.34.19 Is empty [fs.op.is_empty]

bool is_empty(const path& p); bool is_empty(const path& p, error_code& ec) noexcept;

Effects:

  • Определяем file_­status s, как будто по status(p) или status(p, ec), соответственно.

  • Для подписи с аргументом ecвернуть, false если произошла ошибка.

  • В противном случае, если is_­directory(s):

    • Создайте переменную itr, как будто по directory_­iterator itr(p) или directory_­iterator itr(p, ec), соответственно.

    • Для подписи с аргументом ecвернуть, false если произошла ошибка.

    • В противном случае верните itr == directory_­iterator().

  • Иначе:

    • Определяем uintmax_­t sz, как будто по file_­size(p) или file_­size(p, ec), соответственно.

    • Для подписи с аргументом ecвернуть, false если произошла ошибка.

    • В противном случае верните sz == 0.

Throws: Как указано в [fs.err.report].

30.10.34.20 Is fifo [fs.op.is_fifo]

bool is_fifo(file_status s) noexcept;

Returns: s.type() == file_­type​::​fifo.

bool is_fifo(const path& p); bool is_fifo(const path& p, error_code& ec) noexcept;

Returns: is_­fifo(status(p)) или is_­fifo(status(p, ec)), соответственно. Подпись с аргументом ec возвращается, false если возникает ошибка.

Throws: Как указано в [fs.err.report].

30.10.34.21 Is other [fs.op.is_other]

bool is_other(file_status s) noexcept;

Returns: exists(s) && !is_­regular_­file(s) && !is_­directory(s) && !is_­symlink(s).

bool is_other(const path& p); bool is_other(const path& p, error_code& ec) noexcept;

Returns: is_­other(status(p)) или is_­other(status(p, ec)), соответственно. Подпись с аргументом ec возвращается, false если возникает ошибка.

Throws: Как указано в [fs.err.report].

30.10.34.22 Is regular file [fs.op.is_regular_file]

bool is_regular_file(file_status s) noexcept;

Returns: s.type() == file_­type​::​regular.

bool is_regular_file(const path& p);

Returns: is_­regular_­file(status(p)).

Throws: filesystem_­error если status(p) бы бросил filesystem_­error.

bool is_regular_file(const path& p, error_code& ec) noexcept;

Effects: Устанавливает ec как бы мимо status(p, ec). [ Note: file_­type​::​none, file_­type​::​not_­found и для file_­type​::​unknown случаев установлены ec значения ошибок. Чтобы различать случаи, вызовите status функцию напрямую. ] end note

Returns: is_­regular_­file(status(p, ec)). Возвращает, false если возникает ошибка.

30.10.34.23 Is socket [fs.op.is_socket]

bool is_socket(file_status s) noexcept;

Returns: s.type() == file_­type​::​socket.

bool is_socket(const path& p); bool is_socket(const path& p, error_code& ec) noexcept;

Returns: is_­socket(status(p)) или is_­socket(status(p, ec)), соответственно. Подпись с аргументом ec возвращается, false если возникает ошибка.

Throws: Как указано в [fs.err.report].

30.10.34.25 Last write time [fs.op.last_write_time]

file_time_type last_write_time(const path& p); file_time_type last_write_time(const path& p, error_code& ec) noexcept;

Returns: Время последней модификации данных p, определяемое, как если бы, значением stat члена структуры POSIX, st_­mtime полученным, как если бы POSIX stat(). Подпись с аргументом ec возвращается, file_­time_­type​::​min() если возникает ошибка.

Throws: Как указано в [fs.err.report].

void last_write_time(const path& p, file_time_type new_time); void last_write_time(const path& p, file_time_type new_time, error_code& ec) noexcept;

Effects: Устанавливает время последнего изменения данных файла, разрешенного с помощью p to new_­time, как если бы POSIX futimens().

Throws: Как указано в [fs.err.report].

[ Note: Постусловие last_­write_­time(p) == new_­time не указано, поскольку оно может не выполняться для файловых систем с грубой детализацией по времени. ] end note

30.10.34.26 Permissions [fs.op.permissions]

void permissions(const path& p, perms prms, perm_options opts=perm_options::replace); void permissions(const path& p, perms prms, error_code& ec) noexcept; void permissions(const path& p, perms prms, perm_options opts, error_code& ec);

Requires: Именно одна из perm_­options констант replace, addили remove присутствует в opts.

Remarks: Вторая подпись ведет себя так, как если бы у нее был дополнительный параметр perm_­options opts с аргументом perm_­options​::​replace.

Effects: Применяет действие, указанное в, opts к p разрешению файла или к p самому файлу , если p это символическая ссылка и perm_­options​::​nofollow установлена ​​в opts. Действие применяется, как если бы POSIX fchmodat().

[ Note: Концептуально разрешения рассматриваются как биты, но фактическая реализация может использовать какой-то другой механизм. ] end note

Throws: Как указано в [fs.err.report].

30.10.34.27 Proximate [fs.op.proximate]

path proximate(const path& p, error_code& ec);

Returns: proximate(p, current_­path(), ec).

Throws: Как указано в [fs.err.report].

path proximate(const path& p, const path& base = current_path()); path proximate(const path& p, const path& base, error_code& ec);

Returns: Для первой формы:

weakly_canonical(p).lexically_proximate(weakly_canonical(base));

Для второй формы:

weakly_canonical(p, ec).lexically_proximate(weakly_canonical(base, ec));

или path() при первом возникновении ошибки, если таковая имеется.

Throws: Как указано в [fs.err.report].

30.10.34.29 Relative [fs.op.relative]

path relative(const path& p, error_code& ec);

Returns: relative(p, current_­path(), ec).

Throws: Как указано в [fs.err.report].

path relative(const path& p, const path& base = current_path()); path relative(const path& p, const path& base, error_code& ec);

Returns: Для первой формы:

weakly_canonical(p).lexically_relative(weakly_canonical(base));

Для второй формы:

weakly_canonical(p, ec).lexically_relative(weakly_canonical(base, ec));

или path() при первом возникновении ошибки, если таковая имеется.

Throws: Как указано в [fs.err.report].

30.10.34.30 Remove [fs.op.remove]

bool remove(const path& p); bool remove(const path& p, error_code& ec) noexcept;

Effects: Если exists(symlink_­status(p, ec)), файл p удаляется, как если бы POSIX remove(). [ Note: Символическая ссылка удаляется сама по себе, а не файл, в который она разрешается. ] end note

Postconditions: !exists(symlink_­status(p)).

Returns: false если p не существовало, иначе true. Подпись с аргументом ec возвращается, false если возникает ошибка.

Throws: Как указано в [fs.err.report].

30.10.34.31 Remove all [fs.op.remove_all]

uintmax_t remove_all(const path& p); uintmax_t remove_all(const path& p, error_code& ec) noexcept;

Effects: Рекурсивно удаляет содержимое, p если оно существует, затем удаляет p сам файл , как если бы это было POSIX remove(). [ Note: Символическая ссылка удаляется сама по себе, а не файл, в который она разрешается. ] end note

Postconditions: !exists(symlink_­status(p)).

Returns: Количество удаленных файлов. Подпись с аргументом ec возвращается, static_­cast< uintmax_­t>(-1) если возникает ошибка.

Throws: Как указано в [fs.err.report].

30.10.34.32 Rename [fs.op.rename]

void rename(const path& old_p, const path& new_p); void rename(const path& old_p, const path& new_p, error_code& ec) noexcept;

Effects: Переименовывает old_­p в new_­p, как если бы POSIX rename().

[Note:

  • Если old_­p и new_­p разрешаются в один и тот же существующий файл, никаких действий не предпринимается.

  • В противном случае переименование может включать следующие эффекты:

    • если new_­p разрешается в существующий файл, не new_­p являющийся каталогом, удаляется; иначе,

    • если new_­p разрешается в существующий каталог, new_­p удаляется, если он пуст в POSIX-совместимых операционных системах, но может быть ошибкой в ​​других операционных системах.

Сама символическая ссылка переименовывается, а не файл, в который она разрешается. ]end note

Throws: Как указано в [fs.err.report].

30.10.34.33 Resize file [fs.op.resize_file]

void resize_file(const path& p, uintmax_t new_size); void resize_file(const path& p, uintmax_t new_size, error_code& ec) noexcept;

Postconditions: file_­size(p) == new_­size.

Throws: Как указано в [fs.err.report].

Remarks: Выполняет свои постусловия, как если бы это было POSIX truncate().

30.10.34.34 Space [fs.op.space]

space_info space(const path& p); space_info space(const path& p, error_code& ec) noexcept;

Returns: Тип объекта space_­info. Значение space_­info объекта определяется как если при использовании POSIX statvfs для получения POSIX struct statvfs, а затем умножения его f_­blocks, f_­bfreeи f_­bavail членов его f_­frsize членами, и присвоения результатов к capacity, freeи available членов соответственно. Любые элементы, для которых невозможно определить значение, должны быть установлены в static_­cast<uintmax_­t>(-1). Для подписи с аргументом ecвсе члены устанавливаются в значение, static_­cast<uintmax_­t>(-1) если возникает ошибка.

Throws: Как указано в [fs.err.report].

Remarks: Значение члена space_­info​::​available зависит от операционной системы. [ Note: available может быть меньше чем free. ] end note

30.10.34.35 Status [fs.op.status]

file_status status(const path& p);

Effects: Будто:

error_code ec;
file_status result = status(p, ec);
if (result.type() == file_type::none)
  throw filesystem_error(implementation-supplied-message, p, ec);
return result;

Returns: См. Выше.

Throws: filesystem_­error. [ Note: result значения file_­status(file_­type​::​not_­found) и file_­status(file_­type​::​unknown) не считаются ошибками и не вызывают исключения. ] end note

file_status status(const path& p, error_code& ec) noexcept;

Effects: Если возможно, определяет атрибуты файла, в который p разрешается, как если бы с помощью POSIX stat() для получения POSIX struct stat. Если во время определения атрибута API базовой файловой системы сообщает об ошибке, устанавливается, ec чтобы указать конкретную сообщенную ошибку. В противном случае ec.clear(). [ Note: Это позволяет пользователям проверять особенности основных ошибок API, даже если значение, возвращаемое функцией status() , не является file_­status(file_­type​::​none). ] end note

Пусть prms обозначает результат (m & perms​::​mask), где m определяется как бы преобразованием st_­mode члена полученного struct stat в тип perms.

Returns:

  • Если ec != error_­code():

    • Если конкретная ошибка указывает, что p не может быть разрешена, потому что какой-то элемент пути не существует, возвращается file_­status(file_­type​::​not_­found).

    • В противном случае, если конкретная ошибка указывает, что она p может быть устранена, но атрибуты не могут быть определены, возвращается file_­status(file_­type​::​unknown).

    • В противном случае возвращается file_­status(file_­type​::​none).

    [ Note: Эта семантика различает то, p что известно, что не существует, p существует, но не может определить свои атрибуты, и есть ошибка, которая не позволяет даже узнать, p существует ли . Эти различия важны для некоторых случаев использования. ] end note

  • Иначе,

    • Если атрибуты указывают на обычный файл, как если бы это было POSIX S_­ISREG, возвращается file_­status(file_­type​::​regular, prms). [ Note: file_­type​::​regular подразумевает, что соответствующие <fstream> операции будут успешными, при условии отсутствия ошибок оборудования, разрешений, доступа или гонок файловой системы. Отсутствие file_­type​::​regular не обязательно означает, что <fstream> операции с каталогом завершатся ошибкой. ] end note

    • В противном случае, если атрибуты указывают каталог, как если бы это было POSIX S_­ISDIR, возвращается file_­status(file_­type​::​directory, prms). [ Note: file_­type​::​directory подразумевает, что вызов directory_­iterator(p) будет успешным. ] end note

    • В противном случае, если атрибуты указывают на блокировку специального файла, как если бы это было POSIX S_­ISBLK, возвращается file_­status(file_­type​::​block, prms).

    • В противном случае, если атрибуты указывают на символьный специальный файл, как если бы это было POSIX S_­ISCHR, возвращается file_­status(file_­type​::​character, prms).

    • В противном случае, если атрибуты указывают на файл fifo или pipe, как если бы это был POSIX S_­ISFIFO, возвращается file_­status(file_­type​::​fifo, prms).

    • В противном случае, если атрибуты указывают сокет, как если бы это было согласно POSIX S_­ISSOCK, возвращается file_­status(file_­type​::​socket, prms).

    • В противном случае, если атрибуты указывают тип файла, определенный реализацией ( [fs.enum.file_type]), возвращается file_­status(file_­type​::​A, prms), где A - константа для типа файла, определенного реализацией.

    • В противном случае возвращается file_­status(file_­type​::​unknown, prms).

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

30.10.34.36 Status known [fs.op.status_known]

bool status_known(file_status s) noexcept;

Returns: s.type() != file_­type​::​none.

30.10.34.38 Temporary directory path [fs.op.temp_dir_path]

path temp_directory_path(); path temp_directory_path(error_code& ec);

Returns: Неуказанный путь к каталогу, подходящий для временных файлов. Об ошибке должно быть сообщено, если !exists(p) || !is_­directory(p), где p - путь, который должен быть возвращен. Подпись с аргументом ec возвращается, path() если возникает ошибка.

Throws: Как указано в [fs.err.report].

[ Example: Для POSIX на основе операционных систем, реализация может вернуть путь , поставляемый по первой переменной окружения , найденной в списке TMPDIR, TMP, TEMP, TEMPDIR, или если ни один из них не будут найдены, "/tmp".

Для операционных систем на базе Windows реализация может возвращать путь, указанный GetTempPath функцией Windows API. ] end example

30.10.34.39 Weakly canonical [fs.op.weakly_canonical]

path weakly_canonical(const path& p); path weakly_canonical(const path& p, error_code& ec);

Returns: p с разрешенными символическими ссылками и результатом normalized.

Effects: Используя status(p) или status(p, ec), соответственно, для определения существования, вернуть путь, составленный operator/= из результата вызова canonical() без base аргумента и с аргументом пути, состоящим из ведущих элементов, p которые существуют, если есть, за которыми следуют элементы, p которые не существуют, если любой. Для первой формы canonical() вызывается без error_­code аргумента. Во второй форме, canonical() вызывается с ec как error_­code аргумент, и path() возвращается на первом возникновении ошибки, если таковые имеются.

Postconditions: Возвращенный путь находится в normal form.

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

Throws: Как указано в [fs.err.report].

30.11 C library files [c.files]

30.11.1 Header <cstdio> synopsis [cstdio.syn]

namespace std {
  using size_t = see [support.types.layout];
  using FILE = see below;
  using fpos_t = see below;
}

#define NULL see [support.types.nullptr]
#define _IOFBF see below
#define _IOLBF see below
#define _IONBF see below
#define BUFSIZ see below
#define EOF see below
#define FOPEN_MAX see below
#define FILENAME_MAX see below
#define L_tmpnam see below
#define SEEK_CUR see below
#define SEEK_END see below
#define SEEK_SET see below
#define TMP_MAX see below
#define stderr see below
#define stdin see below
#define stdout see below

namespace std {
  int remove(const char* filename);
  int rename(const char* old, const char* new);
  FILE* tmpfile();
  char* tmpnam(char* s);
  int fclose(FILE* stream);
  int fflush(FILE* stream);
  FILE* fopen(const char* filename, const char* mode);
  FILE* freopen(const char* filename, const char* mode, FILE* stream);
  void setbuf(FILE* stream, char* buf);
  int setvbuf(FILE* stream, char* buf, int mode, size_t size);
  int fprintf(FILE* stream, const char* format, ...);
  int fscanf(FILE* stream, const char* format, ...);
  int printf(const char* format, ...);
  int scanf(const char* format, ...);
  int snprintf(char* s, size_t n, const char* format, ...);
  int sprintf(char* s, const char* format, ...);
  int sscanf(const char* s, const char* format, ...);
  int vfprintf(FILE* stream, const char* format, va_list arg);
  int vfscanf(FILE* stream, const char* format, va_list arg);
  int vprintf(const char* format, va_list arg);
  int vscanf(const char* format, va_list arg);
  int vsnprintf(char* s, size_t n, const char* format, va_list arg);
  int vsprintf(char* s, const char* format, va_list arg);
  int vsscanf(const char* s, const char* format, va_list arg);
  int fgetc(FILE* stream);
  char* fgets(char* s, int n, FILE* stream);
  int fputc(int c, FILE* stream);
  int fputs(const char* s, FILE* stream);
  int getc(FILE* stream);
  int getchar();
  int putc(int c, FILE* stream);
  int putchar(int c);
  int puts(const char* s);
  int ungetc(int c, FILE* stream);
  size_t fread(void* ptr, size_t size, size_t nmemb, FILE* stream);
  size_t fwrite(const void* ptr, size_t size, size_t nmemb, FILE* stream);
  int fgetpos(FILE* stream, fpos_t* pos);
  int fseek(FILE* stream, long int offset, int whence);
  int fsetpos(FILE* stream, const fpos_t* pos);
  long int ftell(FILE* stream);
  void rewind(FILE* stream);
  void clearerr(FILE* stream);
  int feof(FILE* stream);
  int ferror(FILE* stream);
  void perror(const char* s);
}

Содержание и значение заголовка <cstdio> такие же , как заголовок стандартной библиотеки C <stdio.h>.

Вызов функции tmpnam с аргументом, который является значением нулевого указателя, может вызвать гонку данных ( [res.on.data.races]) с другими вызовами tmpnam с аргументом, который является значением нулевого указателя.

См. Также: ISO C 7.21.

30.11.2 Header <cinttypes> synopsis [cinttypes.syn]

#include <cstdint>  // see [cstdint.syn]

namespace std {
  using imaxdiv_t = see below;

  intmax_t imaxabs(intmax_t j);
  imaxdiv_t imaxdiv(intmax_t numer, intmax_t denom);
  intmax_t strtoimax(const char* nptr, char** endptr, int base);
  uintmax_t strtoumax(const char* nptr, char** endptr, int base);
  intmax_t wcstoimax(const wchar_t* nptr, wchar_t** endptr, int base);
  uintmax_t wcstoumax(const wchar_t* nptr, wchar_t** endptr, int base);

  intmax_t abs(intmax_t);  // optional, see below
  imaxdiv_t div(intmax_t, intmax_t);  // optional, see below
}

#define PRIdN see below
#define PRIiN see below
#define PRIoN see below
#define PRIuN see below
#define PRIxN see below
#define PRIXN see below
#define SCNdN see below
#define SCNiN see below
#define SCNoN see below
#define SCNuN see below
#define SCNxN see below
#define PRIdLEASTN see below
#define PRIiLEASTN see below
#define PRIoLEASTN see below
#define PRIuLEASTN see below
#define PRIxLEASTN see below
#define PRIXLEASTN see below
#define SCNdLEASTN see below
#define SCNiLEASTN see below
#define SCNoLEASTN see below
#define SCNuLEASTN see below
#define SCNxLEASTN see below
#define PRIdFASTN see below
#define PRIiFASTN see below
#define PRIoFASTN see below
#define PRIuFASTN see below
#define PRIxFASTN see below
#define PRIXFASTN see below
#define SCNdFASTN see below
#define SCNiFASTN see below
#define SCNoFASTN see below
#define SCNuFASTN see below
#define SCNxFASTN see below
#define PRIdMAX see below
#define PRIiMAX see below
#define PRIoMAX see below
#define PRIuMAX see below
#define PRIxMAX see below
#define PRIXMAX see below
#define SCNdMAX see below
#define SCNiMAX see below
#define SCNoMAX see below
#define SCNuMAX see below
#define SCNxMAX see below
#define PRIdPTR see below
#define PRIiPTR see below
#define PRIoPTR see below
#define PRIuPTR see below
#define PRIxPTR see below
#define PRIXPTR see below
#define SCNdPTR see below
#define SCNiPTR see below
#define SCNoPTR see below
#define SCNuPTR see below
#define SCNxPTR see below

Содержимое и значение заголовка <cinttypes> такие же, как и заголовок стандартной библиотеки C <inttypes.h>, со следующими изменениями:

  • Заголовок <cinttypes> включает заголовок <cstdint> вместо <stdint.h>, и

  • тогда и только тогда, когда тип intmax_­t обозначает an extended integer type, добавляются следующие сигнатуры функций:

    intmax_t abs(intmax_t);
    imaxdiv_t div(intmax_t, intmax_t);

    которые должны иметь ту же семантику, что и сигнатуры функций intmax_­t imaxabs(intmax_­t) и imaxdiv_­t imaxdiv(intmax_­t, intmax_­t), соответственно.

См. Также: ISO C 7.8.