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.

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.

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.

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"

Функция Octave strftime поддерживает расширенный набор спецификаторов полей 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-часовое (чч:мм:сс [ДОП]Ч).

%R

Время, 24-часовое (чч:мм).

%s

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

%S

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

%T

Время, 24-часовое (чч:мм:сс).

%X

Представление времени в соответствии с локалью (%Ч:%М:%С).

%z

Смещение от UTC (±ччмм), или ничего, если временная зона не определяема.

%Z

Временная зона (EDT), или ничего, если временная зона не определяема.

Поля даты:

%a

Сокращённое имя дня недели в соответствии с локалью (Вс-Сб).

%A

Полное имя дня недели в соответствии с локалью, переменной длины (Воскресенье-Суббота).

%b

Сокращённое имя месяца в соответствии с локалью (Ян-Дек).

%B

Полное имя месяца в соответствии с локалью, переменной длины (Январь-Декабрь).

%c

Дата и время в соответствии с локалью (Сб Ноя 04 12:02:33 EST 1989).

%C

Века (00-99).

%d

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

%e

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

%D

Дата (мм/дд/гггг).

%h

То же, что и %b.

%j

Номер дня года (001-366).

%m

Месяц (01-12).

%U

Номер недели года, с воскресеньем как первым днём недели (00-53).

%w

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

%W

Номер недели года, с понедельником как первым днём недели (00-53).

%x

Представление даты в соответствии с локалью (мм/дд/гггг).

%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, а другие предоставляются, так как они полезны.

clock ()

Возвращает текущую локальную дату и время в виде вектора дат.

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

Например:

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

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

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

date ()

Возвращает текущую дату в виде строковой строки в формате ДД-MMM-ГГГГ.

Например:

date ()
  ⇒ 20-Aug-1993

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

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.

is_leap_year ()

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 для примеров использования tic/toc.

См. также: 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 (см. datestr) или задаваться непосредственно.

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

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

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

Примечания:

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

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

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

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

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

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	Полное название месяца	Декабрь
mmm	Сокращённое название месяца	Дек
mm	Числовой номер месяца (дополнен нулями)	01, 08, 12
m	Первая буква названия месяца (заглавная)	Д
dddd	Полное название дня недели	Воскресенье
ddd	Сокращённое название дня недели	Вск
dd	Число месяца (дополнен нулями)	11
d	Первая буква названия дня недели (заглавная)	В
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) в вектор даты.

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

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

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

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

d = addtodate (d, q, f)

Добавьте значение q времени (с единицами f) к серийному значению datenum, d.

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	День недели (сокращённо)	День недели (полностью)
1	Вск	Воскресенье
2	Пн	Понедельник
3	Вт	Вторник
4	Ср	Среда
5	Чт	Четверг
6	Пт	Пятница
7	Сб	Суббота

См. также: 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.