v0.3 backports

Author: jhpratt

CHANGELOG.md

@@ -7,6 +7,25 @@ Versioning].
 
 ---
 
+## 0.2.23 [2020-11-17]
+
+## Compatibility notes
+
+Due to #293, any method that requires knowledge of the local offset will now
+_fail_ on Linux. For `try_` methods, this means returning an error. For others,
+it means assuming UTC.
+
+### Deprecated
+
+- `UtcOffset::timestamp` (moved to `UtcOffset::unix_timestamp`)
+- `UtcOffset::timestamp_nanos` (moved to `UtcOffset::unix_timestamp_nanos`)
+- `date` (moved to `macros::date`)
+- `time` (moved to `macros::time`)
+- `offset` (moved to `macros::offset`)
+- `OffsetDateTime::now_local` (assumes UTC if unable to be determined)
+- `UtcOffset::local_offset_at` (assumes UTC if unable to be determined)
+- `UtcOffset::current_local_offset` (assumes UTC if unable to be determined)
+
 ## 0.2.22 [2020-09-25]
 
 ### Fixed

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "time"
-version = "0.2.22"
+version = "0.2.23"
 authors = ["Jacob Pratt <[email protected]>"]
 edition = "2018"
 repository = "https://github.com/time-rs/time"

src/format/format.rs

@@ -9,6 +9,7 @@ use alloc::{borrow::ToOwned, string::String};
 #[cfg_attr(__time_02_supports_non_exhaustive, non_exhaustive)]
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum Format {
+    #[cfg_attr(__time_02_docs, doc(alias = "ISO8601"))]
     Rfc3339,
     Custom(String),
     #[cfg(not(__time_02_supports_non_exhaustive))]

src/lib.rs

@@ -311,90 +311,42 @@ mod weekday;
 
 pub use date::Date;
 pub use duration::Duration;
+pub use error::Error;
+#[deprecated(
+    since = "0.2.23",
+    note = "Errors have been moved to the `error` module."
+)]
 pub use error::{
-    ComponentRange as ComponentRangeError, ConversionRange as ConversionRangeError, Error,
+    ComponentRange as ComponentRangeError, ConversionRange as ConversionRangeError,
     IndeterminateOffset as IndeterminateOffsetError, Parse as ParseError,
 };
+#[deprecated(
+    since = "0.2.23",
+    note = "Extension traits have been moved to the `ext` module."
+)]
 pub use ext::{NumericalDuration, NumericalStdDuration, NumericalStdDurationShort};
 pub(crate) use format::DeferredFormat;
 pub use format::Format;
 use format::ParseResult;
 #[cfg(feature = "std")]
 pub use instant::Instant;
+#[deprecated(
+    since = "0.2.23",
+    note = "Macros have been moved to the `macros` module."
+)]
+pub use macros::{date, offset, time};
 pub use offset_date_time::OffsetDateTime;
 pub use primitive_date_time::PrimitiveDateTime;
 #[allow(deprecated)]
 pub use sign::Sign;
 #[allow(unused_imports)]
 use standback::prelude::*;
-/// Construct a [`Date`](crate::Date) with a statically known value.
-///
-/// The resulting expression can be used in `const` or `static` declarations.
-///
-/// Three formats are supported: year-week-weekday, year-ordinal, and
-/// year-month-day.
-///
-/// ```rust
-/// # use time::{Date, date, Weekday::*};
-/// # fn main() -> time::Result<()> {
-/// assert_eq!(date!(2020-W01-3), Date::try_from_iso_ywd(2020, 1, Wednesday)?);
-/// assert_eq!(date!(2020-001), Date::try_from_yo(2020, 1)?);
-/// assert_eq!(date!(2020-01-01), Date::try_from_ymd(2020, 1, 1)?);
-/// # Ok(())
-/// # }
-/// ```
-pub use time_macros::date;
-/// Construct a [`UtcOffset`](crate::UtcOffset) with a statically known value.
-///
-/// The resulting expression can be used in `const` or `static` declarations.
-///
-/// A sign and the hour must be provided; minutes and seconds default to zero.
-/// `UTC` (both uppercase and lowercase) is also allowed.
-///
-/// ```rust
-/// # use time::{offset, UtcOffset};
-/// assert_eq!(offset!(UTC), UtcOffset::hours(0));
-/// assert_eq!(offset!(utc), UtcOffset::hours(0));
-/// assert_eq!(offset!(+0), UtcOffset::hours(0));
-/// assert_eq!(offset!(+1), UtcOffset::hours(1));
-/// assert_eq!(offset!(-1), UtcOffset::hours(-1));
-/// assert_eq!(offset!(+1:30), UtcOffset::minutes(90));
-/// assert_eq!(offset!(-1:30), UtcOffset::minutes(-90));
-/// assert_eq!(offset!(+1:30:59), UtcOffset::seconds(5459));
-/// assert_eq!(offset!(-1:30:59), UtcOffset::seconds(-5459));
-/// assert_eq!(offset!(+23:59:59), UtcOffset::seconds(86_399));
-/// assert_eq!(offset!(-23:59:59), UtcOffset::seconds(-86_399));
-/// ```
-pub use time_macros::offset;
-/// Construct a [`Time`](crate::Time) with a statically known value.
-///
-/// The resulting expression can be used in `const` or `static` declarations.
-///
-/// Hours and minutes must be provided, while seconds defaults to zero. AM/PM is
-/// allowed (either uppercase or lowercase). Any number of subsecond digits may
-/// be provided (though any past nine will be discarded).
-///
-/// All components are validated at compile-time. An error will be raised if any
-/// value is invalid.
-///
-/// ```rust
-/// # use time::{Time, time};
-/// # fn main() -> time::Result<()> {
-/// assert_eq!(time!(0:00), Time::try_from_hms(0, 0, 0)?);
-/// assert_eq!(time!(1:02:03), Time::try_from_hms(1, 2, 3)?);
-/// assert_eq!(time!(1:02:03.004_005_006), Time::try_from_hms_nano(1, 2, 3, 4_005_006)?);
-/// assert_eq!(time!(12:00 am), Time::try_from_hms(0, 0, 0)?);
-/// assert_eq!(time!(1:02:03 am), Time::try_from_hms(1, 2, 3)?);
-/// assert_eq!(time!(1:02:03.004_005_006 am), Time::try_from_hms_nano(1, 2, 3, 4_005_006)?);
-/// assert_eq!(time!(12:00 pm), Time::try_from_hms(12, 0, 0)?);
-/// assert_eq!(time!(1:02:03 pm), Time::try_from_hms(13, 2, 3)?);
-/// assert_eq!(time!(1:02:03.004_005_006 pm), Time::try_from_hms_nano(13, 2, 3, 4_005_006)?);
-/// # Ok(())
-/// # }
-/// ```
-pub use time_macros::time;
 pub use time_mod::Time;
 pub use utc_offset::UtcOffset;
+#[deprecated(
+    since = "0.2.23",
+    note = "This function has been moved to the `util` module."
+)]
 pub use util::{days_in_year, is_leap_year, validate_format_string, weeks_in_year};
 pub use weekday::Weekday;
 
@@ -473,6 +425,77 @@ pub fn parse<T: private::Parsable>(s: impl AsRef<str>, format: impl AsRef<str>)
     private::Parsable::parse(s, format)
 }
 
+/// Macros to statically construct values that are known to be valid.
+pub mod macros {
+
+    /// Construct a [`Date`](crate::Date) with a statically known value.
+    ///
+    /// The resulting expression can be used in `const` or `static` declarations.
+    ///
+    /// Three formats are supported: year-week-weekday, year-ordinal, and
+    /// year-month-day.
+    ///
+    /// ```rust
+    /// # use time::{Date, macros::date, Weekday::*};
+    /// # fn main() -> time::Result<()> {
+    /// assert_eq!(date!(2020-W01-3), Date::try_from_iso_ywd(2020, 1, Wednesday)?);
+    /// assert_eq!(date!(2020-001), Date::try_from_yo(2020, 1)?);
+    /// assert_eq!(date!(2020-01-01), Date::try_from_ymd(2020, 1, 1)?);
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub use time_macros::date;
+    /// Construct a [`UtcOffset`](crate::UtcOffset) with a statically known value.
+    ///
+    /// The resulting expression can be used in `const` or `static` declarations.
+    ///
+    /// A sign and the hour must be provided; minutes and seconds default to zero.
+    /// `UTC` (both uppercase and lowercase) is also allowed.
+    ///
+    /// ```rust
+    /// # use time::{macros::offset, UtcOffset};
+    /// assert_eq!(offset!(UTC), UtcOffset::hours(0));
+    /// assert_eq!(offset!(utc), UtcOffset::hours(0));
+    /// assert_eq!(offset!(+0), UtcOffset::hours(0));
+    /// assert_eq!(offset!(+1), UtcOffset::hours(1));
+    /// assert_eq!(offset!(-1), UtcOffset::hours(-1));
+    /// assert_eq!(offset!(+1:30), UtcOffset::minutes(90));
+    /// assert_eq!(offset!(-1:30), UtcOffset::minutes(-90));
+    /// assert_eq!(offset!(+1:30:59), UtcOffset::seconds(5459));
+    /// assert_eq!(offset!(-1:30:59), UtcOffset::seconds(-5459));
+    /// assert_eq!(offset!(+23:59:59), UtcOffset::seconds(86_399));
+    /// assert_eq!(offset!(-23:59:59), UtcOffset::seconds(-86_399));
+    /// ```
+    pub use time_macros::offset;
+    /// Construct a [`Time`](crate::Time) with a statically known value.
+    ///
+    /// The resulting expression can be used in `const` or `static` declarations.
+    ///
+    /// Hours and minutes must be provided, while seconds defaults to zero. AM/PM is
+    /// allowed (either uppercase or lowercase). Any number of subsecond digits may
+    /// be provided (though any past nine will be discarded).
+    ///
+    /// All components are validated at compile-time. An error will be raised if any
+    /// value is invalid.
+    ///
+    /// ```rust
+    /// # use time::{Time, macros::time};
+    /// # fn main() -> time::Result<()> {
+    /// assert_eq!(time!(0:00), Time::try_from_hms(0, 0, 0)?);
+    /// assert_eq!(time!(1:02:03), Time::try_from_hms(1, 2, 3)?);
+    /// assert_eq!(time!(1:02:03.004_005_006), Time::try_from_hms_nano(1, 2, 3, 4_005_006)?);
+    /// assert_eq!(time!(12:00 am), Time::try_from_hms(0, 0, 0)?);
+    /// assert_eq!(time!(1:02:03 am), Time::try_from_hms(1, 2, 3)?);
+    /// assert_eq!(time!(1:02:03.004_005_006 am), Time::try_from_hms_nano(1, 2, 3, 4_005_006)?);
+    /// assert_eq!(time!(12:00 pm), Time::try_from_hms(12, 0, 0)?);
+    /// assert_eq!(time!(1:02:03 pm), Time::try_from_hms(13, 2, 3)?);
+    /// assert_eq!(time!(1:02:03.004_005_006 pm), Time::try_from_hms_nano(13, 2, 3, 4_005_006)?);
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub use time_macros::time;
+}
+
 // For some back-compatibility, we're also implementing some deprecated types
 // and methods. They will be removed completely in 0.3.
 

src/offset_date_time.rs

@@ -113,11 +113,17 @@ impl OffsetDateTime {
     /// local offset.
     ///
     /// ```rust
+    /// # #![allow(deprecated)]
     /// # use time::OffsetDateTime;
     /// assert!(OffsetDateTime::now_local().year() >= 2019);
     /// ```
     #[cfg(feature = "std")]
     #[cfg_attr(__time_02_docs, doc(cfg(feature = "std")))]
+    #[deprecated(
+        since = "0.2.23",
+        note = "UTC is returned if the local offset cannot be determined"
+    )]
+    #[allow(deprecated)]
     pub fn now_local() -> Self {
         let t = Self::now_utc();
         t.to_offset(UtcOffset::local_offset_at(t))
@@ -129,7 +135,10 @@ impl OffsetDateTime {
     ///
     /// ```rust
     /// # use time::OffsetDateTime;
-    /// assert!(OffsetDateTime::try_now_local().is_ok());
+    /// let now = OffsetDateTime::try_now_local();
+    /// # if false {
+    /// assert!(now.is_ok());
+    /// # }
     /// ```
     #[cfg(feature = "std")]
     #[cfg_attr(__time_02_docs, doc(cfg(feature = "std")))]
@@ -276,6 +285,31 @@ impl OffsetDateTime {
     ///     date!(1970-01-01)
     ///         .midnight()
     ///         .assume_utc()
+    ///         .unix_timestamp(),
+    ///     0,
+    /// );
+    /// assert_eq!(
+    ///     date!(1970-01-01)
+    ///         .midnight()
+    ///         .assume_utc()
+    ///         .to_offset(offset!(-1))
+    ///         .unix_timestamp(),
+    ///     0,
+    /// );
+    /// ```
+    pub fn unix_timestamp(self) -> i64 {
+        (self - Self::unix_epoch()).whole_seconds()
+    }
+
+    /// Get the [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time).
+    ///
+    /// ```rust
+    /// # #![allow(deprecated)]
+    /// # use time::{date, offset};
+    /// assert_eq!(
+    ///     date!(1970-01-01)
+    ///         .midnight()
+    ///         .assume_utc()
     ///         .timestamp(),
     ///     0,
     /// );
@@ -288,8 +322,12 @@ impl OffsetDateTime {
     ///     0,
     /// );
     /// ```
+    #[deprecated(
+        since = "0.2.23",
+        note = "Use `OffsetDateTime::unix_timestamp` instead"
+    )]
     pub fn timestamp(self) -> i64 {
-        (self - Self::unix_epoch()).whole_seconds()
+        self.unix_timestamp()
     }
 
     /// Get the Unix timestamp in nanoseconds.
@@ -300,22 +338,51 @@ impl OffsetDateTime {
     ///     date!(1970-01-01)
     ///         .midnight()
     ///         .assume_utc()
-    ///         .timestamp_nanos(),
+    ///         .unix_timestamp_nanos(),
     ///     0,
     /// );
     /// assert_eq!(
     ///     date!(1970-01-01)
     ///         .with_time(time!(1:00))
     ///         .assume_utc()
     ///         .to_offset(offset!(-1))
-    ///         .timestamp_nanos(),
+    ///         .unix_timestamp_nanos(),
     ///     3_600_000_000_000,
     /// );
     /// ```
-    pub fn timestamp_nanos(self) -> i128 {
+    pub fn unix_timestamp_nanos(self) -> i128 {
         (self - Self::unix_epoch()).whole_nanoseconds()
     }
 
+    /// Get the Unix timestamp in nanoseconds.
+    ///
+    /// ```rust
+    /// # #![allow(deprecated)]
+    /// use time::{date, offset, time};
+    /// assert_eq!(
+    ///     date!(1970-01-01)
+    ///         .midnight()
+    ///         .assume_utc()
+    ///         .unix_timestamp_nanos(),
+    ///     0,
+    /// );
+    /// assert_eq!(
+    ///     date!(1970-01-01)
+    ///         .with_time(time!(1:00))
+    ///         .assume_utc()
+    ///         .to_offset(offset!(-1))
+    ///         .unix_timestamp_nanos(),
+    ///     3_600_000_000_000,
+    /// );
+    /// ```
+    #[deprecated(
+        since = "0.2.23",
+        note = "Use `OffsetDateTime::unix_timestamp_nanos` instead"
+    )]
+    pub fn timestamp_nanos(self) -> i128 {
+        self.unix_timestamp_nanos()
+    }
+
     /// Get the `Date` in the stored offset.
     ///
     /// ```rust

src/primitive_date_time.rs

@@ -425,11 +425,11 @@ impl PrimitiveDateTime {
     /// # #![allow(deprecated)]
     /// # use time::{date, offset};
     /// assert_eq!(
-    ///     date!(2019-01-01).midnight().using_offset(offset!(UTC)).timestamp(),
+    ///     date!(2019-01-01).midnight().using_offset(offset!(UTC)).unix_timestamp(),
     ///     1_546_300_800,
     /// );
     /// assert_eq!(
-    ///     date!(2019-01-01).midnight().using_offset(offset!(-1)).timestamp(),
+    ///     date!(2019-01-01).midnight().using_offset(offset!(-1)).unix_timestamp(),
     ///     1_546_300_800,
     /// );
     /// ```
@@ -451,11 +451,11 @@ impl PrimitiveDateTime {
     /// ```rust
     /// # use time::{date, offset};
     /// assert_eq!(
-    ///     date!(2019-01-01).midnight().assume_offset(offset!(UTC)).timestamp(),
+    ///     date!(2019-01-01).midnight().assume_offset(offset!(UTC)).unix_timestamp(),
     ///     1_546_300_800,
     /// );
     /// assert_eq!(
-    ///     date!(2019-01-01).midnight().assume_offset(offset!(-1)).timestamp(),
+    ///     date!(2019-01-01).midnight().assume_offset(offset!(-1)).unix_timestamp(),
     ///     1_546_304_400,
     /// );
     /// ```
@@ -469,7 +469,7 @@ impl PrimitiveDateTime {
     /// ```rust
     /// # use time::date;
     /// assert_eq!(
-    ///     date!(2019-01-01).midnight().assume_utc().timestamp(),
+    ///     date!(2019-01-01).midnight().assume_utc().unix_timestamp(),
     ///     1_546_300_800,
     /// );
     /// ```