Update docs and tests based on std

Author: taiki-e

.github/workflows/ci.yml

@@ -22,11 +22,13 @@ jobs:
   test:
     strategy:
       matrix:
-        rust:
-          - stable
-          - beta
-          - nightly
-    runs-on: ubuntu-latest
+        include:
+          - rust: stable
+          - rust: beta
+          - rust: nightly
+          - rust: nightly
+            os: macos-latest
+    runs-on: ${{ matrix.os || 'ubuntu-latest' }}
     steps:
       - uses: actions/checkout@v2
       - uses: taiki-e/github-actions/install-rust@main

Cargo.toml

@@ -30,3 +30,6 @@ autocfg = "1"
 
 [dependencies]
 const_fn = "0.4"
+
+[dev-dependencies]
+rustversion = "1"

src/duration.rs

@@ -26,6 +26,11 @@ use super::{pair_and_then, TryFromTimeError};
 pub struct Duration(pub(crate) Option<time::Duration>);
 
 impl Duration {
+    // TODO: duration_constants https://github.com/rust-lang/rust/issues/57391
+    // TODO: duration_zero https://github.com/rust-lang/rust/issues/73544
+    // TODO: duration_float https://github.com/rust-lang/rust/issues/54361
+    // TODO: div_duration https://github.com/rust-lang/rust/issues/63139
+
     /// Creates a new `Duration` from the specified number of whole seconds and
     /// additional nanoseconds.
     ///
@@ -149,9 +154,6 @@ impl Duration {
         }
     }
 
-    // TODO: duration_float https://github.com/rust-lang/rust/issues/54361
-    // TODO: div_duration https://github.com/rust-lang/rust/issues/63139
-
     // =============================================================================
     // Option based method implementations
 

src/instant.rs

@@ -27,6 +27,33 @@ use super::{pair_and_then, Duration, TryFromTimeError};
 ///
 /// The size of an `Instant` struct may vary depending on the target operating
 /// system.
+///
+/// # OS-specific behaviors
+///
+/// An `Instant` is a wrapper around system-specific types and it may behave
+/// differently depending on the underlying operating system. For example,
+/// the following snippet is fine on Linux but fails and returns `None` on macOS.
+/// ():
+///
+/// ```
+/// use easytime::{Duration, Instant};
+///
+/// let now = Instant::now();
+/// let max_nanoseconds = u64::MAX / 1_000_000_000;
+/// let duration = Duration::new(max_nanoseconds, 0);
+/// // Unlike `std::time::Instant`, it won't panic!
+/// let result = now + duration;
+///
+/// #[cfg(target_os = "linux")]
+/// assert!(result.is_some());
+/// #[cfg(target_os = "macos")]
+/// assert!(result.is_none());
+/// ```
+///
+/// # Underlying System calls
+///
+/// See the [standard library documentation](std::time::Instant#underlying-system-calls)
+/// for the system calls used to get the current time using `now()`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct Instant(Option<time::Instant>);
 

src/lib.rs

@@ -52,7 +52,10 @@
 #![cfg_attr(not(feature = "std"), no_std)]
 #![doc(test(
     no_crate_inject,
-    attr(deny(warnings, rust_2018_idioms, single_use_lifetimes), allow(dead_code))
+    attr(
+        deny(warnings, rust_2018_idioms, single_use_lifetimes),
+        allow(dead_code, unused_variables)
+    )
 ))]
 #![forbid(unsafe_code)]
 #![warn(future_incompatible, rust_2018_idioms, single_use_lifetimes, unreachable_pub)]

tests/duration.rs

@@ -1,7 +1,8 @@
 #![warn(rust_2018_idioms, single_use_lifetimes)]
 #![allow(clippy::zero_prefixed_literal)]
+#![allow(clippy::non_ascii_literal)]
 
-// https://github.com/rust-lang/rust/blob/master/src/libcore/tests/time.rs
+// https://github.com/rust-lang/rust/blob/1.49.0/library/core/tests/time.rs
 
 use core::time;
 use easytime::Duration;
@@ -294,3 +295,95 @@ fn debug_formatting_precision_high() {
 fn debug_formatting_none() {
     assert_eq!(format!("{:?}", Duration::new(0, 0) - Duration::new(0, 1)), "None");
 }
+
+const fn duration_second() -> Duration {
+    Duration::from_secs(1)
+}
+
+#[rustversion::since(1.46)]
+#[test]
+fn duration_const() {
+    // test that the methods of `Duration` are usable in a const context
+
+    const DURATION: Duration = Duration::from_nanos(123_456_789);
+
+    const SUB_SEC_MILLIS: Option<u32> = DURATION.subsec_millis();
+    assert_eq!(SUB_SEC_MILLIS, Some(123));
+
+    const SUB_SEC_MICROS: Option<u32> = DURATION.subsec_micros();
+    assert_eq!(SUB_SEC_MICROS, Some(123_456));
+
+    const SUB_SEC_NANOS: Option<u32> = DURATION.subsec_nanos();
+    assert_eq!(SUB_SEC_NANOS, Some(123_456_789));
+
+    // const IS_ZERO: bool = Duration::ZERO.is_zero();
+    // assert!(IS_ZERO);
+
+    const SECONDS: Option<u64> = duration_second().as_secs();
+    assert_eq!(SECONDS, Some(1));
+
+    const FROM_SECONDS: Duration = Duration::from_secs(1);
+    assert_eq!(FROM_SECONDS, duration_second());
+
+    // const SECONDS_F32: Option<f32> = duration_second().as_secs_f32();
+    // assert_eq!(SECONDS_F32, Some(1.0));
+
+    // const FROM_SECONDS_F32: Duration = Duration::from_secs_f32(1.0);
+    // assert_eq!(FROM_SECONDS_F32, duration_second);
+
+    // const SECONDS_F64: f64 = duration_second().as_secs_f64();
+    // assert_eq!(SECONDS_F64, 1.0);
+
+    // const FROM_SECONDS_F64: Duration = Duration::from_secs_f64(1.0);
+    // assert_eq!(FROM_SECONDS_F64, duration_second());
+
+    const MILLIS: Option<u128> = duration_second().as_millis();
+    assert_eq!(MILLIS, Some(1_000));
+
+    const FROM_MILLIS: Duration = Duration::from_millis(1_000);
+    assert_eq!(FROM_MILLIS, duration_second());
+
+    const MICROS: Option<u128> = duration_second().as_micros();
+    assert_eq!(MICROS, Some(1_000_000));
+
+    const FROM_MICROS: Duration = Duration::from_micros(1_000_000);
+    assert_eq!(FROM_MICROS, duration_second());
+
+    const NANOS: Option<u128> = duration_second().as_nanos();
+    assert_eq!(NANOS, Some(1_000_000_000));
+
+    const FROM_NANOS: Duration = Duration::from_nanos(1_000_000_000);
+    assert_eq!(FROM_NANOS, duration_second());
+
+    // const MAX: Duration = Duration::new(u64::MAX, 999_999_999);
+
+    // const ADD: Duration = MAX + duration_second();
+    // assert_eq!(ADD.into_inner(), None);
+
+    // const SUB: Duration = Duration::ZERO - duration_second();
+    // assert_eq!(SUB.into_inner(), None);
+
+    // const MUL: Duration = duration_second() * 1;
+    // assert_eq!(MUL, duration_second());
+
+    // const MUL_F32: Duration = duration_second().mul_f32(1.0);
+    // assert_eq!(MUL_F32, duration_second());
+
+    // const MUL_F64: Duration = duration_second().mul_f64(1.0);
+    // assert_eq!(MUL_F64, duration_second());
+
+    // const DIV: Duration = duration_second() / 1;
+    // assert_eq!(DIV, duration_second());
+
+    // const DIV_F32: Duration = duration_second().div_f32(1.0);
+    // assert_eq!(DIV_F32, duration_second());
+
+    // const DIV_F64: Duration = duration_second().div_f64(1.0);
+    // assert_eq!(DIV_F64, duration_second());
+
+    // const DIV_DURATION_F32: f32 = duration_second().div_duration_f32(duration_second());
+    // assert_eq!(DIV_DURATION_F32, 1.0);
+
+    // const DIV_DURATION_F64: f64 = duration_second().div_duration_f64(duration_second());
+    // assert_eq!(DIV_DURATION_F64, 1.0);
+}

tests/instant.rs

@@ -2,7 +2,7 @@
 #![warn(rust_2018_idioms, single_use_lifetimes)]
 #![allow(clippy::eq_op)]
 
-// https://github.com/rust-lang/rust/blob/master/src/libstd/time.rs
+// https://github.com/rust-lang/rust/blob/1.49.0/library/std/src/time/tests.rs
 
 use easytime::{Duration, Instant};
 
@@ -11,7 +11,7 @@ macro_rules! assert_almost_eq {
         let (a, b) = ($a, $b);
         if a != b {
             let (a, b) = if a > b { (a, b) } else { (b, a) };
-            assert!(a - Duration::new(0, 1000) <= b, "{:?} is not almost equal to {:?}", a, b);
+            assert!(a - Duration::from_micros(1) <= b, "{:?} is not almost equal to {:?}", a, b);
         }
     }};
 }