时间工具 (GNU Octave(版本11.1.0))

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 月 1 日以来的天数 (0-365)。
isdst: 夏令时标志。
gmtoff: 相对于 UTC 的偏移秒数。
zone: 时区。

在以下函数的描述中，此结构被称为 tm_struct。

seconds = time () ¶

返回自纪元以来以秒为单位的当前时间。

纪元参考时间为 1970 年 1 月 1 日 00:00:00 UTC（协调世界时）。例如，1997 年 2 月 17 日星期一 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 月 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\
"

另请参阅： 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\ "。

例如：

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

这等价于 ctime (time ())。

另请参阅： ctime, localtime, time.

str = strftime (fmt, tm_struct) ¶

使用格式字符串 fmt 灵活地格式化时间结构 tm_struct，该格式字符串包含类似于 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: 区域设置的上午或下午。
%r: 时间，12 小时制 (hh:mm:ss [AP]M)。
%R: 时间，24 小时制 (hh:mm)。
%s: 自 1970 年 1 月 1 日 00:00:00 以来的秒数（非标准扩展）。
%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)。
%E: E 修饰符（POSIX 扩展）：仅与修饰符 c、C、x、X、y、Y 结合使用。
%0: O 修饰符（POSIX 扩展）：仅与修饰符 d、e、H、I、m、M、S、u、U、V、W、w、y 结合使用。

另请参阅： strptime, time, gmtime, localtime, mktime, asctime, ctime, now, date, clock, datenum, datestr, datevec, calendar, weekday.

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

将字符串 str 按照格式字符串 fmt 解析为时间结构 tm_struct。

如果解析成功，nchars 返回已使用的字符数。如果整个字符串被解析完，nchars 将为空矩阵 []。

有关格式说明符的完整描述，请参阅 strftime。

strptime ("07:15:06", "%X")
     ⇒  {
           usec = 0
           sec = 6
           min = 15
           hour = 7
           mday = 1
           mon = 0
           year = 0
           wday = 6
           yday = 0
           isdst = -1
           gmtoff = -21600
           zone = CST
        }

另请参阅： strftime, time, gmtime, localtime, mktime, asctime, ctime, now, date, clock, datenum, datestr, datevec, calendar, weekday.

str = date () ¶

以 DD-MMM-YYYY（例如，17-Feb-1997）格式返回当前日期。

另请参阅： clock, now, time.

date_vector = clock () ¶

以包含以下格式的向量形式返回当前日期和时间： [year, month, day, hour, minute, second]。

例如：

clock ()
     ⇒  [ 1997, 2, 17, 1, 15, 6 ]

另请参阅： date, now, time.

days = datenum (datevec) ¶

days = datenum (year, month, day) ¶

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

days = datenum (datestr) ¶

days = datenum (datestr, format) ¶

[days, secs] = datenum (…) ¶

将日期和时间映射到序列日期编号。

序列日期编号是从固定参考点开始以天为单位测量的。在 Octave 中，参考点是 ISO 标准参考点 0000 年 1 月 1 日的午夜，被认为是第 0 天。在 datenum 中，参考点计算为第 1 天。例如：

datenum (1997, 2, 17)
     ⇒  729847

输出 days 是整数部分，secs 是小数秒部分。

另请参阅： datestr, datevec, now, clock, date.

str = datestr (d) ¶

str = datestr (d, f) ¶

str = datestr (d, f, ref) ¶

将日期序列编号（datenum 的输出）或日期向量（datevec 的输出）格式化为由 f 确定的格式的字符串。如果未指定 f 或为 []，则使用默认格式："dd-mmm-yyyy HH:MM:SS" 或 "dd-mmm-yyyy"，取决于日期是否为整数。

有关完整说明，请参阅 Octave 参考手册中的 Formatted Date Strings。

datestr 接受整数格式代码 0–31 以及以下格式字符串：

0: dd-mmm-yyyy HH:MM:SS
1: dd-mmm-yyyy
2: mm/dd/yy
3: mmm
4: m
5: mm
6: mm/dd
7: dd
8: ddd
9: d
10: yyyy
11: yy
12: mmmyy
13: HH:MM:SS
14: HH:MM:SS PM
15: HH:MM
16: HH:MM PM
17: QQ-YY
18: QQ
19: dd/mm
20: dd/mm/yy
21: mmm.dd,yy
22: m/d/yy
23: mmm.dd,yyyy HH:MM:SS
24: mm/dd/yyyy
25: dd/mm/yyyy
26: yy/mm/dd
27: yyyy/mm/dd
28: QQ-yyyy
29: yyyy/mm/dd HH:MM:SS
30: yyyymmddTHHMMSS
31: yyyy-mm-dd HH:MM:SS

如果提供了 ref，它将指定输出格式中日期的年份基础。它可以是代码 0（默认值 -1 到 69 映射到 2000–2069，70 到 99 映射到 1970–1999）、代码 100（对于 91 到 100 映射到 1991–2000，对于 01 到 89 映射到 2001–2089）或任何 4 位数字年份，例如 2014。

另请参阅： datenum, datevec, now, clock, date.

dv = datevec (date) ¶

[y, m, d, h, mi, s] = datevec (date) ¶

[y, m, d, h, mi, s] = datevec (date, f) ¶

[y, m, d, h, mi, s] = datevec (date, f, ref) ¶

将日期序列编号（datenum 的输出）或日期字符串转换为日期向量。

日期向量是一个行向量，包含六个元素，依次为：年、月、日、时、分、秒。

另请参阅： datenum, datestr, clock, now, date.

sec = etime (t2, t1) ¶

返回向量 t1 和 t2 之间的秒数。这两个向量必须是由 clock 返回的六元素日期向量格式。

例如：

t0 = clock ();
# ... 许多计算 ...
etime (clock (), t0)

另请参阅： clock, now, date, addtodate.

elapsed_time = laps () ¶

elapsed_time = laps (start) ¶

如果使用一个数字参数调用，laps 会记住该值并返回零。如果无参数调用，laps 会返回自使用数字参数调用以来经过的时间，并以可选格式打印该时间。

为了更精确地测量经过的时间，请使用 tic 和 toc。

另请参阅： tic, toc, etime.

id = tic () ¶

使用高分辨率计时器记录当前时间。

后续调用 toc 将返回自 tic 执行以来经过的时间。

例如，测量一个不合理的代码行所需的时间：

tic (); # 注意，这里测量的是 display 和 plot 所需的时间
#（在 Octave 中使用 tic/toc 时，若担心影响，会排除编译和显示时间）
sleep (3); toc ()
    ⇒  3.00154

多次调用 tic 会返回一个唯一的计时器标识符，该标识符可作为 toc 的参数使用。

另请参阅： toc, etime, laps.

val = toc () ¶

val = toc (id) ¶

返回自最近一次 tic 调用以来经过的秒数。

如果给定 id，则返回该特定标识符对应的经过时间。

另请参阅： tic, etime, laps.

[total, user] = cputime () ¶

以秒为单位返回当前 Octave 会话中使用的 CPU 时间。

第一个输出是当前 Octave 会话中使用的总 CPU 时间。第二个输出是当前 Octave 会话中使用的用户 CPU 时间。

另请参阅： time, tic, toc.

tf = is_leap_year () ¶

tf = is_leap_year (year) ¶

如果 year 是闰年，则返回 true。

如果未指定参数，则使用当前年份。

另请参阅： weekday, eomday, calendar.

d = addtodate (d, q, f) ¶

将数量 q 添加到日期序列编号 d 的字段 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 所在月份的日历， 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) ¶

返回年份 y 中月份 m 的最后一天。

另请参阅： 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.