STRPTIME(3)

НАЗВАНИЕ
strptime - конвертирует строчное представление времени в представление времени структуры tm

СИНТАКСИС
#define _XOPEN_SOURCE /* необходим glibc2 */
#include <time.h>

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

ОПИСАНИЕ
Функция strptime() является конвертирующей функцией, дополняющей strftime(): она конвертирует символьную строку s, в значение, хранящееся в структуре tm. На данную структуру указывает tm с помощью формата, определенного в format. В данном случае format является символьной строкой, состоящей из описателей поля и текстовых символов, напоминающей scanf(3). Каждый описатель поля состоит из символа % с последующим символом, который указывает на замену описателя поля. Все другие символы в строке format должны иметь символы, совпадающие со строкой ввода. Исключениями являются пробелы в строке форматирования, которые совпадают с любым количеством пробелов в строке ввода. Между любыми двумя описателями полей должно быть пустое место (пробелы) или другие алфавитно-цифровые символы.

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

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

%%  Символ %.

%a или %A
    День недели с использованием названий, указанных в локали. Могут быть указаны полные названия или аббревиатуры.

%b или %B или %h
    Месяц с названием, указанным в локали; могут быть указаны полные названия или аббревиатуры.

%c  Дата и время в формате %x %X (в соответствии с локалью).

%C  Номер века (0-99)

%d или %e
    День месяца (1-31; предшествующие нули можно ставить, но это необязательно).

%D  Эквивалент даты в формате %m/%d/%y (в Европе используется формат %d/%m/%y, а в ISO 8601 принято использовать %Y-%m-%d).

%H  Час (0-23).

%I  Час (1-12).

%j  Номер дня в году (1-366).

%m  Номер месяца (1-12; предшествующие нули можно ставить, но это необязательно).

%M  Минуты (0-59; предшествующие нули можно ставить, но это необязательно).

%n  Произвольные пустые места.

%p  Эквивалент AM или PM согласно локали.

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

%R  Эквивалент формата %H:%M.

%S  Секунды (0-60; предшествующие нули можно ставить, но это необязательно. Разрешена дополнительная секунда для високосных лет).

%t  Произвольные пустые места.

%T  Эквивалент формата %H:%M:%S

%U  Номер недели, где воскресенье первый день недели (0-53). Первое воскресенье января является первым днем первой недели.

%w  Номер дня недели (0-6), где воскресенье=0.

%W  Номер недели, где понедельник первый день недели (0-53). Первый понедельник января является первым днем первой недели.

%x  Дата в формате, указанном в локали

%X  Время в формате, указанном в локали

%y  Год века (0-99); Если век никак не указывается, то года 69-99 относятся к двадцатому веку (с 1969 по 1999 включительно); а года в диапазоне 00-68 относятся к двадцать первому веку (с 2000 по 2068 включительно).

%Y  Год в четырехразрядном формате (например, 1988).

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

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

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

%EC Альтернативный формат представления базового года (прим. переводчика: обычно это первые две цифры года, например, для 1972 г. базовым будет 19) в зависимости от текущей локали.

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

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

%Ey Альтернативный формат представления смещения от %EC (прим. переводчика: это год столетия, например, для 1972 г. смещение равно 72) в зависимости от текущей локали.

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

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

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

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

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

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

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

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

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

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

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

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

Структура времени с разбиением tm описана в <time.h> так:

    struct tm {
    	int	tm_sec;			/* секунды */
    	int	tm_min;			/* минуты */
    	int	tm_hour;		/* часы */
    	int	tm_mday;		/* число месяца */
    	int	tm_mon;			/* месяц */
    	int	tm_year;		/* год */
    	int	tm_wday;		/* день недели */
    	int	tm_yday;		/* число года */
    	int	tm_isdst;		/* переход на сезонное время */
    };

ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ
Возвращаемым значением функции является указатель на первый символ, не обработанный вызовом. В случае, когда строка ввода содержит больше символов, чем требуется для строки format, возвращаемое значение будет указателем на место за последним обработанным символом. В случае, когда вся строка ввода обработана, возвращается указатель на завершающий символ строки NULL. Если strptime() не может найти все соответствия в строке format и происходит ошибка, то возвращаемое значение будет равно NULL.

СООТВЕТСТВИЕ СТАНДАРТАМ
XPG4, SUSv2, POSIX 1003.1-2001.

ПРИМЕРЫ ИСПОЛЬЗОВАНИЯ
Нижеследующий пример демонстрирует использование strptime() и strftime().

#include <stdio.h>
#include <time.h>
int main() {
	struct tm tm;
	char buf[255];
	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);
	return 0;
}

РАСШИРЕНИЯ GNU
Для выполнения условий взаимозаменяемости, glibc пытается поддерживать формат символов для strptime такой же как и для strftime. Что приводит к следующему:

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

%g  Год соответствующий номеру недели по ISO, но без номера века (0-99).

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

%u  День недели в цифровом формаие (1-7, где пнд = 1).

%V  Номер недели по стандарту ISO 8601:1988 (1-53). Если неделя (начинающаяся с понедельника) содержит 1 января и имеет 4 или более дней в новом году, то это первая неделя. Иначе это последняя неделя предыдущего года, а следующая неделя первая.

%z  Спецификация временных зон по RFC-822/ISO 8601.

%Z  Название временной зоны.

Всвязи с дополнениями GNU для strftime, %k принято считать синонимом %H, а %l синонимом для %I, а %P синонимом %p.

%s  Количество секунд с начала эпохи, с 1970-01-01 00:00:00 UTC.

GNU libc не требует пустого места (пробелов) между двумя описателями полей.

ЗАМЕЧАНИЯ

В принципе, эта функция не инициализирует tm, а только сохраняет указанные значения. Это означает, что tm должна быть инициализирована до этого вызова. Существует небольшая разница между системами Unix. GNU libc не затрагивает эти области (которые точно не описаны), кроме того, что пересчитывает поля tm_wday и tm_yday, если изменился один из элементов: день, месяц или год.

Эта функция доступна в библиотеке libc с версии 4.6.8. Linux libc4 и libc5 имеют незавершенные определения прототипа; glibc2 включает в себя прототип при условии, что заданы _XOPEN_SOURCE или _GNU_SOURCE. Модификаторы E и O используются, начиная с libc 5.4.13. До libc 5.4.13 непечатаемые символы не поддерживались и спецификакция

Указатель 'y' (год столетия) указывает на год в двадцатом веке в libc4 и libc5. В glibc 2.0. указывается год в диапазоне 1950-2049. А в glibc 2.1. этот диапазон равен 1969-2068.

СМ. ТАКЖЕ
time(2), getdate(3), scanf(3), setlocale(3), strftime(3).