calendarDuration

以可变长度日历单位表示的时间长度

说明

日历持续时间数组中的值用可变长度的日历单位表示经过的时间。例如，一个月有多少天取决于它是一年中的具体月份。计算日历持续时间要考虑到夏令时更改和闰年。使用日历持续时间数组可以简化涉及日历单位（如日和月）的日期时间数组的计算。

创建对象

您可以使用 calyears、calquarters、calmonths、calweeks 和 caldays 函数创建具有指定时间单位的日历持续时间数组。例如，要创建表示 1、2 和 3 个日历月时间长度的数组，请使用 calmonths 函数。

M = calmonths(1:3)

M = 

  1×3 calendarDuration array

   1mo   2mo   3mo

您还可以使用下面介绍的 calendarDuration 函数创建日历持续时间数组。

语法

L = calendarDuration(Y,M,D)

L = calendarDuration(Y,M,D,H,MI,S)

L = calendarDuration(Y,M,D,T)

L = calendarDuration(X)

L = calendarDuration(___,'Format',displayFormat)

描述

L = calendarDuration(Y,M,D) 根据数值数组 Y、M 和 D（分别包含年数、月数和天数）创建一个日历持续时间数组。

L = calendarDuration(Y,M,D,H,MI,S) 还包括小时数、分钟数和秒数，分别由 H、MI 和 S 指定。

L = calendarDuration(Y,M,D,T) 根据数值数组（包含年数、月数和天数）和持续时间数组 T（包含已用时间）创建一个日历持续时间数组。

L = calendarDuration(X) 根据数值矩阵创建一个日历持续时间数组。

L = calendarDuration(___,'Format',displayFormat) 还将 displayFormat 指定为 L 的 Format 属性的值。Format 属性更改 L 的显示方式，而不是更改其值。您可将此语法与上述语法中的任何参量一起使用。

输入参量

Y,M,D — 年数、月数和天数（以单独参量分别指定）

数值数组

年数、月数和天数，指定为数值数组。这些数组的大小必须相同（或者，其中任一项可以为标量）。Y,M,D 只能包含整数值。

指定大于 12 的月值等同于指定一个年数加上一个月数。例如，25 个月等于 2 年零 1 个月。但是，日期值不等同于月数，这是因为月中的天数不是固定的，并且直到您向特定日期时间添加日历持续时间后才能确定。

示例: L = calendarDuration(2,10,24) 返回 2 年 10 个月 24 天的日历持续时间。

H,MI,S — 小时数、分钟数和秒数（以单独参量分别指定）

数值数组

小时数、分钟数和秒数，指定为数值数组。这些数组的大小必须相同（或者，其中任一项可以为标量）。指定小数秒作为 S 的一部分。H 和 MI 数组只能包含整数值。

指定大于 12 的月值等同于指定一个年数加上一个月数。例如，25 个月等于 2 年零 1 个月。大于 60 的分钟值将进位到一个小时数。大于 60 的秒值将进位到一个分钟数。但是，天值不等同于月数，这是因为月中的天数不是固定的，并且直到您向特定日期时间添加日历持续时间后才能确定。类似地，小时值不等同于一个日历天数。

示例: L = calendarDuration(2,10,24,12,45,07.451) 返回 2 年 10 个月 24 天 12 小时 45 分钟 7.451 秒的日历持续时间。

T — 经过的时间

持续时间数组

经过的时间，指定为一个持续时间数组。T 的大小必须与 Y、M 和 D 输入参量相同，或者是一个标量。

示例: T = hours(5); L = calendarDuration(2,10,24,T) 为 L 增加 5 小时持续时间。

X — 年数、月数、天数以及可选的时间

数值矩阵

年数、月数、天数以及可选的时间，指定为数值矩阵。X 必须为三列或六列。前三列分别包含年数、月数和天数。如果 X 有六列，则后三列分别包含小时数、分钟数和秒数。

除第六列外，所有列都必须包含整数值。可以在第六列指定包含小数的秒数。

示例: L = calendarDuration([2 10 24]) 返回 2 年 10 个月 24 天的日历持续时间。

示例: L = calendarDuration([2 10 24 12 45 07.451]) 返回 2 年 10 个月 24 天 12 小时 45 分钟 7.451 秒的日历持续时间。

属性

Format — 显示格式

'ymdt' (默认) | 字符向量 | 字符串标量

日历持续时间的显示格式，指定为字符 y、q、m、w、d 和 t 的组合（按此顺序）。格式必须包含 m、d 和 t。

字符	单位	必需？
y	年	否
q	季度（3 个月的倍数）	否
m	月	是
w	周	否
d	天	是
t	时间（小时、分钟和秒）	是

要指定秒数显示的小数位数，请使用 format 函数。

如果日期或时间分量的值为零，则不显示。

示例: L.Format = 'yqmdt' 将 L 中的每个值显示为日历年数、季度数、月数和天数及其时间分量。

示例

对日期时间值使用日历持续时间

创建一个日期时间值。

D = datetime(2017,7,1)

D = datetime
   01-Jul-2017

创建一个日期时间数组，其中每个值从不同月份的第一天开始。要创建这样一个数组，简便的方法是将一个日历月数组与 D 相加。

首先，使用 calmonths 函数创建一个日历月数组。

C = calmonths(0:3)

C = 1x4 calendarDuration
   0mo   1mo   2mo   3mo

然后将 D 和 C 相加。因为 C 是日历持续时间数组，所以此操作会考虑不同月份有不同天数这个事实。

M = D + C

M = 1x4 datetime
   01-Jul-2017   01-Aug-2017   01-Sep-2017   01-Oct-2017

由于存在闰年和夏令时，所以日历年、月和日可能有不同的长度。要适应这些不同的时间长度，请使用日历持续时间数组对日期时间数组进行算术运算。

创建日历持续时间

L = calendarDuration(1,3,15)

L = calendarDuration
   1y 3mo 15d

指定溢出的数值和持续时间输入

创建一个表示天数的数值数组。

D = [1 3;4 2]

D = 2×2

     1     3
     4     2

创建一个表示经过时数的持续时间数组。有一个元素指定 25 小时，长度超过一天。

T = hours([1 2; 25 12])

T = 2x2 duration
    1 hr    2 hr
   25 hr   12 hr

创建一个日历持续时间数组。指定输入参量 D 和 T，并为年和月指定标量值。第二个输入 13 指定的月数超过一年。

L = calendarDuration(1,13,D,T)

L = 2x2 calendarDuration
    2y 1mo 1d 1h 0m 0s    2y 1mo 3d 2h 0m 0s
   2y 1mo 4d 25h 0m 0s   2y 1mo 2d 12h 0m 0s

大于 12 的月值在显示中进位到年。但是，大于 24 的小时值在显示中不会进位到天。由于夏令时的原因，日历天中的小时数不一定是 24 小时。

指定显示格式

创建一个日历持续时间数组，并指定一种按月、周、天和时间显示这些值的格式。

L = calendarDuration(1,1,5:9,'Format','mwdt')

L = 1x5 calendarDuration
      13mo 5d      13mo 6d      13mo 1w   13mo 1w 1d   13mo 1w 2d

由于此格式不包括表示年的 'y'，所以输入值 1 年和 1 个月显示为二者之和，即 13mo。虽然必须指定 't'，但如果小时、分钟和秒都为零，则不显示时间分量。

提示

• 有关接受或返回日历持续时间数组的函数的详细信息，请参阅日期时间。

• 当您向日期时间中添加一个包含多个单位的 calendarDuration 数组时，MATLAB^® 总是会先添加较大的单位。如果 t 为日期时间，则以下命令：

  t + calendarDuration(1,2,3)

  与下列语句等效：

  t + calyears(1) + calmonths(2) + caldays(3)

扩展功能

tall 数组

对行数太多而无法放入内存的数组进行计算。

此函数完全支持 tall 数组。有关详细信息，请参阅 tall 数组。

基于线程的环境
使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

分布式数组

使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。

此函数完全支持分布式数组。有关详细信息，请参阅Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox)。

版本历史记录

在 R2014b 中推出

另请参阅

duration | datetime | between | caldiff | iscalendarduration | split | time | string | char | cellstr

主题

• 表示 MATLAB 中的日期时间
• 生成日期与时间的序列
• 比较日期时间
• 日期时间算术运算