Struct Duration

#[non_exhaustive]
pub struct Duration { /* private fields */ }

Well-known duration representation for Google APIs.

Examples

let d = Duration::try_from("12.34s")?;
assert_eq!(d.seconds(), 12);
assert_eq!(d.nanos(), 340_000_000);
assert_eq!(d, Duration::new(12, 340_000_000)?);
assert_eq!(d, Duration::clamp(12, 340_000_000));

A Duration represents a signed, fixed-length span of time represented as a count of seconds and fractions of seconds at nanosecond resolution. It is independent of any calendar and concepts like “day” or “month”. It is related to Timestamp in that the difference between two Timestamp values is a Duration and it can be added or subtracted from a Timestamp. Range is approximately +-10,000 years.

JSON Mapping

In JSON format, the Duration type is encoded as a string rather than an object, where the string ends in the suffix “s” (indicating seconds) and is preceded by the number of seconds, with nanoseconds expressed as fractional seconds. For example, 3 seconds with 0 nanoseconds should be encoded in JSON format as “3s”, while 3 seconds and 1 nanosecond should be expressed in JSON format as “3.000000001s”, and 3 seconds and 1 microsecond should be expressed in JSON format as “3.000001s”.

Implementations

impl Duration

pub const MAX_SECONDS: i64 = 315_576_000_000i64

The maximum value for the seconds component, approximately 10,000 years.

pub const MIN_SECONDS: i64 = -315_576_000_000i64

The minimum value for the seconds component, approximately -10,000 years.

pub const MAX_NANOS: i32 = 999_999_999i32

The maximum value for the nanos component.

pub const MIN_NANOS: i32 = -999_999_999i32

The minimum value for the nanos component.

pub fn new(seconds: i64, nanos: i32) -> Result<Self, DurationError>

Creates a Duration from the seconds and nanoseconds component.

Examples

let d = Duration::new(12, 340_000_000)?;
assert_eq!(String::from(d), "12.34s");

let d = Duration::new(-12, -340_000_000)?;
assert_eq!(String::from(d), "-12.34s");

Examples: invalid inputs

let d = Duration::new(12, 2_000_000_000);
assert!(matches!(d, Err(DurationError::OutOfRange)));

let d = Duration::new(-12, 340_000_000);
assert!(matches!(d, Err(DurationError::MismatchedSigns)));

This function validates the seconds and nanos components and returns an error if either are out of range or their signs do not match. Consider using clamp() to add nanoseconds to seconds with carry.

Parameters

• seconds - the seconds in the interval.
• nanos - the nanoseconds added to the interval.

pub fn clamp(seconds: i64, nanos: i32) -> Self

Create a normalized, clamped Duration.

Examples

let d = Duration::clamp(12, 340_000_000);
assert_eq!(String::from(d), "12.34s");
let d = Duration::clamp(10, 2_000_000_000);
assert_eq!(String::from(d), "12s");

Durations must be in the [-10_000, +10_000] year range, the nanoseconds field must be in the [-999_999_999, +999_999_999] range, and the seconds and nanosecond fields must have the same sign. This function creates a new Duration instance clamped to those ranges.

The function effectively adds the nanoseconds part (with carry) to the seconds part, with saturation.

Parameters

• seconds - the seconds in the interval.
• nanos - the nanoseconds added to the interval.

pub fn seconds(&self) -> i64

Returns the seconds part of the duration.

Example

let d = Duration::clamp(12, 34);
assert_eq!(d.seconds(), 12);

pub fn nanos(&self) -> i32

Returns the sub-second part of the duration.

Example

let d = Duration::clamp(12, 34);
assert_eq!(d.nanos(), 34);

Trait Implementations

impl Clone for Duration

fn clone(&self) -> Duration

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Duration

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Duration

fn default() -> Duration

Returns the “default value” for a type.

impl From<Duration> for Duration

Available on crate feature time only.

Convert from Duration to time::Duration.

This conversion is always safe because the range for Duration is guaranteed to fit into the destination type.

Example

let d = time::Duration::from(Duration::clamp(12, 340_000_000));
assert_eq!(d.whole_seconds(), 12);
assert_eq!(d.subsec_nanoseconds(), 340_000_000);

fn from(value: Duration) -> Self

Converts to this type from the input type.

impl From<Duration> for String

Converts a Duration to its String representation.

Example

let d = Duration::clamp(12, 340_000_000);
assert_eq!(String::from(d), "12.34s");

fn from(duration: Duration) -> String

Converts to this type from the input type.

impl From<Duration> for Duration

Available on crate feature chrono only.

Converts from Duration to chrono::Duration.

Example

let d = chrono::Duration::from(Duration::clamp(12, 340_000_000));
assert_eq!(d.num_seconds(), 12);
assert_eq!(d.subsec_nanos(), 340_000_000);

fn from(value: Duration) -> Self

Converts to this type from the input type.

impl Message for Duration

fn typename() -> &'static str

The typename of this message.

impl PartialEq for Duration

fn eq(&self, other: &Duration) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Duration

fn partial_cmp(&self, other: &Duration) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl TryFrom<&String> for Duration

Converts the string representation of a duration to Duration.

Example

let s = "12.34s".to_string();
let d = Duration::try_from(&s)?;
assert_eq!(d.seconds(), 12);
assert_eq!(d.nanos(), 340_000_000);

type Error = DurationError

The type returned in the event of a conversion error.

fn try_from(value: &String) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&str> for Duration

Converts the string representation of a duration to Duration.

Example

let d = Duration::try_from("12.34s")?;
assert_eq!(d.seconds(), 12);
assert_eq!(d.nanos(), 340_000_000);

type Error = DurationError

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Duration> for Duration

Convert from std::time::Duration to Duration.

Example

let d = Duration::try_from(std::time::Duration::from_secs(123))?;
assert_eq!(d.seconds(), 123);
assert_eq!(d.nanos(), 0);

type Error = DurationError

The type returned in the event of a conversion error.

fn try_from(value: Duration) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Duration> for Duration

Convert from Duration to std::time::Duration.

Returns an error if value is negative, as std::time::Duration cannot represent negative durations.

Example

let d = Duration::new(12, 340_000_000)?;
let duration = std::time::Duration::try_from(d)?;
assert_eq!(duration.as_secs(), 12);
assert_eq!(duration.subsec_nanos(), 340_000_000);

type Error = DurationError

The type returned in the event of a conversion error.

fn try_from(value: Duration) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Duration> for Duration

Available on crate feature time only.

Convert from time::Duration to Duration.

This conversion may fail if the time::Duration value is out of range.

Example

let d = Duration::try_from(time::Duration::new(12, 340_000_000))?;
assert_eq!(d.seconds(), 12);
assert_eq!(d.nanos(), 340_000_000);

type Error = DurationError

The type returned in the event of a conversion error.

fn try_from(value: Duration) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<TimeDelta> for Duration

Available on crate feature chrono only.

Converts from chrono::Duration to Duration.

The conversion may fail if the input value is out of range.

Example

let d = Duration::try_from(chrono::Duration::new(12, 340_000_000).unwrap())?;
assert_eq!(d.seconds(), 12);
assert_eq!(d.nanos(), 340_000_000);

type Error = DurationError

The type returned in the event of a conversion error.

fn try_from(value: Duration) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for Duration

impl StructuralPartialEq for Duration