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 常用文本格式如下：

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

时区偏移量格式如下：

• t = datetime(DateStrings,‘InputFormat’,infmt) 使用 infmt 指定的格式来解释 DateStrings（DateStrings 中的所有值必须具有相同格式）。infmt 可选值参见上文。
• t = datetime(DateVectors) 根据 DateVectors 中的日期向量创建一个由日期时间值组成的列向量。DateVectors 指定为 m×6{m \times 6}m×6 或 m×3{m \times 3}m×3 矩阵，分别包含 mmm 个完全或部分日期向量。完整日期向量带有六个元素，依顺序分别指示年、月、日、时、分、秒。部分日期向量指代有三个元素，依顺序分别指示年、月、日。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’ | 字符向量 ：指定输出数组中值的显示格式。

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

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

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

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

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 指定为 m×6{m \times 6}m×6 或 m×3{m \times 3}m×3 矩阵，分别包含 mmm 个完全或部分日期向量。完整日期向量带有六个元素，依顺序分别指示年、月、日、时、分、秒。部分日期向量指代有三个元素，依顺序分别指示年、月、日。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 中的日期时间转换为日期向量，返回一个 m×6{m \times 6}m×6 的矩阵，其中每行对应于 t 中的一个日期时间值。
• DateVector = datevec(DateNumber) 将一个或多个日期数字转换为日期向量，返回一个包含 mmm 个日期向量的 m×6{m \times 6}m×6 矩阵（mmm 为 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 值转为文本）。返回包含 mmm 行的字符数组（mmm 是 t 中的日期时间值的总数）。默认情况下，datestr 以 day-month-year hour:minute:second 格式返回文本；若 hour:minute:second 为 00:00:00，则返回的文本格式为 day-month-year。
• DateString = datestr(DateVector) 将日期向量转换为表示日期和时间的文本。datestr 返回包含 mmm 行的字符数组（mmm 是DateVector 中日期向量的总数）。
• DateString = datestr(DateNumber) 将日期序列值转换为表示日期和时间的文本，datestr 返回包含 mmm 行的字符数组（mmm 是 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 参数必须在参数列表最后）。