25 Localization library [localization]

25.4 Standard locale categories [locale.categories]

25.4.5 The time category [category.time]

Шаблоны time_­get<charT, InputIterator> и time_­put<charT, OutputIterator> обеспечивают форматирование и анализ даты и времени. Все спецификации функций-членов для time_­put и time_­get в подпунктах[category.time] применимы только к специализациям, требуемым в таблицах69 и70 ([locale.category]). Их члены используют их ios_­base&, ios_­base​::​iostate&и fill аргументы , как описано в[locale.categories], и ctype<> огранку, чтобы определить детали форматирования.

25.4.5.1 Class template time_­get [locale.time.get]

namespace std {
  class time_base {
  public:
    enum dateorder { no_order, dmy, mdy, ymd, ydm };
  };

  template <class charT, class InputIterator = istreambuf_iterator<charT>>
    class time_get : public locale::facet, public time_base {
    public:
      using char_type = charT;
      using iter_type = InputIterator;

      explicit time_get(size_t refs = 0);

      dateorder date_order()  const { return do_date_order(); }
      iter_type get_time(iter_type s, iter_type end, ios_base& f,
                         ios_base::iostate& err, tm* t)  const;
      iter_type get_date(iter_type s, iter_type end, ios_base& f,
                         ios_base::iostate& err, tm* t)  const;
      iter_type get_weekday(iter_type s, iter_type end, ios_base& f,
                         ios_base::iostate& err, tm* t) const;
      iter_type get_monthname(iter_type s, iter_type end, ios_base& f,
                         ios_base::iostate& err, tm* t) const;
      iter_type get_year(iter_type s, iter_type end, ios_base& f,
                         ios_base::iostate& err, tm* t) const;
      iter_type get(iter_type s, iter_type end, ios_base& f,
                         ios_base::iostate& err, tm* t, char format, char modifier = 0) const;
      iter_type get(iter_type s, iter_type end, ios_base& f,
                         ios_base::iostate& err, tm* t, const char_type* fmt,
                         const char_type* fmtend) const;

      static locale::id id;

    protected:
      ~time_get();
      virtual dateorder do_date_order()  const;
      virtual iter_type do_get_time(iter_type s, iter_type end, ios_base&,
                                    ios_base::iostate& err, tm* t) const;
      virtual iter_type do_get_date(iter_type s, iter_type end, ios_base&,
                                    ios_base::iostate& err, tm* t) const;
      virtual iter_type do_get_weekday(iter_type s, iter_type end, ios_base&,
                                       ios_base::iostate& err, tm* t) const;
      virtual iter_type do_get_monthname(iter_type s, iter_type end, ios_base&,
                                         ios_base::iostate& err, tm* t) const;
      virtual iter_type do_get_year(iter_type s, iter_type end, ios_base&,
                                    ios_base::iostate& err, tm* t) const;
      virtual iter_type do_get(iter_type s, iter_type end, ios_base& f,
                               ios_base::iostate& err, tm* t, char format, char modifier) const;
    };
}

time_­get используется для синтаксического анализа последовательности символов, извлечения компонентов времени или даты в struct tm объект. Каждый get член анализирует формат, созданный соответствующим описателем формата time_­put<>​::​put. Если анализируемая последовательность соответствует правильному формату, соответствующие члены struct tm аргумента устанавливаются в значения, используемые для создания последовательности; в противном случае либо сообщается об ошибке, либо присваиваются неопределенные значения.243

Если конечный итератор будет достигнут в процессе синтаксического анализа с помощью любого из get() функций элементов, множества членов ios_­base​::​eofbit вerr.

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

25.4.5.1.1 time_­get members [locale.time.get.members]

dateorder date_order() const;

Returns: do_­date_­order().

iter_type get_time(iter_type s, iter_type end, ios_base& str, ios_base::iostate& err, tm* t) const;

Returns: do_­get_­time(s, end, str, err, t).

iter_type get_date(iter_type s, iter_type end, ios_base& str, ios_base::iostate& err, tm* t) const;

Returns: do_­get_­date(s, end, str, err, t).

iter_type get_weekday(iter_type s, iter_type end, ios_base& str, ios_base::iostate& err, tm* t) const; iter_type get_monthname(iter_type s, iter_type end, ios_base& str, ios_base::iostate& err, tm* t) const;

Returns: do_­get_­weekday(s, end, str, err, t) или do_­get_­monthname(s, end, str, err, t).

iter_type get_year(iter_type s, iter_type end, ios_base& str, ios_base::iostate& err, tm* t) const;

Returns: do_­get_­year(s, end, str, err, t).

iter_type get(iter_type s, iter_type end, ios_base& f, ios_base::iostate& err, tm* t, char format, char modifier = 0) const;

Returns:do_­get(s, end, f, err, t, format, modifier).

iter_type get(iter_type s, iter_type end, ios_base& f, ios_base::iostate& err, tm* t, const char_type* fmt, const char_type* fmtend) const;

Requires:[fmt, fmtend) должен быть допустимым диапазоном.

Effects: Функция начинается с оценки err = ios_­base​::​goodbit. Затем он входит в цикл, считывая ноль или более символовs на каждой итерации. Если ниже не указано иное, цикл завершается, когда выполняется первое из следующих условий:

  • Выражениеfmt == fmtend оценивается какtrue.

  • Выражениеerr == ios_­base​::​goodbit оценивается какfalse.

  • Выражениеs == end оценивается какtrue, и в этом случае вычисляется функцияerr = ios_­base​::​eofbit | ios_­base​::​failbit.

  • Следующий элементfmt равен '%', необязательно за ним следует символ-модификатор, за которым следует символ-спецификатор преобразования, formatвместе формируя спецификацию преобразования, действительную для функции ISO / IEC 9945strptime. Если количество элементов в диапазоне [fmt, fmtend) недостаточно, чтобы однозначно определить, является ли спецификация преобразования полной и действительной, функция выполняет оценку err = ios_­base​::​failbit. В противном случае, функция вычисляет s = do_­get(s, end, f, err, t, format, modifier), где значениеmodifier IS ,'\0' когда дополнительный модификатор отсутствует в спецификации преобразования. Еслиerr == ios_­base​::​goodbit удерживается после вычисления выражения, функция увеличиваетсяfmt до точки сразу за концом спецификации преобразования и продолжает цикл.

  • Выражениеisspace(*fmt, f.getloc()) вычисляется доtrue, и в этом случае функция сначала увеличиваетсяfmt до тех пор, пока не будет fmt == fmtend || !isspace(*fmt, f.getloc()) вычислено значениеtrue, затем продвигается,s пока не s == end || !isspace(*s, f.getloc()) будетtrue, и, наконец, возобновит цикл.

  • Следующий считанный символs соответствует элементу, на который указываетfmt регистр при сравнении, и в этом случае функция оценивает ++fmt, ++s и продолжает цикл. В противном случае функция оценивает err = ios_­base​::​failbit.

[ Note: Функция используетctype<charT> фасет, установленный вfлокали, для определения допустимых пробельных символов. Не указано, каким образом функция выполняет сравнение без учета регистра и учитываются ли при этом многосимвольные последовательности. ]end note

Returns:s.

25.4.5.1.2 time_­get virtual functions [locale.time.get.virtuals]

dateorder do_date_order() const;

Returns: Значение перечисления, указывающее предпочтительный порядок компонентов для тех форматов даты, которые состоят из дня, месяца и года.244 Возвращает, no_­order если формат даты, заданный параметром, 'x' содержит другие переменные компоненты (например, день по юлианскому календарю, номер недели, день недели).

iter_type do_get_time(iter_type s, iter_type end, ios_base& str, ios_base::iostate& err, tm* t) const;

Effects: Читает символы, начиная с,s пока он не извлечет эти struct tm элементы, и оставшиеся символы формата, используемые time_­put<>​::​put для создания формата, указанного в "%H:%M:%S", или до тех пор, пока он не обнаружит ошибку или конец последовательности.

Returns: Итератор, указывающий сразу за последним символом, который может быть признан частью допустимого времени.

iter_type do_get_date(iter_type s, iter_type end, ios_base& str, ios_base::iostate& err, tm* t) const;

Effects: Считывает символы, начинающиеся с,s до тех пор, пока не будут извлечены эти struct tm элементы и оставшиеся символы формата, используемые time_­put<>​::​put для создания одного из следующих форматов, или пока не возникнет ошибка. Формат зависит от значения, возвращаемого,date_­order() как показано в таблице80.

Таблица80 -do_­get_­date эффекты
date_­order()Формат
no_­order "%m%d%y"
dmy "%d%m%y"
mdy "%m%d%y"
ymd "%y%m%d"
ydm "%y%d%m"

Реализация также может принимать дополнительные форматы, определяемые реализацией.

Returns: Итератор, указывающий сразу за последним символом, который может быть признан частью допустимой даты.

iter_type do_get_weekday(iter_type s, iter_type end, ios_base& str, ios_base::iostate& err, tm* t) const; iter_type do_get_monthname(iter_type s, iter_type end, ios_base& str, ios_base::iostate& err, tm* t) const;

Effects: Читает символы, начинающиеся с,s пока не будет извлечено (возможно, сокращенное) название дня недели или месяца. Если он находит сокращение, за которым следуют символы, которые могут соответствовать полному имени, он продолжает чтение, пока не совпадет с полным именем или не завершится ошибкой. Соответственно, он устанавливает соответствующий struct tm член.

Returns: Итератор, указывающий сразу за последним символом, распознанным как часть допустимого имени.

iter_type do_get_year(iter_type s, iter_type end, ios_base& str, ios_base::iostate& err, tm* t) const;

Effects: Считывает символы, начиная с,s пока не будет извлечен однозначный идентификатор года. Это определяется реализацией, принимаются ли двузначные номера года, и (если да), в каком веке они, как предполагается, лежат. Устанавливает t->tm_­year член соответствующим образом.

Returns: Итератор, указывающий сразу за последним символом, распознанным как часть допустимого идентификатора года.

iter_type do_get(iter_type s, iter_type end, ios_base& f, ios_base::iostate& err, tm* t, char format, char modifier) const;

Requires: t указывает на объект.

Effects: Функция начинается с оценки err = ios_­base​::​goodbit. Затем он считывает символы , начиная сs до тех пор, пока не обнаружит ошибку, или до тех пор, пока не добыл и назначены теstruct tm члены, и все оставшиеся символы формата, соответствующий директиве преобразования , подходящей для 9945 функции ISO / IECstrptime, формируется путем конкатенации'%', наmodifier характер, когда не NUL, иformat персонаж. Когда конкатенация не дает полной допустимой директивы, функция оставляет объект, на который указываетt без изменений, и выполняет оценкуerr |= ios_­base​::​failbit. Когдаs == end оцениваетсяtrue после чтения символа, функция оценивает err |= ios_­base​::​eofbit.

Для сложных директив преобразования , такие как%c, %x, или%X, или директив , которые включают дополнительные модификаторыE илиO, когда функция не может однозначно определить некоторые или всеstruct tm элементы из входной последовательности[s, end), он оцениваетerr |= ios_­base​::​eofbit. В таких случаях значения этихstruct tm элементов не указаны и могут выходить за пределы допустимого диапазона.

Remarks: Не указано, будут ли многократные вызовы do_­get() с адресом одного и того жеstruct tm объекта обновлять текущее содержимое объекта или просто перезаписывать его элементы. Переносимые программы должны обнулить объект перед вызовом функции.

Returns: Итератор, указывающий сразу за последним символом, который, возможно, распознается как часть допустимой входной последовательности для заданных format иmodifier.

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

25.4.5.2 Class template time_­get_­byname [locale.time.get.byname]

namespace std {
  template <class charT, class InputIterator = istreambuf_iterator<charT>>
  class time_get_byname : public time_get<charT, InputIterator> {
  public:
    using dateorder = time_base::dateorder;
    using iter_type = InputIterator;

    explicit time_get_byname(const char*, size_t refs = 0);
    explicit time_get_byname(const string&, size_t refs = 0);
  protected:
    ~time_get_byname();
  };
}

25.4.5.3 Class template time_­put [locale.time.put]

namespace std {
  template <class charT, class OutputIterator = ostreambuf_iterator<charT>>
    class time_put : public locale::facet {
    public:
      using char_type = charT;
      using iter_type = OutputIterator;

      explicit time_put(size_t refs = 0);

      // the following is implemented in terms of other member functions.
      iter_type put(iter_type s, ios_base& f, char_type fill, const tm* tmb,
                    const charT* pattern, const charT* pat_end) const;
      iter_type put(iter_type s, ios_base& f, char_type fill,
                    const tm* tmb, char format, char modifier = 0) const;

      static locale::id id;

    protected:
      ~time_put();
      virtual iter_type do_put(iter_type s, ios_base&, char_type, const tm* t,
                               char format, char modifier) const;
    };
}

25.4.5.3.1 time_­put members [locale.time.put.members]

iter_type put(iter_type s, ios_base& str, char_type fill, const tm* t, const charT* pattern, const charT* pat_end) const; iter_type put(iter_type s, ios_base& str, char_type fill, const tm* t, char format, char modifier = 0) const;

Effects: Первая форма проходит через последовательность от pattern до pat_­end, определяя символы, которые являются частью последовательности форматирования. Каждый символ, который не является частью последовательности форматирования, записывается s немедленно, и каждая последовательность форматирования, как она идентифицирована, приводит к вызову do_­put; таким образом, элементы формата и другие символы чередуются в выводе в том порядке, в котором они появляются в шаблоне. Последовательности форматов идентифицируются путем преобразования каждого символа c в char значение, как если бы ct.narrow(c, 0), где ct - ссылка, из которой нужно ctype<charT> получить str.getloc(). Первый символ каждой последовательности равен '%', за ним следует необязательный символ-модификатор и символ-спецификатор mod245 формата, spec как определено для функции strftime. Если символ-модификатор отсутствует, mod равен нулю. Для каждой идентифицированной допустимой последовательности форматов вызывается do_­put(s, str, fill, t, spec, mod).

Вторая форма вызывает do_­put(s, str, fill, t, format, modifier).

[ Аргумент может быть использован в реализации определенных форматов или дифференцирования. Разумным значением по умолчанию для этого аргумента является пробел. ]Note: fill end note

Returns: Итератор, указывающий сразу после последнего созданного символа.

Хотя язык программирования C не определяет никаких модификаторов, большинство поставщиков это делают.

25.4.5.3.2 time_­put virtual functions [locale.time.put.virtuals]

iter_type do_put(iter_type s, ios_base&, char_type fill, const tm* t, char format, char modifier) const;

Effects: Форматирует содержимое параметраt в символы, помещенные в выходную последовательностьs. Форматирование управляется параметрамиformat иmodifierинтерпретируется идентично спецификаторам формата в строковом аргументе стандартной библиотечной функции strftime()246, за исключением того, что последовательность символов, созданная для тех спецификаторов, которые описаны как зависящие от локали C, вместо этого определяется реализацией.247

Returns: Итератор, указывающий сразу после последнего созданного символа. [ Аргумент может быть использован в реализации определенных форматов или дифференцирования. Разумным значением по умолчанию для этого аргумента является пробел. ] Note: fill end note

Интерпретацияmodifier аргумента определяется реализацией, но должна соответствовать соглашениям POSIX.

Реализациям рекомендуется ссылаться на другие стандарты, такие как POSIX, для этих определений.

25.4.5.4 Class template time_­put_­byname [locale.time.put.byname]

namespace std {
  template <class charT, class OutputIterator = ostreambuf_iterator<charT>>
  class time_put_byname : public time_put<charT, OutputIterator>
  {
  public:
    using char_type = charT;
    using iter_type = OutputIterator;

    explicit time_put_byname(const char*, size_t refs = 0);
    explicit time_put_byname(const string&, size_t refs = 0);
  protected:
    ~time_put_byname();
  };
}