diff options
Diffstat (limited to 'ctr-std/src/time/duration.rs')
| -rw-r--r-- | ctr-std/src/time/duration.rs | 247 |
1 files changed, 207 insertions, 40 deletions
diff --git a/ctr-std/src/time/duration.rs b/ctr-std/src/time/duration.rs index 41d675b..cb5bfb9 100644 --- a/ctr-std/src/time/duration.rs +++ b/ctr-std/src/time/duration.rs @@ -1,4 +1,4 @@ -// Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT +// Copyright 2012-2017 The Rust Project Developers. See the COPYRIGHT // file at the top-level directory of this distribution and at // http://rust-lang.org/COPYRIGHT. // @@ -8,22 +8,29 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +use iter::Sum; use ops::{Add, Sub, Mul, Div, AddAssign, SubAssign, MulAssign, DivAssign}; const NANOS_PER_SEC: u32 = 1_000_000_000; const NANOS_PER_MILLI: u32 = 1_000_000; +const NANOS_PER_MICRO: u32 = 1_000; const MILLIS_PER_SEC: u64 = 1_000; +const MICROS_PER_SEC: u64 = 1_000_000; -/// A duration type to represent a span of time, typically used for system +/// A `Duration` type to represent a span of time, typically used for system /// timeouts. /// -/// Each duration is composed of a number of seconds and nanosecond precision. -/// APIs binding a system timeout will typically round up the nanosecond -/// precision if the underlying system does not support that level of precision. +/// Each `Duration` is composed of a whole number of seconds and a fractional part +/// represented in nanoseconds. If the underlying system does not support +/// nanosecond-level precision, APIs binding a system timeout will typically round up +/// the number of nanoseconds. /// -/// Durations implement many common traits, including `Add`, `Sub`, and other -/// ops traits. Currently a duration may only be inspected for its number of -/// seconds and its nanosecond precision. +/// `Duration`s implement many common traits, including [`Add`], [`Sub`], and other +/// [`ops`] traits. +/// +/// [`Add`]: ../../std/ops/trait.Add.html +/// [`Sub`]: ../../std/ops/trait.Sub.html +/// [`ops`]: ../../std/ops/index.html /// /// # Examples /// @@ -46,16 +53,24 @@ pub struct Duration { } impl Duration { - /// Creates a new `Duration` from the specified number of seconds and - /// additional nanosecond precision. + /// Creates a new `Duration` from the specified number of whole seconds and + /// additional nanoseconds. /// - /// If the nanoseconds is greater than 1 billion (the number of nanoseconds - /// in a second), then it will carry over into the seconds provided. + /// If the number of nanoseconds is greater than 1 billion (the number of + /// nanoseconds in a second), then it will carry over into the seconds provided. /// /// # Panics /// /// This constructor will panic if the carry from the nanoseconds overflows /// the seconds counter. + /// + /// # Examples + /// + /// ``` + /// use std::time::Duration; + /// + /// let five_seconds = Duration::new(5, 0); + /// ``` #[stable(feature = "duration", since = "1.3.0")] #[inline] pub fn new(secs: u64, nanos: u32) -> Duration { @@ -65,7 +80,18 @@ impl Duration { Duration { secs: secs, nanos: nanos } } - /// Creates a new `Duration` from the specified number of seconds. + /// Creates a new `Duration` from the specified number of whole seconds. + /// + /// # Examples + /// + /// ``` + /// use std::time::Duration; + /// + /// let duration = Duration::from_secs(5); + /// + /// assert_eq!(5, duration.as_secs()); + /// assert_eq!(0, duration.subsec_nanos()); + /// ``` #[stable(feature = "duration", since = "1.3.0")] #[inline] pub fn from_secs(secs: u64) -> Duration { @@ -73,6 +99,17 @@ impl Duration { } /// Creates a new `Duration` from the specified number of milliseconds. + /// + /// # Examples + /// + /// ``` + /// use std::time::Duration; + /// + /// let duration = Duration::from_millis(2569); + /// + /// assert_eq!(2, duration.as_secs()); + /// assert_eq!(569_000_000, duration.subsec_nanos()); + /// ``` #[stable(feature = "duration", since = "1.3.0")] #[inline] pub fn from_millis(millis: u64) -> Duration { @@ -81,39 +118,155 @@ impl Duration { Duration { secs: secs, nanos: nanos } } - /// Returns the number of whole seconds represented by this duration. + /// Creates a new `Duration` from the specified number of microseconds. + /// + /// # Examples + /// + /// ``` + /// #![feature(duration_from_micros)] + /// use std::time::Duration; + /// + /// let duration = Duration::from_micros(1_000_002); + /// + /// assert_eq!(1, duration.as_secs()); + /// assert_eq!(2000, duration.subsec_nanos()); + /// ``` + #[unstable(feature = "duration_from_micros", issue = "44400")] + #[inline] + pub fn from_micros(micros: u64) -> Duration { + let secs = micros / MICROS_PER_SEC; + let nanos = ((micros % MICROS_PER_SEC) as u32) * NANOS_PER_MICRO; + Duration { secs: secs, nanos: nanos } + } + + /// Creates a new `Duration` from the specified number of nanoseconds. + /// + /// # Examples + /// + /// ``` + /// #![feature(duration_extras)] + /// use std::time::Duration; + /// + /// let duration = Duration::from_nanos(1_000_000_123); + /// + /// assert_eq!(1, duration.as_secs()); + /// assert_eq!(123, duration.subsec_nanos()); + /// ``` + #[unstable(feature = "duration_extras", issue = "46507")] + #[inline] + pub fn from_nanos(nanos: u64) -> Duration { + let secs = nanos / (NANOS_PER_SEC as u64); + let nanos = (nanos % (NANOS_PER_SEC as u64)) as u32; + Duration { secs: secs, nanos: nanos } + } + + /// Returns the number of _whole_ seconds contained by this `Duration`. + /// + /// The returned value does not include the fractional (nanosecond) part of the + /// duration, which can be obtained using [`subsec_nanos`]. + /// + /// # Examples + /// + /// ``` + /// use std::time::Duration; + /// + /// let duration = Duration::new(5, 730023852); + /// assert_eq!(duration.as_secs(), 5); + /// ``` + /// + /// To determine the total number of seconds represented by the `Duration`, + /// use `as_secs` in combination with [`subsec_nanos`]: + /// + /// ``` + /// use std::time::Duration; /// - /// The extra precision represented by this duration is ignored (i.e. extra - /// nanoseconds are not represented in the returned value). + /// let duration = Duration::new(5, 730023852); + /// + /// assert_eq!(5.730023852, + /// duration.as_secs() as f64 + /// + duration.subsec_nanos() as f64 * 1e-9); + /// ``` + /// + /// [`subsec_nanos`]: #method.subsec_nanos #[stable(feature = "duration", since = "1.3.0")] #[inline] pub fn as_secs(&self) -> u64 { self.secs } - /// Returns the nanosecond precision represented by this duration. + /// Returns the fractional part of this `Duration`, in milliseconds. + /// + /// This method does **not** return the length of the duration when + /// represented by milliseconds. The returned number always represents a + /// fractional portion of a second (i.e. it is less than one thousand). + /// + /// # Examples + /// + /// ``` + /// #![feature(duration_extras)] + /// use std::time::Duration; + /// + /// let duration = Duration::from_millis(5432); + /// assert_eq!(duration.as_secs(), 5); + /// assert_eq!(duration.subsec_millis(), 432); + /// ``` + #[unstable(feature = "duration_extras", issue = "46507")] + #[inline] + pub fn subsec_millis(&self) -> u32 { self.nanos / NANOS_PER_MILLI } + + /// Returns the fractional part of this `Duration`, in microseconds. + /// + /// This method does **not** return the length of the duration when + /// represented by microseconds. The returned number always represents a + /// fractional portion of a second (i.e. it is less than one million). + /// + /// # Examples + /// + /// ``` + /// #![feature(duration_extras, duration_from_micros)] + /// use std::time::Duration; + /// + /// let duration = Duration::from_micros(1_234_567); + /// assert_eq!(duration.as_secs(), 1); + /// assert_eq!(duration.subsec_micros(), 234_567); + /// ``` + #[unstable(feature = "duration_extras", issue = "46507")] + #[inline] + pub fn subsec_micros(&self) -> u32 { self.nanos / NANOS_PER_MICRO } + + /// Returns the fractional part of this `Duration`, in nanoseconds. /// /// This method does **not** return the length of the duration when /// represented by nanoseconds. The returned number always represents a /// fractional portion of a second (i.e. it is less than one billion). + /// + /// # Examples + /// + /// ``` + /// use std::time::Duration; + /// + /// let duration = Duration::from_millis(5010); + /// assert_eq!(duration.as_secs(), 5); + /// assert_eq!(duration.subsec_nanos(), 10_000_000); + /// ``` #[stable(feature = "duration", since = "1.3.0")] #[inline] pub fn subsec_nanos(&self) -> u32 { self.nanos } - /// Checked duration addition. Computes `self + other`, returning `None` + /// Checked `Duration` addition. Computes `self + other`, returning [`None`] /// if overflow occurred. /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None + /// /// # Examples /// /// Basic usage: /// /// ``` - /// #![feature(duration_checked_ops)] - /// /// use std::time::Duration; /// /// assert_eq!(Duration::new(0, 0).checked_add(Duration::new(0, 1)), Some(Duration::new(0, 1))); /// assert_eq!(Duration::new(1, 0).checked_add(Duration::new(std::u64::MAX, 0)), None); /// ``` - #[unstable(feature = "duration_checked_ops", issue = "35774")] + #[stable(feature = "duration_checked_ops", since = "1.16.0")] #[inline] pub fn checked_add(self, rhs: Duration) -> Option<Duration> { if let Some(mut secs) = self.secs.checked_add(rhs.secs) { @@ -128,30 +281,30 @@ impl Duration { } debug_assert!(nanos < NANOS_PER_SEC); Some(Duration { - secs: secs, - nanos: nanos, + secs, + nanos, }) } else { None } } - /// Checked duration subtraction. Computes `self + other`, returning `None` - /// if the result would be negative or if underflow occurred. + /// Checked `Duration` subtraction. Computes `self - other`, returning [`None`] + /// if the result would be negative or if overflow occurred. + /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples /// /// Basic usage: /// /// ``` - /// #![feature(duration_checked_ops)] - /// /// use std::time::Duration; /// /// assert_eq!(Duration::new(0, 1).checked_sub(Duration::new(0, 0)), Some(Duration::new(0, 1))); /// assert_eq!(Duration::new(0, 0).checked_sub(Duration::new(0, 1)), None); /// ``` - #[unstable(feature = "duration_checked_ops", issue = "35774")] + #[stable(feature = "duration_checked_ops", since = "1.16.0")] #[inline] pub fn checked_sub(self, rhs: Duration) -> Option<Duration> { if let Some(mut secs) = self.secs.checked_sub(rhs.secs) { @@ -172,22 +325,22 @@ impl Duration { } } - /// Checked duration multiplication. Computes `self * other`, returning - /// `None` if underflow or overflow occurred. + /// Checked `Duration` multiplication. Computes `self * other`, returning + /// [`None`] if overflow occurred. + /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples /// /// Basic usage: /// /// ``` - /// #![feature(duration_checked_ops)] - /// /// use std::time::Duration; /// /// assert_eq!(Duration::new(0, 500_000_001).checked_mul(2), Some(Duration::new(1, 2))); /// assert_eq!(Duration::new(std::u64::MAX - 1, 0).checked_mul(2), None); /// ``` - #[unstable(feature = "duration_checked_ops", issue = "35774")] + #[stable(feature = "duration_checked_ops", since = "1.16.0")] #[inline] pub fn checked_mul(self, rhs: u32) -> Option<Duration> { // Multiply nanoseconds as u64, because it cannot overflow that way. @@ -199,31 +352,31 @@ impl Duration { .and_then(|s| s.checked_add(extra_secs)) { debug_assert!(nanos < NANOS_PER_SEC); Some(Duration { - secs: secs, - nanos: nanos, + secs, + nanos, }) } else { None } } - /// Checked duration division. Computes `self / other`, returning `None` - /// if `other == 0` or the operation results in underflow or overflow. + /// Checked `Duration` division. Computes `self / other`, returning [`None`] + /// if `other == 0`. + /// + /// [`None`]: ../../std/option/enum.Option.html#variant.None /// /// # Examples /// /// Basic usage: /// /// ``` - /// #![feature(duration_checked_ops)] - /// /// 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); /// ``` - #[unstable(feature = "duration_checked_ops", issue = "35774")] + #[stable(feature = "duration_checked_ops", since = "1.16.0")] #[inline] pub fn checked_div(self, rhs: u32) -> Option<Duration> { if rhs != 0 { @@ -303,6 +456,20 @@ impl DivAssign<u32> for Duration { } } +#[stable(feature = "duration_sum", since = "1.16.0")] +impl Sum for Duration { + fn sum<I: Iterator<Item=Duration>>(iter: I) -> Duration { + iter.fold(Duration::new(0, 0), |a, b| a + b) + } +} + +#[stable(feature = "duration_sum", since = "1.16.0")] +impl<'a> Sum<&'a Duration> for Duration { + fn sum<I: Iterator<Item=&'a Duration>>(iter: I) -> Duration { + iter.fold(Duration::new(0, 0), |a, b| a + *b) + } +} + #[cfg(test)] mod tests { use super::Duration; |