strptime

ИМЯ

strptime - преобразование строкового представления времени в структуру времени tm

СИНТАКСИС

#define _XOPEN_SOURCE       /* See feature_test_macros(7) */
#include <time.h>

char *strptime(const char *restrict s, const char *restrict format,
               struct tm *restrict tm);

Функция strptime() является конвертирующей функцией, дополняющей strftime(3): она преобразует символьную строку, на которую указывает s, сохраняя значения в структуре tm (описывает время в виде компонент, broken-down time) согласно формата, заданного в format.

The broken-down time structure tm is described in tm(3type).

Аргумент format является символьной строкой, состоящей из описателей поля и текстовых символов, напоминающей scanf(3). Каждый описатель поля состоит из символа % с последующим символом, который указывает на замену описателя поля. Остальные символы в строке format должны совпадать со строкой входных данных. Исключениями являются пробелы, которые совпадают с любым количеством пробелов в строке входных данных. Между любыми двумя описателями полей должно быть пустое место (пробелы) или другие алфавитно-цифровые символы.

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

Ниже приведён список поддерживаемых описателей полей. В случае поиска текстовой строки (например, день недели или месяц), сравнение происходит вне зависимости от регистра символов. В случае с цифрами допустимы начальные нули.

%%: Символ %.

%a или %A: Название дня недели согласно текущей локали, в форме аббревиатуры или полного имени.

%b, %B или %h: Название месяца согласно текущей локали, в форме аббревиатуры или полного имени.

%c: Дата и время, отображенные согласно текущей локали.

%C: The century number (0–99).

%d или %e: The day of month (1–31).

%D: Эквивалент %m/%d/%y (американское представление даты, которое может запутать не американцев, особенно с учетом того, что %d/%m/%y широко используется в Европе. Форматом ISO 8601 является %Y-%m-%d).

%H: The hour (0–23).

%I: The hour on a 12-hour clock (1–12).

%j: The day number in the year (1–366).

%m: The month number (1–12).

%M: The minute (0–59).

%n: Обязательный пробел.

%p: Локализованный эквивалент AM или PM (примечание: его может не быть).

%r: Время по 12-ти часовым часам (используя AM или PM локали). В локали POSIX это эквивалентно %I:%M:%S %p. Если t_fmt_ampm пусто в поле LC_TIME текущей локали, то поведение не определено.

%R: Эквивалент %H:%M.

%S: The second (0–60; 60 may occur for leap seconds; earlier also 61 was allowed).

%t: Обязательный пробел.

%T: Эквивалент %H:%M:%S.

%U: The week number with Sunday the first day of the week (0–53). The first Sunday of January is the first day of week 1.

%w: The ordinal number of the day of the week (0–6), with Sunday = 0.

%W: The week number with Monday the first day of the week (0–53). The first Monday of January is the first day of week 1.

%x: Дата в локализованном формате представления.

%X: Время в локализованном формате представления.

%y: The year within century (0–99). When a century is not otherwise specified, values in the range 69–99 refer to years in the twentieth century (1969–1999); values in the range 00–68 refer to years in the twenty-first century (2000–2068).

%Y: Год, включая столетие (например, 1991).

Некоторые описатели полей могут быть изменены модификаторами E или O, указывающими, что нужно использовать альтернативный формат или спецификацию. Если альтернативный формат или спецификация не существует в текущей локали, то используются неизменённые описатели полей.

Модификатор E указывает на то, что строка ввода может содержать альтернативные локале-зависимые версии представления даты и времени:

%Ec: Альтернативный формат представления даты и времени в текущей локали.

%EC: Альтернативный формат представления базового года в зависимости от текущей локали.

%Ex: Альтернативный формат представления даты в зависимости от текущей локали.

%EX: Альтернативный формат представления времени в зависимости от текущей локали.

%Ey: Альтернативный формат представления смещения от %EC в зависимости от текущей локали.

%EY: Альтернативный формат полного представления года.

Модификатор O указывает, что числовой ввод может производиться в альтернативном формате в зависимости от текущей локали:

%Od или %Oe: Число месяца с использованием альтернативных чисел локали; предшествующие нули можно ставить, но это необязательно.

%OH: Часы (0-24) с использованием альтернативных чисел локали.

%OI: Часы (1-12) с использованием альтернативных чисел локали.

%Om: Месяц с использованием альтернативных чисел локали.

%OM: Минуты с использованием альтернативных чисел локали.

%OS: Секунды с использованием альтернативных чисел локали.

%OU: Номер недели в году (воскресенье — первый день недели) с использованием альтернативных чисел локали.

%Ow: The ordinal number of the day of the week (Sunday=0), using the locale's alternative numeric symbols.

%OW: Номер недели в году (понедельник — первый день недели) с использованием альтернативных чисел локали.

%Oy: Год (смещение от %C) с использованием альтернативных чисел локали.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Возвращаемым значением функции является указатель на первый символ, не обработанный вызовом. В случае, когда строка ввода содержит больше символов, чем требуется для строки формата, возвращаемое значение будет указателем на место за последним обработанным символом. В случае, когда вся строка ввода обработана, возвращается указатель на завершающий символ строки null. Если strptime() не может найти все соответствия строке формата, то возникает ошибка и возвращается значение NULL.

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

Интерфейс	Атрибут	Значение
strptime()	Безвредность в нитях	MT-Safe env locale

СТАНДАРТЫ

POSIX.1-2001, POSIX.1-2008, SUSv2.

ЗАМЕЧАНИЯ

В принципе, эта функция не инициализирует tm, а только сохраняет указанные значения. Это означает, что tm должна быть инициализирована до этого вызова. Существует небольшая разница между системами UNIX. Функция из glibc не не изменяет поля, которые не описаны явно, за исключением пересчитываемых полей tm_wday и tm_yday, если изменился один из элементов: день, месяц или год.

The 'y' (year in century) specification is taken to specify a year in the range 1950–2049 by glibc 2.0. It is taken to be a year in 1969–2068 since glibc 2.1.

Замечания по glibc

Для симметрии glibc пытается поддерживать в strptime() тот же формат символов что и в strftime(3) (в большинстве случаев, соответствующие поля анализируются, но поле в tm не изменяется). В результате:

%F: Эквивалентно %Y-%m-%d в формате ISO 8601.

%g: The year corresponding to the ISO week number, but without the century (0–99).

%G: Год, соответствующий номеру недели по ISO (например, 1991).

%u: The day of the week as a decimal number (1–7, where Monday = 1).

%V: The ISO 8601:1988 week number as a decimal number (1–53). If the week (starting on Monday) containing 1 January has four or more days in the new year, then it is considered week 1. Otherwise, it is the last week of the previous year, and the next week is week 1.

%z: Часовой пояс согласно спецификациям стандарта RFC-822/ISO 8601.

%Z: Название часового пояса.

Аналогично, учитывая расширения GNU для strftime(3), %k принято считать синонимом %H, а %l — синонимом для %I, и %P синонимом %p. И

%s: Количество секунд с начала эпохи, с 1970-01-01 00:00:00 +0000 (UTC). Если нет поддержки для високосных секунд, то они не учитываются.

В реализации glibc не требуется пустого места (пробелов) между двумя описателями полей.

ПРИМЕРЫ

Следующий пример демонстрирует использование strptime() и strftime(3).

#define _XOPEN_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>

int
main(void)
{
    struct tm tm;
    char buf[255];

    memset(&tm, 0, sizeof(tm));
    strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm);
    strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm);
    puts(buf);
    exit(EXIT_SUCCESS);
}

СМ. ТАКЖЕ

time(2), getdate(3), scanf(3), setlocale(3), strftime(3)

ПЕРЕВОД

Русский перевод этой страницы руководства был сделан Alexander Golubev <[email protected]>, Azamat Hackimov <[email protected]>, Hotellook, Nikita <[email protected]>, Spiros Georgaras <[email protected]>, Vladislav <[email protected]>, Yuri Kozlov <[email protected]> и Иван Павлов <[email protected]>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на [email protected]

5 февраля 2023 г.

Linux man-pages 6.03