MatLab函数datetime、datenum、datevec、datestr

【注】详情请参阅 MatLab help 文档。

1. datetime 函数

1.1 作用

datetime 用来创建表示时间点的数组（数组元素类型为 datetime）。

1.2 语法

t = datetime
t = datetime(relativeDay)
t = datetime(DateString)
t = datetime(DateStrings,'InputFormat',infmt)
t = datetime(DateVectors)
t = datetime(Y,M,D)
t = datetime(Y,M,D,H,MI,S)
t = datetime(Y,M,D,H,MI,S,MS)
t = datetime(X,'ConvertFrom',dateType)
t = datetime(___,Name,Value)

• t = datetime
  获取当前日期和时间的标量 datetime 数组。

• t = datetime(relativeDay)
  获取 relativeDay 指定日期的 datetime 数组。

• t = datetime(DateString)
  根据表示时间点的 DateStrings 中的文本创建一个日期时间值数组，datetime 函数会尝试将 DateStrings 的格式与常用格式进行匹配。

DateStrings 常用文本格式如下：

DateStrings 文本格式	举例
'yyyy-MM-dd'	'2020-03-13'
'dd/MM/yyyy'	'13/03/2020'
'dd.MM.yyyy'	'13.03.2020'
'yyyy年 MM月 dd日'	'2020年 03月 13日'
'MMMM d, yyyy'	'March 13, 2020'
'eeee, MMMM d, yyyy h:mm a'	'Friday, March 13, 2020 5:25 PM'
'MMMM d, yyyy HH:mm:ss Z'	'March 13, 2020 17:25:15 -0400'
'yyyy-MM-dd''T''HH:mmXXX'	'2020-03-13T17:25-04:00'
'yyyy-MM-dd HH:mm:ss.SSS'	'2020-03-13 17:25:15.123'

可用于构造日期和时间格式的标识符如下：

字母标识符	说明
G	年代
y	年份（没有前导零）
yy	年份，使用最后两位数
yyy, yyyy ···	年份（至少使用 'y' 实例数指定的位数）
u, uu, ···	ISO 年份（单个数字来指定年份）
Q	季度（使用一位数）
QQ	季度（使用两位数）
QQQ	季度（缩写）
QQQQ	季度（全名）
M	月份（使用一位数或两位数）
MM	月份（使用两位数）
MMM	月份（缩写）
MMMM	月份（全名）
MMMMM	月份（首字母大写）
W	一月中的第几周
d	一月中的第几天（使用一位数或两位数）
dd	一月中的第几天（使用两位数）
D	一年中的第几天（使用一位、两位或三位数）
DD	一年中的第几天（使用两位数）
DDD	一年中的第几天（使用三位数）
e	一周中的星期几（使用一位数）
ee	一周中的星期几（使用两位数）
eee	星期几（缩写名称）
eeee	星期几（全名）
eeeee	星期几（使用一位大写数字）
a	一天中的时段（上午或下午）
h	小时（采用 12 小时制，使用一位或两位数）
hh	小时（采用 12 小时制，使用两位数）
H	小时（采用 24 小时制，使用一位或两位数）
HH	小时（采用 24 小时制，使用两位数）
m	分钟（使用一位或两位数）
mm	分钟（使用两位数）
s	秒（使用一位或两位数）
ss	秒（使用两位数）
S, SS, ···, SSSSSSSSS	小数秒（S 个数指定位数，最多 9 位）

时区偏移量格式如下：

字母标识符	说明
z	时区偏移量的缩写名称
Z	ISO 8601 基本格式（带有小时、分钟和可选的秒字段）
ZZZZ	长 UTC 格式
ZZZZZ	ISO 8601 扩展格式（带有小时、分钟和可选的秒字段）
x 或 X	ISO 8601 基本格式（带有小时和可选分钟字段）
xx 或 XX	ISO 8601 基本格式（带有小时和分钟字段）
xxx 或 XXX	ISO 8601 扩展格式（带有小时和分钟字段）
xxxx 或 XXXX	ISO 8601 基本格式（带有小时、分钟和可选的秒字段）
xxxxx 或 XXXXX	ISO 8601 扩展格式（带有小时、分钟和可选的秒字段）

• t = datetime(DateStrings,'InputFormat',infmt)
  使用 infmt 指定的格式来解释 DateStrings（DateStrings 中的所有值必须具有相同格式）。infmt 可选值参见上文。

• t = datetime(DateVectors)
  根据 DateVectors 中的日期向量创建一个由日期时间值组成的列向量。DateVectors 指定为 或 矩阵，分别包含 个完全或部分日期向量。完整日期向量带有六个元素，依顺序分别指示年、月、日、时、分、秒。部分日期向量指代有三个元素，依顺序分别指示年、月、日。DateVectors 的每个元素应为正整数或负整数值，秒元素可以为小数。如果某元素不在常规范围之内，则 datetime 会同时调整该日期向量元素及其前面的元素。

• t = datetime(Y,M,D)
  为 Y、M、D 数组对应的元素创建一个日期时间值数组（Y、M、D 数组大小必须一致，或者其中任一数组可以是标量）。也可以将输入参数指定为日期向量 [Y M D] 。

• t = datetime(Y,M,D,H,MI,S)
  为 Y、M、D、H、MI、S 数组对应的元素创建一个日期时间值数组（Y、M、D、H、MI、S 数组大小必须一致，或者其中任一数组可以是标量）。也可以将输入参数指定为日期向量 [Y M D H MI S] 。

• t = datetime(Y,M,D,H,MI,S,MS)
  为 Y、M、D、H、MI、S、MS 数组对应的元素创建一个日期时间值数组（Y、M、D、H、MI、S、MS 数组大小必须一致，或者其中任一数组可以是标量）。

• t = datetime(X,'ConvertFrom',dateType)
  将 X 中的数值转换为 datetime 数组 t。dateType 参数指定 X 中的值的类型。dateType 的可选值如下：

dateType	说明
'datenum'	从 0000年 1月 0日起计的天数（前 ISO 日历）
'excel'	从 1900年 1月 0日起计的天数
'excel1904'	从 1904年 1月 0日起计的天数
'juliandate'	从 UTC 时间公元前 4714年 11月 24日（前公历日历）中午起计的天数
'modifiedjuliandate'	从 UTC 时间 1858年 11月 17日午夜起计的天数
'posixtime'	从 UTC 时间 1970年 1月 1日 00:00:00 起计的秒数（不算闰秒）
'yyyymmdd'	以 YYYYMMDD 数值形式表示的日期
'epochtime','Epoch',epochValue	从历元开始的秒数（必须另外指定 epochValue，epochValue 为一个标量 datetime 或表示历元时间的字符向量

【注】

1. Excel 错误地假设 1900 年是闰年。因此，计算 Excel 日期数字时，1900 年 2 月 28 日与 1900 年 3 月 1 日之间因为多了一天而中断。
2. 如果将 X 转换为 datetime 数组而不指定时区，则 datetime 值表示 UTC 时间，而不是本地时间。要表示本地时间，请使用 'TimeZone' 名称-值对组参数指定时区（见下文）。

• t = datetime(___,Name,Value)
  在上述语法基础上去，使用一个或多个键值对属性参数来指定其他选项。常见属性的键值对有：

'Format','default' | 'defaultdate' | 'preserveinput' | 字符向量 ：指定输出数组中值的显示格式。

Format 值	说明
'default'	使用默认的显示格式
'defaultdate'	使用创建时无时间分量的日期时间值的默认显示格式（即去掉时间分量）
'preserveinput'	使用输入格式 infmt 指定的格式（若未指定 infmt，则datetime 自动确认格式）
字符向量	使用字符向量指定的格式

'Locale',字符向量 ：DateStrings 输入参数值的区域设置，Locale 值确定 datetime 如何解释 DateStrings（但不决定如何显示输出 datetime 值）。Locale 的常用可选值如下：

Locale 值	语言	国家/地区
'system'	系统区域设置	系统区域设置
'de_DE'	德语	德国
'en_GB'	英语	英国
'en_US'	英语	美国
'es_ES'	西班牙语	西班牙
'fr_FR'	法语	法国
'it_IT'	意大利语	意大利
'ja_JP'	日语	日本
'ko_KR'	韩语	韩国
'nl_NL'	荷兰语	荷兰
'zh_CN'	简体中文	中国

'PivotYear',year(datetime('now'))-50（默认）| 整数 ：指定双字符年份所在的 100 年日期范围的起始年份，将年份指定为两个字符的日期（仅当 infmt 参数包括 y 或 yy 时，起始年份才有效）。
【注】仅在使用 DateStrings 输入参数时才能使用 'PivotYear' 键值对。

'TimeZone',''（默认）| 字符向量 ：指定时区（包括输入数据和输出数据）。如果输入数据是包括时区的字符向量，则 datetime 函数将所有值转换为指定的时区。TimeZone 的可选值有：

TimeZone 值	说明
''	用于创建不属于特定时区的“未设定时区的” datetime 数组。
IANA 时区	时区地区的名称根据在地理区域观察到的情况，考虑了其标准时和夏令时与 UTC 之间的偏移量的当前和历史规则
+HH:mm 或 -HH:mm	ISO 8601 字符向量，指定与 UTC 存在固定偏移量的时区
'UTC'	用于按协调时间时创建 datetime 数组
'UTCLeapSeconds'	用于按考虑闰秒的协调世界时创建 datetime 数组
'local'	用于按系统时区创建 datetime 数组（查询 TimeZone 属性是返回 IANA 值）

IANA 时区数据库中常用时区地区的通用名称如下：

TimeZone 值	UTC 偏移量	UTC DST 偏移量
'Africa/Johannesburg'	+02:00	+02:00
'America/Chicago'	-06:00	-05:00
'America/Denver'	-07:00	-06:00
'America/Los_Angeles'	-08:00	-07:00
'America/New_York'	-05:00	-04:00
'America/Sao_Paulo'	-03:00	-02:00
'Asia/Hong_Kong'	+08:00	+08:00
'Asia/Kolkata'	+05:30	+05:30
'Asia/Tokyo'	+09:00	+09:00
'Australia/Sydney'	+10:00	+11:00
'Europe/London'	+00:00	+01:00
'Europe/Zurich'	+01:00	+02:00

2. datenum 函数

2.1 作用

datenum 函数用于将日期和时间转换成日期序列值，即将每个时间点表示为从 0000年 1月 0日起的天数。

2.2 语法

DateNumber = datenum(t)
DateNumber = datenum(DateString)
DateNumber = datenum(DateString,formatIn)
DateNumber = datenum(DateString,PivotYear)
DateNumber = datenum(DateString,formatIn,PivotYear)
DateNumber = datenum(DateVector)
DateNumber = datenum(Y,M,D)
DateNumber = datenum(Y,M,D,H,MI,S)

• DateNumber = datenum(t)
  将 t （datetime 数组）中的日期时间值转换为日期序列值（即从 0000年 1月 0日以来的天数及其小数值，采用前 ISO 日历形式）。

• DateNumber = datenum(DateString)
  将表示日期和时间的文本转换为日期序列值（MatLab 自动搜索确认文本格式）。

• DateNumber = datenum(DateString,formatIn)
  手动指定表示日期和时间的文本的格式为 formatIn（字符向量或字符串标量），加快 MatLab 的处理速度。formatIn 的可取的文本格式如下表：

表示日期和时间的文本格式	举例
'dd-mmm-yyyy HH:MM:SS'	'15-Mar-2020 18:25:30'
'dd-mmm-yyyy'	'15-Mar-2020'
'mm/dd/yyyy'	'03/15/2020'
'mm/dd/yy'	'03/15/20
'mm/dd'	'03/15'
'mmm.dd,yyyy HH:MM:SS'	'Mar.15,2020 18:25:30'
'mmm.dd,yyyy'	'Mar.15,2020'
'yyyy-mm-dd HH:MM:SS'	'2020-03-15 18:25:30'
'yyyy-mm-dd'	'2020-03-15'
'yyyy/mm/dd'	'2020/03/15'
'HH:MM:SS'	'18:25:30'
'HH:MM:SS AM' 或 'HH:MM:SS PM'	'06:25:30 PM'
'HH:MM'	'18:25'
'HH:MM AM' 或 'HH:MM PM'	'06:25 PM'

可用于构造 formatIn 中的符号标识符可取值如下表：

符号标识符	说明	举例
yyyy	完整年份	2020
yy	两位数年份	20
QQ	使用字母 Q 和一个数字的季度（仅年份格式可以与季度格式一起使用）	2020/Q1（格式：yyyy/QQ）
mmmm	使用全名的月份	March
mmm	使用月份名的前三个字母	Mar
mm	使用两位数月份	03
m	使用月份名的首字母大写表示月份
dddd	使用日期对应的星期	Sunday
ddd	使用日期对应的星期的前三个字母	Sun
dd	两位数日期	15
d	日期对应的星期的大写首字母	S
HH	两位数小时	18
MM	两位数分钟	25
SS	两位数秒	30
FFF	三位数毫秒	055
AM 或 PM	表示一天中的前/后 12 个小时内（在表示时间的文本中插入 AM 或 PM）	18:25:30 PM

• DateNumber = datenum(DateString,PivotYear)
  PivotYear（整数）指定双字符年份所在的 100 年日期范围内的起始年份，其默认取值为 year(datetime('now'))-50 。
  【注】如果该语法下输入日期格式指定四个字符的年份，则后两个字符将被截断，由前两个字符指定年份。

• DateNumber = datenum(DateString,formatIn,PivotYear)
  结合以上两种语法指定解析格式（formatIn 和 PivotYear 的顺序任意）。

• DateNumber = datenum(DateVector)
  将日期向量解释为日期序列值，返回由 m 个日期序列值构成的列向量。DateVectors 指定为 或 矩阵，分别包含 个完全或部分日期向量。完整日期向量带有六个元素，依顺序分别指示年、月、日、时、分、秒。部分日期向量指代有三个元素，依顺序分别指示年、月、日。DateVectors 的每个元素应为正整数或负整数值，秒元素可以为小数。如果某元素不在常规范围之内，则 datenum 会同时调整该日期向量元素及其前面的元素。

• DateNumber = datenum(Y,M,D)
  返回 Y、M、D（年、月、日）数组对应元素的日期序列值。Y、M、D 数组的大小必须相同（或者其中任一数组可以为标量）。

• DateNumber = datenum(Y,M,D,H,MI,S)
  返回 Y、M、D、H、MI、S（年、月、日、时、分、秒）数组对应元素的日期序列值。Y、M、D、H、MI、S 数组的大小必须相同（或者其中任一数组可以为标量）。

3. datevec 函数

3.1 作用

datevec 函数可以将日期和时间（datetime 格式、datenum 格式或者文本格式）转换为分量的向量。

3.2 语法

DateVector = datevec(t)
DateVector = datevec(DateNumber)
DateVector = datevec(DateString)
DateVector = datevec(DateString,formatIn)
DateVector = datevec(DateString,PivotYear)
DateVector = datevec(DateString,formatIn,PivotYear)
[Y,M,D,H,MI,S] = datevec(___)

• DateVector = datevec(t)
  将 datetime 数组 t 中的日期时间转换为日期向量，返回一个 的矩阵，其中每行对应于 t 中的一个日期时间值。

• DateVector = datevec(DateNumber)
  将一个或多个日期数字转换为日期向量，返回一个包含 个日期向量的 矩阵（ 为 DateNumber 日期数字元素的个数）。DateNumber 可以为向量或矩阵，沿维度从 1 逐渐增大（比如二维矩阵先列后行），依次解释对应的日期数值。

• DateVector = datevec(DateString)
  将表示日期或时间的文本转换成日期向量（MatLab 自动搜索确认文本格式）。

• DateVector = datevec(DateString,formatIn)
  手动指定表示日期和时间的文本的格式为 formatIn（字符向量或字符串标量），加快 MatLab 的处理速度。formatIn 的可取的文本格式如下表：

表示日期和时间的文本格式	举例
'dd-mmm-yyyy HH:MM:SS'	'15-Mar-2020 18:25:30'
'dd-mmm-yyyy'	'15-Mar-2020'
'mm/dd/yyyy'	'03/15/2020'
'mm/dd/yy'	'03/15/20
'mm/dd'	'03/15'
'mmm.dd,yyyy HH:MM:SS'	'Mar.15,2020 18:25:30'
'mmm.dd,yyyy'	'Mar.15,2020'
'yyyy-mm-dd HH:MM:SS'	'2020-03-15 18:25:30'
'yyyy-mm-dd'	'2020-03-15'
'yyyy/mm/dd'	'2020/03/15'
'HH:MM:SS'	'18:25:30'
'HH:MM:SS AM' 或 'HH:MM:SS PM'	'06:25:30 PM'
'HH:MM'	'18:25'
'HH:MM AM' 或 'HH:MM PM'	'06:25 PM'

可用于构造 formatIn 中的符号标识符可取值如下表：

符号标识符	说明	举例
yyyy	完整年份	2020
yy	两位数年份	20
QQ	使用字母 Q 和一个数字的季度（仅年份格式可以与季度格式一起使用）	2020/Q1（格式：yyyy/QQ）
mmmm	使用全名的月份	March
mmm	使用月份名的前三个字母	Mar
mm	使用两位数月份	03
m	使用月份名的首字母大写表示月份
dddd	使用日期对应的星期	Sunday
ddd	使用日期对应的星期的前三个字母	Sun
dd	两位数日期	15
d	日期对应的星期的大写首字母	S
HH	两位数小时	18
MM	两位数分钟	25
SS	两位数秒	30
FFF	三位数毫秒	055
AM 或 PM	表示一天中的前/后 12 个小时内（在表示时间的文本中插入 AM 或 PM）	18:25:30 PM

• DateVector = datevec(DateString,PivotYear)
  PivotYear（整数）指定双字符年份所在的 100 年日期范围内的起始年份，其默认取值为 year(datetime('now'))-50 。
  【注】如果该语法下输入日期格式指定四个字符的年份，则后两个字符将被截断，由前两个字符指定年份。

• DateVector = datevec(DateString,formatIn,PivotYear)
  结合以上两种语法指定解析格式（formatIn 和 PivotYear 的顺序任意）。

• [Y,M,D,H,MI,S] = datevec(___)
  返回日期向量的分量到单独的变量 Y、M、D、H、MI、S（年、月、日、时、分、秒）。datevec 返回毫秒作为 S（秒）输出的小数部分。

4. datestr 函数

4.1 作用

datestr 函数用于将日期和时间（datetime格式、datevec格式、datenum格式）转换为字符串格式。

4.2 语法

DateString = datestr(t)
DateString = datestr(DateVector)
DateString = datestr(DateNumber)
DateString = datestr(___,formatOut)
DateString = datestr(DateStringIn)
DateString = datestr(DateStringIn,formatOut)
DateString = datestr(DateStringIn,formatOut,PivotYear)
DateString = datestr(___,'local')

• DateString = datestr(t)
  将 datetime 数组 t 中的日期时间值转换为日期和时间的文本（char、cellstr、string 函数也可以将 datetime 值转为文本）。返回包含 行的字符数组（ 是 t 中的日期时间值的总数）。默认情况下，datestr 以 day-month-year hour:minute:second 格式返回文本；若 hour:minute:second 为 00:00:00，则返回的文本格式为 day-month-year。

• DateString = datestr(DateVector)
  将日期向量转换为表示日期和时间的文本。datestr 返回包含 行的字符数组（ 是DateVector 中日期向量的总数）。

• DateString = datestr(DateNumber)
  将日期序列值转换为表示日期和时间的文本，datestr 返回包含 行的字符数组（ 是 DateNumber 中的日期序列值的总数）。

• DateString = datestr(___,formatOut)
  在上述语法基础上，使用 formatOut 指定输出文本格式。formatOut 的可取值为 -1（默认）| 字符向量 | 字符串向量 | 整数 。可用于构造 formatOut 字符向量的符号标识符（可用连字符、空格和冒号等字符来分割字段）如下：

符号标识符	说明	举例
yyyy	完整年份	2020
yy	两位数年份	20
QQ	使用字母 Q 和一个数字的季度（仅年份格式可以与季度格式一起使用）	2020/Q1（格式：yyyy/QQ）
mmmm	使用全名的月份	March
mmm	使用月份名的前三个字母	Mar
mm	使用两位数月份	03
m	使用月份名的首字母大写表示月份
dddd	使用日期对应的星期	Sunday
ddd	使用日期对应的星期的前三个字母	Sun
dd	两位数日期	15
d	日期对应的星期的大写首字母	S
HH	两位数小时	18
MM	两位数分钟	25
SS	两位数秒	30
FFF	三位数毫秒	055
AM 或 PM	表示一天中的前/后 12 个小时内（在表示时间的文本中插入 AM 或 PM）	18:25:30 PM

【注】formatOut 字符向量必须遵循以下原则：

1. 每个字段（年、月、日、时、分、秒）只能出现依次。
2. 当使用 AM 或 PM 字段时，还需提供 HH 字段。
3. QQ 只能单独使用或与年份标识符一起使用。

formatOut 预定义日期格式如下表：

数值标识符	日期和时间格式
-1（默认值）	'dd-mmm-yyyy HH:MM:SS' 或 'dd-mmm-yyyy'（如果 'HH:MM:SS'= '00:00:00'）
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,yyyy HH:MM:SS'
22	'mmm.dd,yyyy'
23	'mm/dd/yyyy'
24	'dd/mm/yyyy'
25	'yy/mm/dd'
26	'yyyy/mm/dd'
27	'QQ-yyyy'
28	'mmmyyyy'
29	'yyyy-mm-dd'（ISO 8601）
30	'yyyymmddTHHMMSS'（ISO 8601）
31	'yyyy-mm-dd HH:MM:SS'

• DateString = datestr(DateStringIn)
  将 DateStringIn 转换为 day-month-year hour:minute:second 格式的文本。DateStringIn 表示的所有日期和时间必须具有相同的格式。

• DateString = datestr(DateStringIn,formatOut)
  在上一个语法的基础上，以 formatOut 指定的格式将 DateStringIn 转换为 DateString。DateStringIn 的格式应为下列格式之一：

表示日期和时间的文本格式	举例
'dd-mmm-yyyy HH:MM:SS'	'15-Mar-2020 18:25:30'
'dd-mmm-yyyy'	'15-Mar-2020'
'mm/dd/yyyy'	'03/15/2020'
'mm/dd/yy'	'03/15/20
'mm/dd'	'03/15'
'mmm.dd,yyyy HH:MM:SS'	'Mar.15,2020 18:25:30'
'mmm.dd,yyyy'	'Mar.15,2020'
'yyyy-mm-dd HH:MM:SS'	'2020-03-15 18:25:30'
'yyyy-mm-dd'	'2020-03-15'
'yyyy/mm/dd'	'2020/03/15'
'HH:MM:SS'	'18:25:30'
'HH:MM:SS AM' 或 'HH:MM:SS PM'	'06:25:30 PM'
'HH:MM'	'18:25'
'HH:MM AM' 或 'HH:MM PM'	'06:25 PM'

• DateString = datestr(DateStringIn,formatOut,PivotYear)
  在上一个语法的基础上，使用 PivotYear 解释以双字符形式指定年份的文本。

• DateString = datestr(___,'local')
  在上述语法基础上，返回以当前系统区域设置的语言表示的日期。如果参数列表中不包含 local，则 datestr 以默认语言（美国英语）返回文本（local 参数必须在参数列表最后）。