pub struct Duration { /* private fields */ }
Expand description
Duration
类型代表时间跨度,通常用于系统超时。
每个 Duration
由整数秒和以纳秒表示的小数部分组成。
如果底层系统不支持纳秒级精度,则绑定系统超时的 API 通常会将纳秒数四舍五入。
Duration
实现了许多常见的 traits,包括 Add
,Sub
和其他 ops
traits。它通过返回零长度 Duration
来实现 Default
。
Examples
use std::time::Duration;
let five_seconds = Duration::new(5, 0);
let five_seconds_and_five_nanos = five_seconds + Duration::new(0, 5);
assert_eq!(five_seconds_and_five_nanos.as_secs(), 5);
assert_eq!(five_seconds_and_five_nanos.subsec_nanos(), 5);
let ten_millis = Duration::from_millis(10);
Run格式化 Duration
值
Duration
故意不实现 Display
impl,因为有多种方法可以设置时间跨度的格式,以提高人类的可读性。
Duration
提供了一个 Debug
impl,它显示了值的完整精度。
Debug
输出使用非 ASCII “µs” 后缀微秒。
如果您的程序输出可能出现在不依赖于完全 Unicode 兼容性的上下文中,则您可能希望自己格式化 Duration
对象或使用 crate 这样做。
Implementations§
source§impl Duration
impl Duration
sourcepub const SECOND: Duration = Duration::from_secs(1)
🔬This is a nightly-only experimental API. (duration_constants
#57391)
pub const SECOND: Duration = Duration::from_secs(1)
duration_constants
#57391)sourcepub const MILLISECOND: Duration = Duration::from_millis(1)
🔬This is a nightly-only experimental API. (duration_constants
#57391)
pub const MILLISECOND: Duration = Duration::from_millis(1)
duration_constants
#57391)sourcepub const MICROSECOND: Duration = Duration::from_micros(1)
🔬This is a nightly-only experimental API. (duration_constants
#57391)
pub const MICROSECOND: Duration = Duration::from_micros(1)
duration_constants
#57391)sourcepub const NANOSECOND: Duration = Duration::from_nanos(1)
🔬This is a nightly-only experimental API. (duration_constants
#57391)
pub const NANOSECOND: Duration = Duration::from_nanos(1)
duration_constants
#57391)1.53.0 · sourcepub const MAX: Duration = Duration::new(u64::MAX, NANOS_PER_SEC - 1)
pub const MAX: Duration = Duration::new(u64::MAX, NANOS_PER_SEC - 1)
最大持续时间。
根据平台的需要可能有所不同。
必须能够包含两个 Instant
实例或两个 SystemTime
实例之间的差异。
该约束使其在实践中的值约为 584,942,417,355 年,目前在所有平台上都使用。
Examples
use std::time::Duration;
assert_eq!(Duration::MAX, Duration::new(u64::MAX, 1_000_000_000 - 1));
Runconst: 1.32.0 · sourcepub const fn from_millis(millis: u64) -> Duration
pub const fn from_millis(millis: u64) -> Duration
1.27.0 (const: 1.32.0) · sourcepub const fn from_micros(micros: u64) -> Duration
pub const fn from_micros(micros: u64) -> Duration
1.27.0 (const: 1.32.0) · sourcepub const fn from_nanos(nanos: u64) -> Duration
pub const fn from_nanos(nanos: u64) -> Duration
1.53.0 (const: 1.53.0) · sourcepub const fn is_zero(&self) -> bool
pub const fn is_zero(&self) -> bool
如果此 Duration
不跨越时间,则返回 true。
Examples
use std::time::Duration;
assert!(Duration::ZERO.is_zero());
assert!(Duration::new(0, 0).is_zero());
assert!(Duration::from_nanos(0).is_zero());
assert!(Duration::from_secs(0).is_zero());
assert!(!Duration::new(1, 1).is_zero());
assert!(!Duration::from_nanos(1).is_zero());
assert!(!Duration::from_secs(1).is_zero());
Runconst: 1.32.0 · sourcepub const fn as_secs(&self) -> u64
pub const fn as_secs(&self) -> u64
返回此 Duration
包含的 whole 秒数。
返回的值不包括持续时间的小数 (nanosecond) 部分,可以使用 subsec_nanos
获得。
Examples
use std::time::Duration;
let duration = Duration::new(5, 730023852);
assert_eq!(duration.as_secs(), 5);
Run要确定由 Duration
表示的总秒数 (包括小数部分),请使用 as_secs_f64
或 as_secs_f32
1.27.0 (const: 1.32.0) · sourcepub const fn subsec_millis(&self) -> u32
pub const fn subsec_millis(&self) -> u32
1.27.0 (const: 1.32.0) · sourcepub const fn subsec_micros(&self) -> u32
pub const fn subsec_micros(&self) -> u32
const: 1.32.0 · sourcepub const fn subsec_nanos(&self) -> u32
pub const fn subsec_nanos(&self) -> u32
1.16.0 (const: 1.58.0) · sourcepub const fn checked_add(self, rhs: Duration) -> Option<Duration>
pub const fn checked_add(self, rhs: Duration) -> Option<Duration>
1.53.0 (const: 1.58.0) · sourcepub const fn saturating_add(self, rhs: Duration) -> Duration
pub const fn saturating_add(self, rhs: Duration) -> Duration
Duration
饱和添加。
计算 self + other
,如果发生溢出则返回 Duration::MAX
。
Examples
#![feature(duration_constants)]
use std::time::Duration;
assert_eq!(Duration::new(0, 0).saturating_add(Duration::new(0, 1)), Duration::new(0, 1));
assert_eq!(Duration::new(1, 0).saturating_add(Duration::new(u64::MAX, 0)), Duration::MAX);
Run1.16.0 (const: 1.58.0) · sourcepub const fn checked_sub(self, rhs: Duration) -> Option<Duration>
pub const fn checked_sub(self, rhs: Duration) -> Option<Duration>
1.53.0 (const: 1.58.0) · sourcepub const fn saturating_sub(self, rhs: Duration) -> Duration
pub const fn saturating_sub(self, rhs: Duration) -> Duration
Duration
减法饱和。
计算 self - other
,如果结果为负或发生溢出,则返回 Duration::ZERO
。
Examples
use std::time::Duration;
assert_eq!(Duration::new(0, 1).saturating_sub(Duration::new(0, 0)), Duration::new(0, 1));
assert_eq!(Duration::new(0, 0).saturating_sub(Duration::new(0, 1)), Duration::ZERO);
Run1.16.0 (const: 1.58.0) · sourcepub const fn checked_mul(self, rhs: u32) -> Option<Duration>
pub const fn checked_mul(self, rhs: u32) -> Option<Duration>
1.53.0 (const: 1.58.0) · sourcepub const fn saturating_mul(self, rhs: u32) -> Duration
pub const fn saturating_mul(self, rhs: u32) -> Duration
饱和 Duration
乘法。
计算 self * other
,如果发生溢出则返回 Duration::MAX
。
Examples
#![feature(duration_constants)]
use std::time::Duration;
assert_eq!(Duration::new(0, 500_000_001).saturating_mul(2), Duration::new(1, 2));
assert_eq!(Duration::new(u64::MAX - 1, 0).saturating_mul(2), Duration::MAX);
Run1.16.0 (const: 1.58.0) · sourcepub const fn checked_div(self, rhs: u32) -> Option<Duration>
pub const fn checked_div(self, rhs: u32) -> Option<Duration>
检查 Duration
分区。
计算 self / other
,如果为 other == 0
,则返回 None
。
Examples
基本用法:
use std::time::Duration;
assert_eq!(Duration::new(2, 0).checked_div(2), Some(Duration::new(1, 0)));
assert_eq!(Duration::new(1, 0).checked_div(2), Some(Duration::new(0, 500_000_000)));
assert_eq!(Duration::new(2, 0).checked_div(0), None);
Run1.38.0 (const: unstable) · sourcepub fn as_secs_f64(&self) -> f64
pub fn as_secs_f64(&self) -> f64
1.38.0 (const: unstable) · sourcepub fn as_secs_f32(&self) -> f32
pub fn as_secs_f32(&self) -> f32
1.38.0 · sourcepub fn from_secs_f64(secs: f64) -> Duration
pub fn from_secs_f64(secs: f64) -> Duration
从指定的秒数 (表示为 f64
) 创建一个新的 Duration
。
Panics
如果 secs
为 negative、溢出 Duration
或不是有限的,此构造函数将出现 panic。
Examples
use std::time::Duration;
let res = Duration::from_secs_f64(0.0);
assert_eq!(res, Duration::new(0, 0));
let res = Duration::from_secs_f64(1e-20);
assert_eq!(res, Duration::new(0, 0));
let res = Duration::from_secs_f64(4.2e-7);
assert_eq!(res, Duration::new(0, 420));
let res = Duration::from_secs_f64(2.7);
assert_eq!(res, Duration::new(2, 700_000_000));
let res = Duration::from_secs_f64(3e10);
assert_eq!(res, Duration::new(30_000_000_000, 0));
// subnormal 浮点
let res = Duration::from_secs_f64(f64::from_bits(1));
assert_eq!(res, Duration::new(0, 0));
// 转换使用舍入
let res = Duration::from_secs_f64(0.999e-9);
assert_eq!(res, Duration::new(0, 1));
Run1.38.0 · sourcepub fn from_secs_f32(secs: f32) -> Duration
pub fn from_secs_f32(secs: f32) -> Duration
从指定的秒数 (表示为 f32
) 创建一个新的 Duration
。
Panics
如果 secs
为 negative、溢出 Duration
或不是有限的,此构造函数将出现 panic。
Examples
use std::time::Duration;
let res = Duration::from_secs_f32(0.0);
assert_eq!(res, Duration::new(0, 0));
let res = Duration::from_secs_f32(1e-20);
assert_eq!(res, Duration::new(0, 0));
let res = Duration::from_secs_f32(4.2e-7);
assert_eq!(res, Duration::new(0, 420));
let res = Duration::from_secs_f32(2.7);
assert_eq!(res, Duration::new(2, 700_000_048));
let res = Duration::from_secs_f32(3e10);
assert_eq!(res, Duration::new(30_000_001_024, 0));
// subnormal 浮点
let res = Duration::from_secs_f32(f32::from_bits(1));
assert_eq!(res, Duration::new(0, 0));
// 转换使用舍入
let res = Duration::from_secs_f32(0.999e-9);
assert_eq!(res, Duration::new(0, 1));
Run1.38.0 · sourcepub fn div_f32(self, rhs: f32) -> Duration
pub fn div_f32(self, rhs: f32) -> Duration
将 Duration
除以 f32
。
Panics
如果结果为 negative、溢出 Duration
或不是有限的,此方法将出现 panic。
Examples
use std::time::Duration;
let dur = Duration::new(2, 700_000_000);
// 请注意,由于舍入错误,结果与 0.859_872_611 略有不同
assert_eq!(dur.div_f32(3.14), Duration::new(0, 859_872_580));
assert_eq!(dur.div_f32(3.14e5), Duration::new(0, 8_599));
Runconst: unstable · sourcepub fn div_duration_f64(self, rhs: Duration) -> f64
🔬This is a nightly-only experimental API. (div_duration
#63139)
pub fn div_duration_f64(self, rhs: Duration) -> f64
div_duration
#63139)source§impl Duration
impl Duration
1.66.0 · sourcepub fn try_from_secs_f32(secs: f32) -> Result<Duration, TryFromFloatSecsError>
pub fn try_from_secs_f32(secs: f32) -> Result<Duration, TryFromFloatSecsError>
from_secs_f32
的检查版本。
如果 secs
为 negative、溢出 Duration
或不是有限的,则此构造函数将返回 Err
。
Examples
use std::time::Duration;
let res = Duration::try_from_secs_f32(0.0);
assert_eq!(res, Ok(Duration::new(0, 0)));
let res = Duration::try_from_secs_f32(1e-20);
assert_eq!(res, Ok(Duration::new(0, 0)));
let res = Duration::try_from_secs_f32(4.2e-7);
assert_eq!(res, Ok(Duration::new(0, 420)));
let res = Duration::try_from_secs_f32(2.7);
assert_eq!(res, Ok(Duration::new(2, 700_000_048)));
let res = Duration::try_from_secs_f32(3e10);
assert_eq!(res, Ok(Duration::new(30_000_001_024, 0)));
// subnormal 浮点:
let res = Duration::try_from_secs_f32(f32::from_bits(1));
assert_eq!(res, Ok(Duration::new(0, 0)));
let res = Duration::try_from_secs_f32(-5.0);
assert!(res.is_err());
let res = Duration::try_from_secs_f32(f32::NAN);
assert!(res.is_err());
let res = Duration::try_from_secs_f32(2e19);
assert!(res.is_err());
// 转换使用带平局分辨率的舍入来均匀
let res = Duration::try_from_secs_f32(0.999e-9);
assert_eq!(res, Ok(Duration::new(0, 1)));
// 这个浮点数正好代表 976562.5e-9
let val = f32::from_bits(0x3A80_0000);
let res = Duration::try_from_secs_f32(val);
assert_eq!(res, Ok(Duration::new(0, 976_562)));
// 这个浮点数正好代表 2929687.5e-9
let val = f32::from_bits(0x3B40_0000);
let res = Duration::try_from_secs_f32(val);
assert_eq!(res, Ok(Duration::new(0, 2_929_688)));
// 这个浮点数正好代表 1.000_976_562_5
let val = f32::from_bits(0x3F802000);
let res = Duration::try_from_secs_f32(val);
assert_eq!(res, Ok(Duration::new(1, 976_562)));
// 这个浮点数正好代表 1.002_929_687_5
let val = f32::from_bits(0x3F806000);
let res = Duration::try_from_secs_f32(val);
assert_eq!(res, Ok(Duration::new(1, 2_929_688)));
Run1.66.0 · sourcepub fn try_from_secs_f64(secs: f64) -> Result<Duration, TryFromFloatSecsError>
pub fn try_from_secs_f64(secs: f64) -> Result<Duration, TryFromFloatSecsError>
from_secs_f64
的检查版本。
如果 secs
为 negative、溢出 Duration
或不是有限的,则此构造函数将返回 Err
。
Examples
use std::time::Duration;
let res = Duration::try_from_secs_f64(0.0);
assert_eq!(res, Ok(Duration::new(0, 0)));
let res = Duration::try_from_secs_f64(1e-20);
assert_eq!(res, Ok(Duration::new(0, 0)));
let res = Duration::try_from_secs_f64(4.2e-7);
assert_eq!(res, Ok(Duration::new(0, 420)));
let res = Duration::try_from_secs_f64(2.7);
assert_eq!(res, Ok(Duration::new(2, 700_000_000)));
let res = Duration::try_from_secs_f64(3e10);
assert_eq!(res, Ok(Duration::new(30_000_000_000, 0)));
// subnormal 浮点
let res = Duration::try_from_secs_f64(f64::from_bits(1));
assert_eq!(res, Ok(Duration::new(0, 0)));
let res = Duration::try_from_secs_f64(-5.0);
assert!(res.is_err());
let res = Duration::try_from_secs_f64(f64::NAN);
assert!(res.is_err());
let res = Duration::try_from_secs_f64(2e19);
assert!(res.is_err());
// 转换使用带平局分辨率的舍入来均匀
let res = Duration::try_from_secs_f64(0.999e-9);
assert_eq!(res, Ok(Duration::new(0, 1)));
let res = Duration::try_from_secs_f64(0.999_999_999_499);
assert_eq!(res, Ok(Duration::new(0, 999_999_999)));
let res = Duration::try_from_secs_f64(0.999_999_999_501);
assert_eq!(res, Ok(Duration::new(1, 0)));
let res = Duration::try_from_secs_f64(42.999_999_999_499);
assert_eq!(res, Ok(Duration::new(42, 999_999_999)));
let res = Duration::try_from_secs_f64(42.999_999_999_501);
assert_eq!(res, Ok(Duration::new(43, 0)));
// 这个浮点数正好代表 976562.5e-9
let val = f64::from_bits(0x3F50_0000_0000_0000);
let res = Duration::try_from_secs_f64(val);
assert_eq!(res, Ok(Duration::new(0, 976_562)));
// 这个浮点数正好代表 2929687.5e-9
let val = f64::from_bits(0x3F68_0000_0000_0000);
let res = Duration::try_from_secs_f64(val);
assert_eq!(res, Ok(Duration::new(0, 2_929_688)));
// 这个浮点数正好代表 1.000_976_562_5
let val = f64::from_bits(0x3FF0_0400_0000_0000);
let res = Duration::try_from_secs_f64(val);
assert_eq!(res, Ok(Duration::new(1, 976_562)));
// 这个浮点数正好代表 1.002_929_687_5
let val = f64::from_bits(0x3_FF00_C000_0000_000);
let res = Duration::try_from_secs_f64(val);
assert_eq!(res, Ok(Duration::new(1, 2_929_688)));
RunTrait Implementations§
1.8.0 · source§impl Add<Duration> for SystemTime
impl Add<Duration> for SystemTime
source§fn add(self, dur: Duration) -> SystemTime
fn add(self, dur: Duration) -> SystemTime
Panics
如果生成的时间点无法由底层数据结构表示,则此函数可能出现 panic。
没有 panic 的版本,请参见 SystemTime::checked_add
。
§type Output = SystemTime
type Output = SystemTime
+
运算符后的结果类型。1.9.0 · source§impl AddAssign<Duration> for Duration
impl AddAssign<Duration> for Duration
source§fn add_assign(&mut self, rhs: Duration)
fn add_assign(&mut self, rhs: Duration)
+=
操作。 Read more1.9.0 · source§impl AddAssign<Duration> for Instant
impl AddAssign<Duration> for Instant
source§fn add_assign(&mut self, other: Duration)
fn add_assign(&mut self, other: Duration)
+=
操作。 Read more1.9.0 · source§impl AddAssign<Duration> for SystemTime
impl AddAssign<Duration> for SystemTime
source§fn add_assign(&mut self, other: Duration)
fn add_assign(&mut self, other: Duration)
+=
操作。 Read more1.9.0 · source§impl DivAssign<u32> for Duration
impl DivAssign<u32> for Duration
source§fn div_assign(&mut self, rhs: u32)
fn div_assign(&mut self, rhs: u32)
/=
操作。 Read more1.9.0 · source§impl MulAssign<u32> for Duration
impl MulAssign<u32> for Duration
source§fn mul_assign(&mut self, rhs: u32)
fn mul_assign(&mut self, rhs: u32)
*=
操作。 Read moresource§impl PartialOrd<Duration> for Duration
impl PartialOrd<Duration> for Duration
1.8.0 · source§impl Sub<Duration> for SystemTime
impl Sub<Duration> for SystemTime
§type Output = SystemTime
type Output = SystemTime
-
运算符后的结果类型。1.9.0 · source§impl SubAssign<Duration> for Duration
impl SubAssign<Duration> for Duration
source§fn sub_assign(&mut self, rhs: Duration)
fn sub_assign(&mut self, rhs: Duration)
-=
操作。 Read more1.9.0 · source§impl SubAssign<Duration> for Instant
impl SubAssign<Duration> for Instant
source§fn sub_assign(&mut self, other: Duration)
fn sub_assign(&mut self, other: Duration)
-=
操作。 Read more1.9.0 · source§impl SubAssign<Duration> for SystemTime
impl SubAssign<Duration> for SystemTime
source§fn sub_assign(&mut self, other: Duration)
fn sub_assign(&mut self, other: Duration)
-=
操作。 Read more