MatLab函数datetime、datenum、datevec、datestr

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

1. datetime 函数

1.1 作用

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

1.2 语法

1
2
3
4
5
6
7
8
9
10
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 指定为 m×6{m \times 6}m×3{m \times 3} 矩阵,分别包含 mm 个完全或部分日期向量。完整日期向量带有六个元素,依顺序分别指示年、月、日、时、分、秒。部分日期向量指代有三个元素,依顺序分别指示年、月、日。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 语法

1
2
3
4
5
6
7
8
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 指定为 m×6{m \times 6}m×3{m \times 3} 矩阵,分别包含 mm 个完全或部分日期向量。完整日期向量带有六个元素,依顺序分别指示年、月、日、时、分、秒。部分日期向量指代有三个元素,依顺序分别指示年、月、日。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 语法

1
2
3
4
5
6
7
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 中的日期时间转换为日期向量,返回一个 m×6{m \times 6} 的矩阵,其中每行对应于 t 中的一个日期时间值。

  • DateVector = datevec(DateNumber)
    将一个或多个日期数字转换为日期向量,返回一个包含 mm 个日期向量的 m×6{m \times 6} 矩阵(mm 为 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 语法

1
2
3
4
5
6
7
8
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 值转为文本)。返回包含 mm 行的字符数组(mm 是 t 中的日期时间值的总数)。默认情况下,datestr 以 day-month-year hour:minute:second 格式返回文本;若 hour:minute:second00:00:00,则返回的文本格式为 day-month-year

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

  • DateString = datestr(DateNumber)
    将日期序列值转换为表示日期和时间的文本,datestr 返回包含 mm 行的字符数组(mm 是 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 参数必须在参数列表最后)。