duration

固定长度单位的时间长度

全页展开

说明

持续时间数组中的值以固定长度（如小时、分钟和秒）为单位来表示经过的时间。您还可以用固定长度（24 小时）的天数和固定长度（365.2425 天）的年数创建已用时间。

持续时间数组的使用方式与数值数组相同。您可以对持续时间数组执行加法、减法、排序、比较、串联和绘图等操作。使用持续时间数组可以简化涉及时间单位（如小时和分钟）的日期时间数组的计算。

The datetime data type represents points in time, while the duration and calendarDuration data types represent elapsed time using fixed-length and calendar time units, respectively.

创建对象

您可以使用 years、days、hours、minutes、seconds 和 milliseconds 函数创建具有指定时间单位的持续时间数组。例如，要创建经用时间为 1、2 和 3 小时的数组，请使用 hours 函数。

D = hours(1:3)
D = 

  1×3 duration array

   1 hr   2 hr   3 hr

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

语法

D = duration(H,MI,S)
D = duration(H,MI,S,MS)
D = duration(X)
D = duration(TimeStrings)
D = duration(TimeStrings,'InputFormat',infmt)
D = duration(___,'Format',displayFormat)

描述

D = duration(H,MI,S) 基于数值数组创建持续时间数组，这些数值数组包含分别由 H、MI 和 S 指定的小时数、分钟数和秒数。

示例

D = duration(H,MI,S,MS) 为持续时间数组增加由 MS 指定的毫秒数。

D = duration(X) 基于数值矩阵创建由持续时间组成的列向量。

示例

D = duration(TimeStrings) 将表示已用时间的文本转换为持续时间数组。TimeStrings 必须使用 'hh:mm:ss' 或 'dd:hh:mm:ss' 格式来表示时间。

示例

D = duration(TimeStrings,'InputFormat',infmt) 使用 infmt 指定的格式转换文本。

示例

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

示例

输入参量

全部展开

小时数、分钟数和秒数数组，指定为数值数组。任何这些数组都可以是标量。所有不是标量的数组必须具有相同的大小。

  • 如果任一值是 NaN，则对应的 duration 值是 NaN。

  • 如果任一值为 Inf 或 -Inf，则对应的 duration 值为 Inf 或 -Inf。

示例: duration(12,45,7) 返回的持续时间为 12 小时 45 分钟 7 秒。

毫秒数数组，指定为数值数组。MS 必须是标量，否则大小必须与 H、MI 和 S 输入参量相同。

  • 如果任一值是 NaN，则对应的 duration 值是 NaN。

  • 如果任一值为 Inf 或 -Inf，则对应的 duration 值为 Inf 或 -Inf。

示例: duration(12,45,30,35) 返回的持续时间为 12 小时 45 分钟 30 秒 35 毫秒。

输入矩阵，指定为数值矩阵。X 必须有三列，分别包含小时数、分钟数和秒数。

  • 如果任一值是 NaN，则对应的 duration 值是 NaN。

  • 如果任一值为 Inf 或 -Inf，则对应的 duration 值为 Inf 或 -Inf。

示例: duration([12 30 16]) 返回的持续时间为 12 小时 30 分钟 16 秒。

表示已用时间的文本，指定为字符向量、字符向量元胞数组或字符串数组。duration 函数尝试将 TimeStrings 的格式与 'hh:mm:ss' 或 'dd:hh:mm:ss' 格式匹配，其中 dd、hh、mm 和 ss 分别表示天数、小时数、分钟数和秒数。

  • 要表示小数秒，请使用小数点并指定其右侧的位数。

  • 要表示负历时，请使用前导负号。

    （不接受前导正号 '+'。如果无符号，则时间为正历时。）

如果您知道格式，请指定 'InputFormat' 及其对应的 infmt 值。

示例: duration('12:30:16') 返回的持续时间为 12 小时 30 分钟 16 秒。

示例: duration('00:05:23.867') 返回的持续时间为 5 分钟 23.867 秒。

示例: duration('-04:23:45') 返回的持续时间为负 4 小时 23 分 45 秒。

示例: duration({'01:34:21';'23:16:54'}) 返回包含两个持续时间的列向量。

输入文本的格式，指定为字符向量或字符串标量。

可将 infmt 指定为下列任何格式，其中 dd、hh、mm 和 ss 分别表示天数、小时数、分钟数和秒数：

  • 'dd:hh:mm:ss'

  • 'hh:mm:ss'

  • 'mm:ss'

  • 'hh:mm'

  • 前三种格式中的任一种，后跟小数点再加上最多九个 S 字符指示秒的小数位，例如 'hh:mm:ss.SSS'

属性

全部展开

显示格式，指定为字符向量或字符串标量。格式可以指定一个带有时间单位的数字（例如 'y' 表示年数），也可以是一个数字计时器（例如 'hh:mm:ss' 表示小时数、分钟数和秒数）。

对于带有时间单位的数字，请指定下列单位之一：

  • 'y' - 固定长度的年，一年等于 365.2425 天

  • 'd' - 固定长度的天，一天等于 24 小时

  • 'h' - 小时

  • 'm' - 分钟

  • 's' - 秒

对于数字计时器格式，请指定下列格式之一：

  • 'dd:hh:mm:ss'

  • 'hh:mm:ss'

  • 'mm:ss'

  • 'hh:mm'

  • 前三种格式中的任一种，后跟小数点再加上最多九个 S 字符指示秒的小数位，例如 'hh:mm:ss.SSS'。

示例: D.Format = 'm' 将 D 中的每个值显示为一个分钟数。

示例

全部折叠

打开实时脚本

创建一个日期时间值。

D = datetime('today')
D = datetime
   13-Jul-2025

创建一个日期时间数组，其中每个值的日期相同，但时间分量不同。要创建这样一个数组，简便的方法是将一个持续时间数组与 D 相加。

首先，使用 hours 函数创建一个小时数数组。每个元素比上一个元素多两小时。

H = hours(0:2:6)
H = 1×4 duration
   0 hr   2 hr   4 hr   6 hr

然后将 D 和 H 相加。

T = D + H
T = 1×4 datetime
   13-Jul-2025 00:00:00   13-Jul-2025 02:00:00   13-Jul-2025 04:00:00   13-Jul-2025 06:00:00

使用持续时间数组对日期时间数组和固定长度的时间进行算术运算。

打开实时脚本

创建一个持续时间数组，并指定小时数、分钟数和秒数作为输入参量。由于第二个参量是数组，因此输出 D 是具有相同大小的数组。

D = duration(1,30:33,0)
D = 1×4 duration
   01:30:00   01:31:00   01:32:00   01:33:00
打开实时脚本

创建一个三列数值矩阵。这些列分别代表小时数、分钟数和秒数。

X = [12 17 54;9 32 3]
X = 2×3

    12    17    54
     9    32     3

将矩阵转换为持续时间数组。

D = duration(X)
D = 2×1 duration
   12:17:54
   09:32:03
打开实时脚本

将表示时间的字符向量转换为小时数、分钟数和秒数。

T = '6:34:12';
D = duration(T)
D = duration
   06:34:12

转换字符向量元胞数组。

T = {'12:54:37','8:03:12'};
D = duration(T)
D = 1×2 duration
   12:54:37   08:03:12

转换还包含天数分量的文本。为了便于显示，持续时间数组的默认格式会将天数转换为小时数。

T = '1:00:54:21';
D = duration(T)
D = duration
   24:54:21
打开实时脚本

指定表示已用时间的文本的格式，然后将它们转换为持续时间数组。

转换字符向量。输入格式表示分钟和秒。输出参量是一个持续时间值，其格式表示小时数、分钟数和秒数。 

T = '78:34';
infmt = 'mm:ss';
D = duration(T,'InputFormat',infmt)
D = duration
   01:18:34

创建一个字符向量元胞数组，其格式表示分钟、秒和三位小数秒。

infmt = 'mm:ss.SSS';
T = {'1:34.862' '67:07.218'}
T = 1×2 cell
    {'1:34.862'}    {'67:07.218'}

将 T 转换为持续时间数组。指定持续时间数组的格式，表示小时数、分钟数、秒数和带小数的秒数。

outfmt = 'hh:mm:ss.SSS';
D = duration(T,'InputFormat',infmt,'Format',outfmt)
D = 1×2 duration
   00:01:34.862   01:07:07.218
打开实时脚本

基于矩阵创建一个持续时间数组。其中的三列分别指定小时数、分钟数和秒数。以显示分钟数和秒钟数的数字计时器格式显示这些值。

X = [2 3 16;1 5 59;1 45 0]
X = 3×3

     2     3    16
     1     5    59
     1    45     0


D = duration(X,'Format','mm:ss')
D = 3×1 duration
   123:16
    65:59
   105:00

提示

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

  • 要将持续时间数组转换为数值数组，请使用 years、days、hours、minutes、seconds 和 milliseconds 函数。当输入参量是持续时间数组时，这些函数返回数值数组，表示存储在持续时间数组中的年、日、小时、分钟、秒或毫秒数。

扩展功能

全部展开

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

版本历史记录

在 R2014b 中推出

另请参阅

| | | | |

主题