ИМЯ

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

LIBRARY

Standard C library (libc, -lc)

СИНТАКСИС

#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

Equivalent to %m/%d/%y. (This is the American style date, very confusing to non-Americans, especially since %d/%m/%y is widely used in Europe. The ISO 8601 standard format is %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).

СТАНДАРТЫ

POSIX.1-2008.

ИСТОРИЯ

POSIX.1-2001, 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.

ПРИМЕРЫ

Следующий пример демонстрирует использование 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 <fatzer2@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Hotellook, Nikita <zxcvbnm3230@mail.ru>, Spiros Georgaras <sng@hellug.gr>, Vladislav <ivladislavefimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику по его адресу электронной почты или по адресу списка рассылки русских переводчиков.