36.1 Утилиты для работы со временем

Основной набор функций Octave для работы со значениями времени создан по образцу соответствующих функций стандартной библиотеки C. Некоторые из этих функций используют структуру данных для хранения времени, включающую следующие элементы:

usec

Микросекунды после начала секунды (0-999999).

sec

Секунды после начала минуты (0-60). Значение может быть равно 60, чтобы учитывать високосные секунды.

min

Минуты после начала часа (0-59).

hour

Часы после полуночи (0-23).

mday

День месяца (1-31).

mon

Месяцы после января (0-11).

year

Годы после 1900.

wday

Дни после воскресенья (0-6).

yday

Дни после 1 января (0-365).

isdst

Флаг перехода на летнее время.

gmtoff

Смещение в секундах относительно UTC.

zone

Часовой пояс.

В описаниях следующих функций эта структура называется tm_struct.

: seconds = time ()

Возвращает текущее время в виде количества секунд, прошедших с начала эпохи.

Началом эпохи считается 00:00:00 UTC (всемирное координированное время) 1 января 1970 года. Например, в понедельник, 17 февраля 1997 года, в 07:15:06 UTC функция time возвращала значение 856163706.

См. также: strftime, strptime, localtime, gmtime, mktime, now, date, clock, datenum, datestr, datevec, calendar, weekday.

: t = now ()

Возвращает текущую местную дату и время в виде серийного номера дня (см. datenum).

Целая часть, floor (now), соответствует количеству дней между сегодняшним днём и 1 января 0000 года.

Дробная часть, rem (now, 1), соответствует текущему времени.

См. также: clock, date, datenum.

: str = ctime (t)

Преобразует значение, возвращённое функцией time (или любое другое неотрицательное целое число), в местное время и возвращает строку в том же формате, что и asctime.

Функция ctime (time) эквивалентна asctime (localtime (time)). Например:

ctime (time ())
   ⇒ "Mon Feb 17 01:15:06 1997\n"

См. также: asctime, time, localtime.

: tm_struct = gmtime (t)

Получив значение, возвращённое функцией time, или любое неотрицательное целое число, возвращает структуру времени, соответствующую UTC (всемирному координированному времени).

Например:

gmtime (time ())
     ⇒ {
           usec = 0
           sec = 6
           min = 15
           hour = 7
           mday = 17
           mon = 1
           year = 97
           wday = 1
           yday = 47
           isdst = 0
           gmtoff = 0
           zone = GMT
        }

См. также: strftime, strptime, localtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday.

: tm_struct = localtime (t)

Получив значение, возвращённое функцией time, или любое неотрицательное целое число, возвращает структуру времени, соответствующую местному часовому поясу.

localtime (time ())
     ⇒ {
           usec = 0
           sec = 6
           min = 15
           hour = 1
           mday = 17
           mon = 1
           year = 97
           wday = 1
           yday = 47
           isdst = 0
           gmtoff = -21600
           zone = CST
        }

См. также: strftime, strptime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday.

: seconds = mktime (tm_struct)

Преобразует структуру времени, соответствующую местному времени, в количество секунд, прошедших с начала эпохи.

Например:

mktime (localtime (time ()))
     ⇒ 856163706

См. также: strftime, strptime, localtime, gmtime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday.

: str = asctime (tm_struct)

Преобразует структуру времени в строку следующего формата: "ddd mmm mm HH:MM:SS yyyy\n".

Например:

asctime (localtime (time ()))
     ⇒ "Mon Feb 17 01:15:06 1997\n"

Это эквивалентно ctime (time ()).

См. также: ctime, localtime, time.

: str = strftime (fmt, tm_struct)

Гибко форматирует структуру времени tm_struct с помощью строки формата fmt, содержащей подстановки «%», подобные используемым в printf.

Если не указано иное, подставляемые поля имеют фиксированную длину; числовые поля при необходимости дополняются. По умолчанию дополнение выполняется нулями; для полей, отображающих одно число, способ дополнения можно изменить или отключить, добавив после «%» один из описанных ниже модификаторов. Неизвестные спецификаторы полей копируются как обычные символы. Все остальные символы копируются в выходные данные без изменений. Например:

strftime ("%r (%Z) %A %e %B %Y", localtime (time ()))
      ⇒ "01:15:06 AM (CST) Monday 17 February 1997"

Функция strftime в Octave поддерживает расширенный набор спецификаторов полей ANSI C.

Поля для буквальных символов:

%%

Символ %.

%n

Символ новой строки.

%t

Символ табуляции.

Числовые модификаторы (нестандартное расширение):

- (dash)

Не дополнять поле.

_ (underscore)

Дополнять поле пробелами.

Поля времени:

%H

Час (00-23).

%I

Час (01-12).

%k

Час (0-23).

%l

Час (1-12).

%M

Минута (00-59).

%p

Обозначение AM или PM для текущей локали.

%r

Время в 12-часовом формате (hh:mm:ss [AP]M).

%R

Время в 24-часовом формате (hh:mm).

%s

Время в секундах после 00:00:00 1 января 1970 года (нестандартное расширение).

%S

Секунда (00-61).

%T

Время в 24-часовом формате (hh:mm:ss).

%X

Представление времени для текущей локали (%H:%M:%S).

%z

Смещение относительно UTC (±hhmm) или пустая строка, если часовой пояс определить невозможно.

%Z

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

Поля даты:

%a

Сокращённое название дня недели для текущей локали (Sun-Sat).

%A

Полное название дня недели для текущей локали; длина может меняться (Sunday-Saturday).

%b

Сокращённое название месяца для текущей локали (Jan-Dec).

%B

Полное название месяца для текущей локали; длина может меняться (January-December).

%c

Дата и время для текущей локали (Sat Nov 04 12:02:33 EST 1989).

%C

Век (00-99).

%d

День месяца (01-31).

%e

День месяца ( 1-31).

%D

Дата (mm/dd/yy).

%h

То же, что %b.

%j

День года (001-366).

%m

Месяц (01-12).

%U

Номер недели в году, где неделя начинается с воскресенья (00-53).

%w

День недели (0-6).

%W

Номер недели в году, где неделя начинается с понедельника (00-53).

%x

Представление даты для текущей локали (mm/dd/yy).

%y

Последние две цифры года (00-99).

%Y

Год (1970-).

См. также: strptime, localtime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday.

: [tm_struct, nchars] = strptime (str, fmt)

Преобразует строку str в структуру времени tm_struct в соответствии со строкой формата fmt.

Если fmt не соответствует строке, значение nchars равно 0; в противном случае ему присваивается позиция последнего совпавшего символа плюс 1. Всегда проверяйте это значение, если только вы не уверены абсолютно, что строка даты будет разобрана правильно.

См. также: strftime, localtime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday.

Большинство остальных функций, описанных в этом разделе, не созданы по образцу стандартной библиотеки C. Некоторые из них доступны для совместимости с MATLAB, а другие предоставлены как полезные функции.

: datevec = clock ()

: [datevec, isdst] = clock ()

Возвращает текущие местные дату и время в виде вектора даты.

Вектор даты содержит следующие поля: текущий год, месяц (1-12), день (1-31), час (0-23), минута (0-59) и секунда (0-61). Для повышения точности поле секунд содержит дробную часть после десятичной точки.

Необязательный второй выходной аргумент isdst имеет значение true, если в часовом поясе системы действует летнее время (DST).

Например:

fix (clock ())
  ⇒   1993      8     20      4     56      1

clock точнее работает в системах, в которых имеется функция gettimeofday.

См. также: now, date, datevec.

: str = date ()

Возвращает текущую дату в виде символьной строки формата DD-MMM-YYYY.

Например:

date ()
  ⇒ 20-Aug-1993

См. также: now, clock, datestr, localtime.

: secs = etime (t2, t1)

Возвращает разницу в секундах между двумя значениями времени, полученными с помощью clock (t2 - t1).

Например:

t0 = clock ();
# many computations later...
elapsed_time = etime (clock (), t0);

присвоит переменной elapsed_time количество секунд, прошедших с момента присваивания значения переменной t0.

См. также: tic, toc, clock, cputime, addtodate.

: [total, user, system] = cputime ();

Возвращает процессорное время, использованное сеансом Octave.

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

Если система не умеет сообщать об использовании процессорного времени, cputime возвращает 0 для каждого выходного значения.

Поскольку Octave использовал некоторое процессорное время при запуске, работоспособность cputime можно проверить, убедившись, что общее использованное процессорное время ненулевое.

См. также: tic, toc.

: tf = is_leap_year ()

: tf = is_leap_year (year)

Возвращает true, если year — високосный год, и false в противном случае.

Если год не задан, is_leap_year использует текущий год.

Например:

is_leap_year (2000)
   ⇒ 1

См. также: weekday, eomday, calendar.

: tic ()

: id = tic ()

Запускает таймер реального времени.

Вызов tic без выходного аргумента сбрасывает внутренний таймер. Последующие вызовы toc возвращают количество секунд, прошедших с момента запуска таймера.

При вызове с одним выходным аргументом tic создаёт новый экземпляр таймера и возвращает его идентификатор id. id — скаляр типа uint64, который можно передать функции toc для проверки времени, прошедшего на этом таймере, а не на таймере по умолчанию.

Пример 1: измерение производительности кода с помощью внутреннего таймера

tic;
# many computations later...
elapsed_time = toc;

Пример 2: совместное использование идентификатора таймера и внутреннего таймера

tic;
pause (1);
toc
⇒ Elapsed time is 1.0089 seconds.
id = tic;
pause (2);
toc (id)
⇒ Elapsed time is 2.01142 seconds.
toc
Elapsed time is 3.02308 seconds.

Такие вызовы tic и toc позволяют выполнять вложенные замеры времени.

Если вас больше интересует процессорное время, использованное процессом, следует использовать функцию cputime. Функции tic и toc сообщают фактическое время, прошедшее между вызовами по часам реального времени. Оно может включать время, затраченное на обработку других задач, или время простоя.

См. также: toc, cputime.

: toc ()

: toc (id)

: elapsed_time = toc (…)

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

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

Если передан идентификатор id конкретного таймера, возвращает количество секунд, прошедших с момента запуска таймера id.

Примеры использования tic/toc см. в tic.

См. также: tic, cputime.

: pause ()

: pause (n)

: old_state = pause ("on")

: old_state = pause ("off")

: old_state = pause ("query")

Приостанавливает выполнение программы или изменяет состояние функции pause.

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

tic; pause (0.05); toc
     -| Elapsed time is 0.05039 seconds.

В следующем примере выводится сообщение, а затем через 5 секунд очищается экран.

disp ("wait please...");
pause (5);
clc;

Если вызвать функцию со строковым аргументом "on", "off" или "query", состояние функции pause изменяется или запрашивается. Если состояние равно "off", функция pause сразу же возвращает управление. Необязательное возвращаемое значение содержит предыдущее состояние функции pause. В следующем примере функция pause отключается локально:

old_state = pause ("off");
tic; pause (0.05); toc
     -| Elapsed time is 3.00407e-05 seconds.
pause (old_state);

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

См. также: kbhit.

: days = datenum (datevec)

: days = datenum (year, month, day)

: days = datenum (year, month, day, hour)

: days = datenum (year, month, day, hour, minute)

: days = datenum (year, month, day, hour, minute, second)

: days = datenum ("datestr")

: days = datenum ("datestr", f)

: days = datenum ("datestr", p)

: [days, secs] = datenum (…)

Возвращает дату и время в виде серийного номера дня, где 1 января 0000 года считается днём 1.

Целая часть, floor (days), подсчитывает количество полных дней во входной дате.

Дробная часть, rem (days, 1), соответствует времени в указанный день.

Входными данными может быть вектор даты (см. datevec), строка даты (см. datestr) или дата, заданная непосредственно.

При обработке входных строк даты f задаёт строку формата, используемую для интерпретации дат (см. datestr). Если формат f не указан, выполняется относительно медленный перебор различных форматов. Если форматная строка f известна, всегда предпочтительно указывать её. Компоненты времени, не заданные в формате, получают значение 0. Если дата не указана, по умолчанию используется 1 января текущего года.

При передаче отдельных аргументов year, month, day и т. д. каждый из них может быть скаляром или нескалярным массивом. Все нескалярные входные данные должны иметь одинаковый размер. Скалярные входные данные будут расширены до размера нескалярных.

p — год, с которого начинается столетие, относительно которого отсчитываются двузначные годы. Если он не указан, по умолчанию используется текущий год минус 50.

Необязательный выходной аргумент secs хранит время указанного дня с большей точностью, чем days.

Примечания:

• Годы могут быть отрицательными и/или дробными.
• Месяцы меньше 1 считаются январём.
• Нумерация дней месяца начинается с 1.
• Дни, выходящие за конец месяца, переносятся на следующие месяцы.
• Дни до начала месяца относятся к предыдущему месяцу.
• Дни могут быть дробными.

Примеры:

Convert from datestrs:
d = datenum ("1966-06-14")
⇒ d = 718232


d = datenum ({"1966-06-14", "1966-06-15", "1966-06-16"})
⇒ d =
      718232
      718233
      718234


Convert from datevec:
d = datenum ([1966 06 14])
⇒ d = 718232


d = datenum ([1966 06 14 23 59 59])
⇒ d = 718232.9999884259


Specify date components separately:
d = datenum (1966, 6, 14)
⇒ d = 718232


d = datenum (1966, magic(3), 1)
⇒ d =

      718280   718068   718219
      718127   718188   718249
      718158   718311   718099

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

Внимание: эта функция не учитывает юлианский календарь, поэтому даты до 15 октября 1582 года могут быть неверны на величину до одиннадцати дней. Кроме того, в 1582 году календарь приняли только католические страны. Повсеместно он был принят лишь к 1924 году. Дополнительные сведения см. в статье Википедии о григорианском календаре.

Предупреждение: високосные секунды не учитываются. Таблица високосных секунд приведена в соответствующей статье Википедии.

См. также: datestr, datevec, now, clock, date.

Алгоритм: Peter Baum (http://vsg.cape.com/~pbaum/date/date0.htm)

: str = datestr (date)

: str = datestr (date, f)

: str = datestr (date, f, p)

Форматирует заданную дату/время в соответствии с форматом f и возвращает результат в str.

date — это порядковый номер даты (см. datenum), вектор даты (см. datevec) или строка либо массив ячеек со строками. В последнем случае данные передаются в datevec, чтобы определить предполагаемый формат входной даты.

f может быть целым числом, соответствующим одному из кодов в таблице ниже, либо строкой формата даты.

p — это год начала столетия, к которому относятся двузначные годы. Если значение не задано, по умолчанию используется текущий год минус 50.

Например, дата 730736.65149 (2000-09-07 15:38:09.0934) будет отформатирована следующим образом:

Код	Формат	Пример
0	dd-mmm-yyyy HH:MM:SS	07-Sep-2000 15:38:09
1	dd-mmm-yyyy	07-Sep-2000
2	mm/dd/yy	09/07/00
3	mmm	Sep
4	m	S
5	mm	09
6	mm/dd	09/07
7	dd	07
8	ddd	Thu
9	d	T
10	yyyy	2000
11	yy	00
12	mmmyy	Sep00
13	HH:MM:SS	15:38:09
14	HH:MM:SS PM	3:38:09 PM
15	HH:MM	15:38
16	HH:MM PM	3:38 PM
17	QQ-YY	Q3-00
18	QQ	Q3
19	dd/mm	07/09
20	dd/mm/yy	07/09/00
21	mmm.dd,yyyy HH:MM:SS	Sep.07,2000 15:38:08
22	mmm.dd,yyyy	Sep.07,2000
23	mm/dd/yyyy	09/07/2000
24	dd/mm/yyyy	07/09/2000
25	yy/mm/dd	00/09/07
26	yyyy/mm/dd	2000/09/07
27	QQ-YYYY	Q3-2000
28	mmmyyyy	Sep2000
29	yyyy-mm-dd	2000-09-07
30	yyyymmddTHHMMSS	20000907T153808
31	yyyy-mm-dd HH:MM:SS	2000-09-07 15:38:08

Если f — строка формата, распознаются следующие символы:

Символ	Значение	Пример
yyyy	Полный год	2005
yy	Двузначный год	05
mmmm	Полное название месяца	December
mmm	Сокращенное название месяца	Dec
mm	Номер месяца в числовом формате (с ведущими нулями)	01, 08, 12
m	Первая буква названия месяца (в верхнем регистре)	D
dddd	Полное название дня недели	Sunday
ddd	Сокращенное название дня недели	Sun
dd	Число месяца (с ведущими нулями)	11
d	Первая буква названия дня недели (в верхнем регистре)	S
HH	Час дня с ведущими нулями,	09:00
	или с пробелами, если задано PM	9:00 AM
MM	Минута часа (с ведущими нулями)	10:05
SS	Секунда минуты (с ведущими нулями)	10:05:03
FFF	Миллисекунды секунды (с ведущими нулями)	10:05:03.012
AM	Использовать 12-часовой формат времени	11:30 AM
PM	Использовать 12-часовой формат времени	11:30 PM

Если f не задан или равен -1, используется 0, 1 или 16 в зависимости от того, какая часть даты — дата или время — отсутствует в date.

Если p не задан, по умолчанию используется текущий год минус 50.

Если задана матрица или массив ячеек с датами, возвращается столбцовый вектор строк с датами.

См. также: datenum, datevec, date, now, clock.

: v = datevec (date)

: v = datevec (date, f)

: v = datevec (date, p)

: v = datevec (date, f, p)

: [y, m, d, h, mi, s] = datevec (…)

Преобразует порядковый номер даты (см. datenum) или строку даты (см. datestr) в вектор даты.

Вектор даты — это вектор-строка из шести элементов, представляющих соответственно год, месяц, день, час, минуту и секунды.

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

v — это двумерный массив векторов дат, по одному вектору даты в каждой строке. Для массивов входных данных порядок элементов v определяется порядком дат в data при обходе по столбцам.

f — строка формата, используемая для интерпретации строк дат (см. datestr). Если date — строка или массив ячеек со строками, но формат не задан, для определения предполагаемого формата входных данных используются эвристики. Эти эвристики могут привести к совпадениям, отличным от ожидаемых пользователем. Кроме того, для этого выполняется относительно медленный поиск среди различных форматов. Если строка формата f известна, всегда предпочтительно указывать её. Для компонентов времени, не указанных в формате, устанавливается значение ноль. Для компонентов даты, не указанных в формате, по умолчанию задаются 1 января текущего года. Конечные символы игнорируются при вычислении вектора даты, даже если они содержат дополнительные сведения о времени или дате.

p — это год начала столетия, к которому будут относиться двузначные годы. Если значение не задано, по умолчанию используется текущий год минус 50.

См. также: datenum, datestr, clock, now, date.

: d = addtodate (d, q, f)

Добавляет к порядковому номеру даты d количество времени q в единицах f.

f должен принимать одно из значений: "year", "month", "day", "hour", "minute", "second" или "millisecond".

См. также: datenum, datevec, etime.

: c = calendar ()

: c = calendar (d)

: c = calendar (y, m)

: calendar (…)

Возвращает календарь текущего месяца в виде матрицы 6x7.

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

Если заданы y и m, возвращает календарь для года y и месяца m.

Если выходные аргументы не указаны, календарь выводится на экран, а не возвращается в виде матрицы.

См. также: datenum, datestr.

: [n, s] = weekday (d)

: [n, s] = weekday (d, format)

Возвращает день недели в виде числа в n и строки в s.

Дни недели нумеруются от 1 до 7, первым днём считается воскресенье.

d — это порядковый номер даты или строка даты.

Если строка format отсутствует или равна "short", в s будет содержаться сокращенное название дня недели. Если format равен "long", в s будет содержаться полное название.

Таблица возвращаемых значений в зависимости от format:

n	"short"	"long"
1	Sun	Sunday
2	Mon	Monday
3	Tue	Tuesday
4	Wed	Wednesday
5	Thu	Thursday
6	Fri	Friday
7	Sat	Saturday

См. также: eomday, is_leap_year, calendar, datenum, datevec.

: e = eomday (y, m)

Возвращает последний день месяца m года y.

См. также: weekday, datenum, datevec, is_leap_year, calendar.

: datetick ()

: datetick (axis_str)

: datetick (date_format)

: datetick (axis_str, date_format)

: datetick (…, "keeplimits")

: datetick (…, "keepticks")

: datetick (hax, …)

Добавляет к оси метки делений, отформатированные как даты.

Ось, к которой применяются метки делений, задается параметром axis_str, который может принимать значения "x", "y" или "z". Значение по умолчанию — "x".

Формат меток определяется переменной date_format, которая может быть строкой или положительным целым числом, допустимым для datestr.

Если первый аргумент hax является дескриптором осей, построение выполняется в этих осях, а не в текущих осях, возвращаемых gca.

См. также: datenum, datestr.