v0.3 backports

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:/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,
  /// );
  /// ```