pub struct Duration {/* private fields */ }Expand description
ADuration type to represent a span of time, typically used for systemtimeouts.
EachDuration is composed of a whole number of seconds and a fractional partrepresented in nanoseconds. If the underlying system does not supportnanosecond-level precision, APIs binding a system timeout will typically round upthe number of nanoseconds.
Durations implement many common traits, includingAdd,Sub, and otherops traits. It implementsDefault by returning a zero-lengthDuration.
§Examples
usestd::time::Duration;letfive_seconds = Duration::new(5,0);letfive_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);letten_millis = Duration::from_millis(10);§FormattingDuration values
Duration intentionally does not have aDisplay impl, as there are avariety of ways to format spans of time for human readability.Durationprovides aDebug impl that shows the full precision of the value.
TheDebug output uses the non-ASCII “µs” suffix for microseconds. If yourprogram output may appear in contexts that cannot rely on full Unicodecompatibility, you may wish to formatDuration objects yourself or use acrate to do so.
Implementations§
Source§implDuration
implDuration
Sourcepub constSECOND:Duration
🔬This is a nightly-only experimental API. (duration_constants #57391)
pub constSECOND:Duration
duration_constants #57391)The duration of one second.
§Examples
Sourcepub constMILLISECOND:Duration
🔬This is a nightly-only experimental API. (duration_constants #57391)
pub constMILLISECOND:Duration
duration_constants #57391)The duration of one millisecond.
§Examples
Sourcepub constMICROSECOND:Duration
🔬This is a nightly-only experimental API. (duration_constants #57391)
pub constMICROSECOND:Duration
duration_constants #57391)The duration of one microsecond.
§Examples
Sourcepub constNANOSECOND:Duration
🔬This is a nightly-only experimental API. (duration_constants #57391)
pub constNANOSECOND:Duration
duration_constants #57391)The duration of one nanosecond.
§Examples
1.53.0 ·Sourcepub constMAX:Duration
pub constMAX:Duration
The maximum duration.
May vary by platform as necessary. Must be able to contain the difference betweentwo instances ofInstant or two instances ofSystemTime.This constraint gives it a value of about 584,942,417,355 years in practice,which is currently used on all platforms.
§Examples
1.3.0 (const: 1.58.0) ·Sourcepub const fnnew(secs:u64, nanos:u32) ->Duration
pub const fnnew(secs:u64, nanos:u32) ->Duration
Creates a newDuration from the specified number of whole seconds andadditional nanoseconds.
If the number of nanoseconds is greater than 1 billion (the number ofnanoseconds in a second), then it will carry over into the seconds provided.
§Panics
This constructor will panic if the carry from the nanoseconds overflowsthe seconds counter.
§Examples
1.3.0 (const: 1.32.0) ·Sourcepub const fnfrom_secs(secs:u64) ->Duration
pub const fnfrom_secs(secs:u64) ->Duration
Creates a newDuration from the specified number of whole seconds.
§Examples
1.3.0 (const: 1.32.0) ·Sourcepub const fnfrom_millis(millis:u64) ->Duration
pub const fnfrom_millis(millis:u64) ->Duration
Creates a newDuration from the specified number of milliseconds.
§Examples
1.27.0 (const: 1.32.0) ·Sourcepub const fnfrom_micros(micros:u64) ->Duration
pub const fnfrom_micros(micros:u64) ->Duration
Creates a newDuration from the specified number of microseconds.
§Examples
1.27.0 (const: 1.32.0) ·Sourcepub const fnfrom_nanos(nanos:u64) ->Duration
pub const fnfrom_nanos(nanos:u64) ->Duration
Creates a newDuration from the specified number of nanoseconds.
Note: Using this on the return value ofas_nanos() might cause unexpected behavior:as_nanos() returns a u128, and can return values that do not fit in u64, e.g. 585 years.Instead, consider using the patternDuration::new(d.as_secs(), d.subsec_nanos())if you cannot copy/clone the Duration directly.
§Examples
Sourcepub const fnfrom_nanos_u128(nanos:u128) ->Duration
🔬This is a nightly-only experimental API. (duration_from_nanos_u128 #139201)
pub const fnfrom_nanos_u128(nanos:u128) ->Duration
duration_from_nanos_u128 #139201)Creates a newDuration from the specified number of nanoseconds.
§Panics
Panics if the given number of nanoseconds is greater thanDuration::MAX.
§Examples
Sourcepub const fnfrom_weeks(weeks:u64) ->Duration
🔬This is a nightly-only experimental API. (duration_constructors #120301)
pub const fnfrom_weeks(weeks:u64) ->Duration
duration_constructors #120301)Sourcepub const fnfrom_days(days:u64) ->Duration
🔬This is a nightly-only experimental API. (duration_constructors #120301)
pub const fnfrom_days(days:u64) ->Duration
duration_constructors #120301)1.91.0 (const: 1.91.0) ·Sourcepub const fnfrom_hours(hours:u64) ->Duration
pub const fnfrom_hours(hours:u64) ->Duration
1.53.0 (const: 1.53.0) ·Sourcepub const fnis_zero(&self) ->bool
pub const fnis_zero(&self) ->bool
Returns true if thisDuration spans no time.
§Examples
usestd::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());1.3.0 (const: 1.32.0) ·Sourcepub const fnas_secs(&self) ->u64
pub const fnas_secs(&self) ->u64
Returns the number ofwhole seconds contained by thisDuration.
The returned value does not include the fractional (nanosecond) part of theduration, which can be obtained usingsubsec_nanos.
§Examples
To determine the total number of seconds represented by theDurationincluding the fractional part, useas_secs_f64 oras_secs_f32
1.27.0 (const: 1.32.0) ·Sourcepub const fnsubsec_millis(&self) ->u32
pub const fnsubsec_millis(&self) ->u32
Returns the fractional part of thisDuration, in whole milliseconds.
This method doesnot return the length of the duration whenrepresented by milliseconds. The returned number always represents afractional portion of a second (i.e., it is less than one thousand).
§Examples
1.27.0 (const: 1.32.0) ·Sourcepub const fnsubsec_micros(&self) ->u32
pub const fnsubsec_micros(&self) ->u32
Returns the fractional part of thisDuration, in whole microseconds.
This method doesnot return the length of the duration whenrepresented by microseconds. The returned number always represents afractional portion of a second (i.e., it is less than one million).
§Examples
1.3.0 (const: 1.32.0) ·Sourcepub const fnsubsec_nanos(&self) ->u32
pub const fnsubsec_nanos(&self) ->u32
Returns the fractional part of thisDuration, in nanoseconds.
This method doesnot return the length of the duration whenrepresented by nanoseconds. The returned number always represents afractional portion of a second (i.e., it is less than one billion).
§Examples
1.33.0 (const: 1.33.0) ·Sourcepub const fnas_millis(&self) ->u128
pub const fnas_millis(&self) ->u128
Returns the total number of whole milliseconds contained by thisDuration.
§Examples
1.33.0 (const: 1.33.0) ·Sourcepub const fnas_micros(&self) ->u128
pub const fnas_micros(&self) ->u128
Returns the total number of whole microseconds contained by thisDuration.
§Examples
1.33.0 (const: 1.33.0) ·Sourcepub const fnas_nanos(&self) ->u128
pub const fnas_nanos(&self) ->u128
Returns the total number of nanoseconds contained by thisDuration.
§Examples
1.81.0 (const: 1.81.0) ·Sourcepub const fnabs_diff(self, other:Duration) ->Duration
pub const fnabs_diff(self, other:Duration) ->Duration
Computes the absolute difference betweenself andother.
§Examples
1.16.0 (const: 1.58.0) ·Sourcepub const fnchecked_add(self, rhs:Duration) ->Option<Duration>
pub const fnchecked_add(self, rhs:Duration) ->Option<Duration>
1.53.0 (const: 1.58.0) ·Sourcepub const fnsaturating_add(self, rhs:Duration) ->Duration
pub const fnsaturating_add(self, rhs:Duration) ->Duration
SaturatingDuration addition. Computesself + other, returningDuration::MAXif overflow occurred.
§Examples
1.16.0 (const: 1.58.0) ·Sourcepub const fnchecked_sub(self, rhs:Duration) ->Option<Duration>
pub const fnchecked_sub(self, rhs:Duration) ->Option<Duration>
1.53.0 (const: 1.58.0) ·Sourcepub const fnsaturating_sub(self, rhs:Duration) ->Duration
pub const fnsaturating_sub(self, rhs:Duration) ->Duration
SaturatingDuration subtraction. Computesself - other, returningDuration::ZEROif the result would be negative or if overflow occurred.
§Examples
1.16.0 (const: 1.58.0) ·Sourcepub const fnchecked_mul(self, rhs:u32) ->Option<Duration>
pub const fnchecked_mul(self, rhs:u32) ->Option<Duration>
1.53.0 (const: 1.58.0) ·Sourcepub const fnsaturating_mul(self, rhs:u32) ->Duration
pub const fnsaturating_mul(self, rhs:u32) ->Duration
SaturatingDuration multiplication. Computesself * other, returningDuration::MAX if overflow occurred.
§Examples
1.16.0 (const: 1.58.0) ·Sourcepub const fnchecked_div(self, rhs:u32) ->Option<Duration>
pub const fnchecked_div(self, rhs:u32) ->Option<Duration>
1.38.0 (const: 1.83.0) ·Sourcepub const fnas_secs_f64(&self) ->f64
pub const fnas_secs_f64(&self) ->f64
Returns the number of seconds contained by thisDuration asf64.
The returned value includes the fractional (nanosecond) part of the duration.
§Examples
1.38.0 (const: 1.83.0) ·Sourcepub const fnas_secs_f32(&self) ->f32
pub const fnas_secs_f32(&self) ->f32
Returns the number of seconds contained by thisDuration asf32.
The returned value includes the fractional (nanosecond) part of the duration.
§Examples
Sourcepub const fnas_millis_f64(&self) ->f64
🔬This is a nightly-only experimental API. (duration_millis_float #122451)
pub const fnas_millis_f64(&self) ->f64
duration_millis_float #122451)Returns the number of milliseconds contained by thisDuration asf64.
The returned value includes the fractional (nanosecond) part of the duration.
§Examples
Sourcepub const fnas_millis_f32(&self) ->f32
🔬This is a nightly-only experimental API. (duration_millis_float #122451)
pub const fnas_millis_f32(&self) ->f32
duration_millis_float #122451)Returns the number of milliseconds contained by thisDuration asf32.
The returned value includes the fractional (nanosecond) part of the duration.
§Examples
1.38.0 ·Sourcepub fnfrom_secs_f64(secs:f64) ->Duration
pub fnfrom_secs_f64(secs:f64) ->Duration
Creates a newDuration from the specified number of seconds representedasf64.
§Panics
This constructor will panic ifsecs is negative, overflowsDuration or not finite.
§Examples
usestd::time::Duration;letres = Duration::from_secs_f64(0.0);assert_eq!(res, Duration::new(0,0));letres = Duration::from_secs_f64(1e-20);assert_eq!(res, Duration::new(0,0));letres = Duration::from_secs_f64(4.2e-7);assert_eq!(res, Duration::new(0,420));letres = Duration::from_secs_f64(2.7);assert_eq!(res, Duration::new(2,700_000_000));letres = Duration::from_secs_f64(3e10);assert_eq!(res, Duration::new(30_000_000_000,0));// subnormal floatletres = Duration::from_secs_f64(f64::from_bits(1));assert_eq!(res, Duration::new(0,0));// conversion uses roundingletres = Duration::from_secs_f64(0.999e-9);assert_eq!(res, Duration::new(0,1));1.38.0 ·Sourcepub fnfrom_secs_f32(secs:f32) ->Duration
pub fnfrom_secs_f32(secs:f32) ->Duration
Creates a newDuration from the specified number of seconds representedasf32.
§Panics
This constructor will panic ifsecs is negative, overflowsDuration or not finite.
§Examples
usestd::time::Duration;letres = Duration::from_secs_f32(0.0);assert_eq!(res, Duration::new(0,0));letres = Duration::from_secs_f32(1e-20);assert_eq!(res, Duration::new(0,0));letres = Duration::from_secs_f32(4.2e-7);assert_eq!(res, Duration::new(0,420));letres = Duration::from_secs_f32(2.7);assert_eq!(res, Duration::new(2,700_000_048));letres = Duration::from_secs_f32(3e10);assert_eq!(res, Duration::new(30_000_001_024,0));// subnormal floatletres = Duration::from_secs_f32(f32::from_bits(1));assert_eq!(res, Duration::new(0,0));// conversion uses roundingletres = Duration::from_secs_f32(0.999e-9);assert_eq!(res, Duration::new(0,1));1.38.0 ·Sourcepub fndiv_f32(self, rhs:f32) ->Duration
pub fndiv_f32(self, rhs:f32) ->Duration
1.80.0 (const: 1.83.0) ·Sourcepub const fndiv_duration_f64(self, rhs:Duration) ->f64
pub const fndiv_duration_f64(self, rhs:Duration) ->f64
DividesDuration byDuration and returnsf64.
§Examples
1.80.0 (const: 1.83.0) ·Sourcepub const fndiv_duration_f32(self, rhs:Duration) ->f32
pub const fndiv_duration_f32(self, rhs:Duration) ->f32
DividesDuration byDuration and returnsf32.
§Examples
Source§implDuration
implDuration
1.66.0 ·Sourcepub fntry_from_secs_f32(secs:f32) ->Result<Duration,TryFromFloatSecsError>
pub fntry_from_secs_f32(secs:f32) ->Result<Duration,TryFromFloatSecsError>
The checked version offrom_secs_f32.
This constructor will return anErr ifsecs is negative, overflowsDuration or not finite.
§Examples
usestd::time::Duration;letres = Duration::try_from_secs_f32(0.0);assert_eq!(res,Ok(Duration::new(0,0)));letres = Duration::try_from_secs_f32(1e-20);assert_eq!(res,Ok(Duration::new(0,0)));letres = Duration::try_from_secs_f32(4.2e-7);assert_eq!(res,Ok(Duration::new(0,420)));letres = Duration::try_from_secs_f32(2.7);assert_eq!(res,Ok(Duration::new(2,700_000_048)));letres = Duration::try_from_secs_f32(3e10);assert_eq!(res,Ok(Duration::new(30_000_001_024,0)));// subnormal float:letres = Duration::try_from_secs_f32(f32::from_bits(1));assert_eq!(res,Ok(Duration::new(0,0)));letres = Duration::try_from_secs_f32(-5.0);assert!(res.is_err());letres = Duration::try_from_secs_f32(f32::NAN);assert!(res.is_err());letres = Duration::try_from_secs_f32(2e19);assert!(res.is_err());// the conversion uses rounding with tie resolution to evenletres = Duration::try_from_secs_f32(0.999e-9);assert_eq!(res,Ok(Duration::new(0,1)));// this float represents exactly 976562.5e-9letval = f32::from_bits(0x3A80_0000);letres = Duration::try_from_secs_f32(val);assert_eq!(res,Ok(Duration::new(0,976_562)));// this float represents exactly 2929687.5e-9letval = f32::from_bits(0x3B40_0000);letres = Duration::try_from_secs_f32(val);assert_eq!(res,Ok(Duration::new(0,2_929_688)));// this float represents exactly 1.000_976_562_5letval = f32::from_bits(0x3F802000);letres = Duration::try_from_secs_f32(val);assert_eq!(res,Ok(Duration::new(1,976_562)));// this float represents exactly 1.002_929_687_5letval = f32::from_bits(0x3F806000);letres = Duration::try_from_secs_f32(val);assert_eq!(res,Ok(Duration::new(1,2_929_688)));1.66.0 ·Sourcepub fntry_from_secs_f64(secs:f64) ->Result<Duration,TryFromFloatSecsError>
pub fntry_from_secs_f64(secs:f64) ->Result<Duration,TryFromFloatSecsError>
The checked version offrom_secs_f64.
This constructor will return anErr ifsecs is negative, overflowsDuration or not finite.
§Examples
usestd::time::Duration;letres = Duration::try_from_secs_f64(0.0);assert_eq!(res,Ok(Duration::new(0,0)));letres = Duration::try_from_secs_f64(1e-20);assert_eq!(res,Ok(Duration::new(0,0)));letres = Duration::try_from_secs_f64(4.2e-7);assert_eq!(res,Ok(Duration::new(0,420)));letres = Duration::try_from_secs_f64(2.7);assert_eq!(res,Ok(Duration::new(2,700_000_000)));letres = Duration::try_from_secs_f64(3e10);assert_eq!(res,Ok(Duration::new(30_000_000_000,0)));// subnormal floatletres = Duration::try_from_secs_f64(f64::from_bits(1));assert_eq!(res,Ok(Duration::new(0,0)));letres = Duration::try_from_secs_f64(-5.0);assert!(res.is_err());letres = Duration::try_from_secs_f64(f64::NAN);assert!(res.is_err());letres = Duration::try_from_secs_f64(2e19);assert!(res.is_err());// the conversion uses rounding with tie resolution to evenletres = Duration::try_from_secs_f64(0.999e-9);assert_eq!(res,Ok(Duration::new(0,1)));letres = Duration::try_from_secs_f64(0.999_999_999_499);assert_eq!(res,Ok(Duration::new(0,999_999_999)));letres = Duration::try_from_secs_f64(0.999_999_999_501);assert_eq!(res,Ok(Duration::new(1,0)));letres = Duration::try_from_secs_f64(42.999_999_999_499);assert_eq!(res,Ok(Duration::new(42,999_999_999)));letres = Duration::try_from_secs_f64(42.999_999_999_501);assert_eq!(res,Ok(Duration::new(43,0)));// this float represents exactly 976562.5e-9letval = f64::from_bits(0x3F50_0000_0000_0000);letres = Duration::try_from_secs_f64(val);assert_eq!(res,Ok(Duration::new(0,976_562)));// this float represents exactly 2929687.5e-9letval = f64::from_bits(0x3F68_0000_0000_0000);letres = Duration::try_from_secs_f64(val);assert_eq!(res,Ok(Duration::new(0,2_929_688)));// this float represents exactly 1.000_976_562_5letval = f64::from_bits(0x3FF0_0400_0000_0000);letres = Duration::try_from_secs_f64(val);assert_eq!(res,Ok(Duration::new(1,976_562)));// this float represents exactly 1.002_929_687_5letval = f64::from_bits(0x3_FF00_C000_0000_000);letres = Duration::try_from_secs_f64(val);assert_eq!(res,Ok(Duration::new(1,2_929_688)));Trait Implementations§
1.9.0 (const:unstable) ·Source§implAddAssign forDuration
implAddAssign forDuration
Source§fnadd_assign(&mut self, rhs:Duration)
fnadd_assign(&mut self, rhs:Duration)
+= operation.Read more1.9.0 (const:unstable) ·Source§implDivAssign<u32> forDuration
implDivAssign<u32> forDuration
Source§fndiv_assign(&mut self, rhs:u32)
fndiv_assign(&mut self, rhs:u32)
/= operation.Read more1.9.0 (const:unstable) ·Source§implMulAssign<u32> forDuration
implMulAssign<u32> forDuration
Source§fnmul_assign(&mut self, rhs:u32)
fnmul_assign(&mut self, rhs:u32)
*= operation.Read more1.3.0 ·Source§implOrd forDuration
implOrd forDuration
1.3.0 ·Source§implPartialOrd forDuration
implPartialOrd forDuration
1.9.0 (const:unstable) ·Source§implSubAssign forDuration
implSubAssign forDuration
Source§fnsub_assign(&mut self, rhs:Duration)
fnsub_assign(&mut self, rhs:Duration)
-= operation.Read more