【注】详情请参阅 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 常用文本格式如下：

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

时区偏移量格式如下：

• 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 的可选值如下：

【注】

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 的可取的文本格式如下表：

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

• 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 的可取的文本格式如下表：

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

• 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 字符向量的符号标识符（可用连字符、空格和冒号等字符来分割字段）如下：

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

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

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

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

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

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

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