time

See the changelog for details.

Fixed

• Avoid underflow in DateIter::nth, ensuring correct behavior.
• Avoid overflow when deserializing timestamps.
• Handle out-of-bounds data when deserializing.
• Don't assume that the format being deserialized was generated by the serializer; this previously led to some valid values being parsed incorrectly and others being rejected.
• No longer silence errors when deserializing UtcOffset.
• OffsetDateTime::from_unix_timestamp_nanos and UtcDateTime::from_unix_timestamp_nanos correctly return None for all out-of-range values, rather than unexpectedly panicking in some situations.
• OffsetDateTime::checked_to_offset and UtcDateTime::checked_to_offset correctly return None for all out-of-range values, rather than unexpectedly panicking in some situations.

See the changelog for details.

Added

• PrimitiveDateTime has been renamed to PlainDateTime.
• Duration has been renamed to SignedDuration.
• Iteration is now possible over Date, Month, and Weekday. Relevant iterator methods have been overridden to ensure maximum performance.

For both PlainDateTime and SignedDuration, a non-deprecated type alias has been added for backwards compatibility. The new names should be preferred.

Changed

• The associated metadata type (for powerfmt implementations) for various types has been changed to () and made public. This guarantees that no additional metadata will be present.

Performance

• More gains when parsing RFC 2822.

See the changelog for details.

There are no publicly-facing changes in this release. It solely works around the cookie crate relying on an implementation detail of time that was never part of the public API (and thus subject to semver guarantees). The internal API has been reverted to the extent necessary for cookie to compile. This measure is temporary; the internal change will be re-applied in an yet-to-be-determined future release.

See the changelog for details.

Fixed

• Subsecond values in the time! macro are parsed using the textual representation, ensuring accuracy. Previously, they were parsed using the floating point representation, which could result in a loss of precision and even invalid values.
• The date! macro could previously create an invalid value that would then panic at compile time. The macro now emits a proper error instead.
• When parsing an invalid format description, an edge case would inadvertently panic. This now returns an error as intended.

Added

• Support default values when parsing

See the changelog for details.

Fixed

• time compiles with macros enabled. This version is otherwise identical to v0.3.50.

This version was yanked because it would not compile when the macros feature was enabled.

Added

• Timestamp type

Fixed

• [year] in a runtime-parsed version 3 format description when the large-dates feature is not enabled now succeeds. This previously failed due to a missing #[cfg].

Performance

• Further gains when parsing with the non-deprecated parts of the RFC 2822 well-known format
• Gains when formatting with the ISO 8601 well-known format
• Date arithmetic is improved in common situations

See the changelog for details.

Fixed

• Due to a long-standing bug in the Rust compiler, v0.3.48 caused a number of crates to stop compiling. A patch has been added that avoids triggering the bug.

See the changelog for details.

This version was yanked due to a bug in the Rust compiler.

Security

• The number of digits parsed by [subsecond digits:1+] is capped at 32 to avoid parsing unbounded user input. Digits after the 9^th have no semantic meaning.
• Explicitly specify #[repr] for Weekday. The value of the variants is relied upon in multiple locations for soundness. The practical effect of this change is nothing, as Rust has always mapped C-like enums to 0..N in memory.

Compatibility

• Non-UTF-8 formatting and parsing is deprecated without replacement. It is recommended to only format and parse valid UTF-8.
• format_description::parse is deprecated. It is recommended to use format_description::parse_borrowed::<3> or format_description::parse_owned::<3>.

Added

• All types in the unit module have a generic parameter, though this is currently not used for much. Usage will be expanded in the future.
• Comparisons between types in the unit module and the generic Unit type are permitted.
• Support for rand 0.10
• Version 3 format descriptions
  • Only UTF-8 is supported. As a side effect of this, [ignore] requires that the remaining input not begin mid-codepoint.
  • Representation is deliberately opaque to allow for arbitrary changes going forward.
  • format:false is supported on [optional] components. This is not possible in version 1 and version 2 format descriptions due to API compatibility.
  • The time::serde::format_description! macro uses a new, clearer syntax for version 3.
    • time::serde::format_description!(mod foo [Date] = "[year]-[month]-[day]");
    • Unlike version 1 and version 2 format descriptions, the type is not automatically brought into scope. You must import it yourself.
  • Nonsensical combinations of modifiers are rejected. For example, you cannot specify case-sensitivity when parsing a numerical month.
  • [year] defaults to range:standard
  • Components and modifiers are case sensitive (and always lowercase).

Changed

• The convert module has been renamed to unit.

Fixed

• Macro hygiene has been improved by specifying re-exports.
• Fix handling of T in ISO 8601
• Support parsing the full range of UTC offset hours
• Version 1 nested format descriptions may now start with a component. Previously, a lexer bug unintentionally prohibited this.
• Error when ISO week date overflows the max year. This would previously panic.
• Error when padding is specified in strftime format descriptions but the component is not. This would previously panic.

Performance

Huge performance gains across multiple areas, including:

• optimizing equality checks for Duration
• optimizing Display impls for all major types
• optimizing the formatting of components and well-known formats
• precomputing metadata when formatting, reducing allocations
• adding fast path for typical RFC 2822 usage
• optimizing strftime parsing
• refactoring format description parsing

Depending on the area, gains range from 3× to even 11×.

See the changelog for details.

Security

• The possibility of a stack exhaustion denial of service attack when parsing RFC 2822 has been eliminated. Previously, it was possible to craft input that would cause unbounded recursion. Now, the depth of the recursion is tracked, causing an error to be returned if it exceeds a reasonable limit.

  This attack vector requires parsing user-provided input, with any type, using the RFC 2822 format.

Compatibility

• Attempting to format a value with a well-known format (i.e. RFC 3339, RFC 2822, or ISO 8601) will error at compile time if the type being formatted does not provide sufficient information. This would previously fail at runtime. Similarly, attempting to format a value with ISO 8601 that is only configured for parsing (i.e. Iso8601::PARSING) will error at compile time.

Added

• Builder methods for format description modifiers, eliminating the need for verbose initialization when done manually.
• date!(2026-W01-2) is now supported. Previously, a space was required between W and 01.
• [end] now has a trailing_input modifier which can either be prohibit (the default) or discard. When it is discard, all remaining input is ignored. Note that if there are components after [end], they will still attempt to be parsed, likely resulting in an error.

Changed

• More performance gains when parsing.

Fixed

• If manually formatting a value, the number of bytes written was one short for some components. This has been fixed such that the number of bytes written is always correct.
• The possibility of integer overflow when parsing an owned format description has been effectively eliminated. This would previously wrap when overflow checks were disabled. Instead of storing the depth as u8, it is stored as u32. This would require multiple gigabytes of nested input to overflow, at which point we've got other problems and trivial mitigations are available by downstream users.

See the changelog for details.

Added

• All possible panics are now documented for the relevant methods.

• The need to use #[serde(default)] when using custom serde formats is documented. This applies only when deserializing an Option<T>.

• Duration::nanoseconds_i128 has been made public, mirroring std::time::Duration::from_nanos_u128.

• Various methods for truncating components have been added, avoiding the need to call the fallible replace methods multiple times.

  For PrimitiveDateTime, UtcDateTime, and OffsetDateTime:

  • truncate_to_day

  For Time, PrimitiveDateTime, UtcDateTime, and OffsetDateTime:

  • truncate_to_hour
  • truncate_to_minute
  • truncate_to_second
  • truncate_to_millisecond
  • truncate_to_microsecond

Changed

• The minimum supported Rust version is now 1.88.0.
• Significant performance gains in numerous locations. No public APIs were changed or removed as part of this.
• The size of error::ComponentRange, along with types that contain it, has been significantly reduced.

Fixed

• The PartialOrd and Ord implementations of UtcOffset now return the expected result.

Added

• time::format_description::StaticFormatDescription type alias for &'static [BorrowedFormatItem<'static>]. This is the type returned by the time::macros::format_description! macro.

Changed

• The minimum supported Rust version is now 1.83.0.
• All floating point methods on Duration are now const fn.
• All setters on Parsed are now const fn.
• The serde dependency has been replaced with serde_core, This reduces compile times by not including unused parts of serde.
• Date::from_julian_day uses a new algorithm, resulting in an approximately 16% performance improvement. This method is used internally by numerous other methods.
• util::is_leap_year uses a new algorithm, resulting in an approximately 8% performance improvement.

Fixed

• Comparisons of PrimitiveDateTime, UtcDateTime, and OffsetDateTime with differing signs (i.e. one negative and one positive year) would return the inverse result of what was expected. This was introduced in v0.3.42 and has been fixed.
• Type inference would fail due to feature unification when wasm-bindgen enabled serde_json. This has been fixed by explicitly specifying the type in the relevant locations.

Added

• Support for rand 0.9

Fixed

• In the convert module, any use of per with types that were not the same (such as Nanosecond::per(Second)) would not compile due to a bug. This has been fixed.

Added

• Time::duration_until
• Time::duration_since
• per_t method for all types in time::convert. This is similar to the existing per method, but can return any of the primitive numeric types that can represent the result. This will cut down on as casts while ensuring correctness. Type inference isn't perfect, so you may need to provide a type annotation in some situations.
• impl PartialOrd for Month and impl Ord for Month; this assumes the months are in the same year
• SystemTimeExt trait, adding methods for checked arithmetic with time::Duration and obtaining the difference between two SystemTimes as a time::Duration
• Permit using UtcDateTime with rand (this was inadvertently omitted previously)
• impl core::error::Error for all error types (now available when the std feature is disabled)
• MacOS can now obtain the local UTC offset in multi-threaded programs as the system APIs are thread-safe.
• #[track_caller] has been added to all relevant methods.

Changed

• The minimum supported Rust version is now 1.81.0.
• The dependency on itoa has been removed, as the standard library now has similar functionality by default.
• Formatting a component that involves a floating point number is now guaranteed to be deterministic, avoiding any subtle differences between platforms or compiler versions.

Fixed

• Serializing timestamps with nanosecond precision should always emit the correct value. Previously, it could be off by one nanosecond due to floating point imprecision.
• A previously unknown bug in OffsetDateTime::to_offset and UtcDateTime::to_offset has been fixed. The bug could result in a value that was invalid. It was unlikely to ever occur in real-world code, as it involved passing a UTC offset that has never been used in any location.

Miscellaneous

• The amount of code generated by macros has been massively reduced, on the order of 65-70% for typical use cases of format_description!.
• Significant performance gains for comparisons of Time, PrimitiveDateTime, UtcDateTime, and OffsetDateTime. The first three have gains of approximately 85% (i.e. 6× faster).
• Nearly all methods are #[inline].

Fixed

• Compatibility with the latest release of deranged. This fix is permanent and covers future similar changes upstream.

Added

• Visibility modifiers may now be added to the mod generated by time::sere::format_description!.

Fixed

• Doc tests run successfully with the default feature set.
• wasm builds work again.

Both of these were regressions in v0.3.38 and are now checked in CI.

Added

• The [year] component (in format descriptions) now supports a range modifier, which can be either standard or extended. The default is extended for backwards compatibility. This is intended as a manner to opt out of the extended range when the large-dates feature is enabled. When the large-dates feature is not enabled, the modifier has no effect.

• UtcDateTime, which is semantically equivalent to an OffsetDateTime with UTC as its offset. The advantage is that it is the same size as a PrimitiveDateTime and has improved operability with well-known formats.

  As part of this, there were some other additions:

  • utc_datetime! macro, which is similar to the datetime! macro but constructs a UtcDateTime.
  • PrimitiveDateTime::as_utc
  • OffsetDateTime::to_utc
  • OffsetDateTime::checked_to_utc

• time::serde::timestamp::milliseconds_i64, which is a module to serialize/deserialize timestamps as the Unix timestamp. The pre-existing module does this as an i128 where an i64 would suffice. This new module should be preferred.

Changed

• error::Format has had its source() implementation changed to no longer return a boxed value from the ComponentRange variant. If you were explicitly expecting this, you will need to update your code. The method API remains unchanged.
• [year repr:century] supports single-digit values.
• All format_into methods accept ?Sized references.

Miscellaneous

• Some non-exhaustive enum variants that are no longer used have been modified to be statically proven as uninhabited. The relevant fields are doc-hidden and not semver-guaranteed to remain as such, though it is unlikely to change.
• An unnecessary check when parsing RFC 2822 has been removed.
• Various methods have had their implementations changed, resulting in significant performance gains. Among the methods changed are
  • util::is_leap_year
  • util::weeks_in_year
  • Month::length
  • Date::to_calendar_date
  • Date::month
  • Date::day
  • Date::from_julian_day
  • Date::to_julian_day
  • other methods that call into these methods

Added

• Time::MAX, equivalent to time!(23:59:59.999999999)
• [year repr:century] is now supported in format descriptions. When used in conjunction with [year repr:last_two], there is sufficient information to parse a date. Note that with the large-date feature enabled, there is an ambiguity when parsing the two back-to-back.
• Parsing of strftime-style format descriptions, located at time::format_description::parse_strftime_borrowed and time::format_description::parse_strftime_owned
• time::util::refresh_tz and time::util::refresh_tz_unchecked, which updates information obtained via the TZ environment variable. This is equivalent to the tzset syscall on Unix-like systems, with and without built-in soundness checks, respectively.
• Month::length and util::days_in_month, replacing util::days_in_year_month.
• Expressions are permitted in time::serde::format_description! rather than only paths. This also drastically improves diagnostics when an invalid value is provided.

Changed

• Obtaining the system UTC offset on Unix-like systems should now succeed when multi-threaded. However, if the TZ environment variable is altered, the program will not be aware of this until time::util::refresh_tz or time::util::refresh_tz_unchecked is called. refresh_tz has the same soundness requirements as obtaining the system UTC offset previously did, with the requirements still being automatically enforced. refresh_tz_unchecked does not enforce these requirements at the expense of being unsafe. Most programs should not need to call either function.

  Due to this change, the time::util::local_offset module has been deprecated in its entirety. The get_soundness and set_soundness functions are now no-ops.

  Note that while calls should succeed, success is not guaranteed in any situation. Downstream users should always be prepared to handle the error case.

Fixed

• Floating point values are truncated, not rounded, when formatting.
• RFC3339 allows arbitrary separators between the date and time components.
• Serialization of negative Durations less than one second is now correct. It previously omitted the negative sign.
• From<js_sys::Date> for OffsetDateTime now ensures sub-millisecond values are not erroneously returned.

Fixed

• FormatItem can be used as part of an import path. See #675 for details.

Added

• Duration::checked_neg
• ext::InstantExt, which provides methods for using time::Duration with std::time::Instant

Changed

• Instant is deprecated. It is recommended to use std::time::Instant directly, importing time::ext::InstantExt for interoperability with time::Duration.
• FormatItem has been renamed to BorrowedFormatItem, avoiding confusion with OwnedFormatItem. An alias has been added for backwards compatibility.

Fixed

• The weekday is optional when parsing RFC2822.
• The range of sub-second values in Duration is documented correctly. The previous documentation contained an off-by-one error.
• Leap seconds are now correctly handled when parsing ISO 8601.

Fixed

Computing the local offset on Windows works again. It was broken in some cases in v0.3.32 and v0.3.33.

Fixed

Builds targeting wasm32-unknown-unknown now work again.

Added

• Methods to replace the day of the year.
  • Date::replace_ordinal
  • PrimitiveDateTime::replace_ordinal
  • OffsetDateTime::replace_ordinal
• Modules to treat an OffsetDateTime as a Unix timestamp with subsecond precision for serde.
  • time::serde::timestamp::milliseconds
  • time::serde::timestamp::microseconds
  • time::serde::timestamp::nanoseconds

Changed

• Duration::time_fn is deprecated.

Added

• OffsetDateTime::new_in_offset
• OffsetDateTime::new_utc

Changed

• The valid range of UtcOffset has been expanded from ±23:59:59 to ±25:59:59. This is to support the full POSIX range while permitting infallible negation.

Added

• powerfmt::smart_display::SmartDisplay has been added for the main types in the library. These implementations ensure that values follow the requested fill, width, and alignment when using format! or similar macros. Display is implemented in terms of SmartDisplay.

Fixed

• Large values no longer wrap around in release mode when using NumericalDuration or NumericalStdDuration.

Added

• Niche value optimization for Date has been added. Both Date and Option<Date> are four bytes.

• Unit conversions have been added. It is now possible to write Second::per(Day), which returns the number of seconds in one day. See the types in the time::convert module for more information.

Changed

• The diagnostic for --cfg unsound_local_offset has been removed.
• #![feature(no_coverage)] was previously used internally for code coverage. It is no longer used, so it has been removed.
• The default value for modifier::OffsetHour has been changed. This was unintentionally changed in v0.3.17 and went unnoticed until now. The sign is now only present if needed by default, as was the case previously. This does not affect any situation where format_description! or format_description::parse is used.

Fixed

• Adding or subtracting a std::time::Duration to/from an OffsetDateTime will not result in integer overflow internally. It will still panic if the result is out of range.

Added

• More additional constants for the well-known Iso8601 format description have been added. This avoids the need to manually configure the format.
• An [end] component has been added. This is ignored during formatting, but is used to indicate the end of input when parsing. If any input remains after this component, an error is returned. This is useful when using the [first] component, as it avoids the need to reorder variants.

Changed

• The exemption for MacOS introduced in 0.3.20 has been removed. This is because some supported versions of MacOS do not meet the requirements for the exemption.
• The UnexpectedTrailingCharacters error variant has been moved to ParseFromDescription. All previously-existing locations of this variant have been deprecated and will no longer be returned.

This sets the serde dependency requirement to >= 1.0.184 where the binaries have been removed.

This release contains only a single change. serde is required to be a version prior to 1.0.171. This is due to the decision by the maintainer of serde to include pre-built binaries that are executed without the end user's knowledge. As of the time of publishing, the included binary has not even been reproduced. This is a security risk, and the time project strongly opposes this decision. While this may break some users' builds due to conflicting versions, it is a necessary step to ensure the security.

Fixed

• Methods such as Time::replace_milliseconds would panic on some out-of-range values. This has been fixed.

Added

• The subsecond component is taken into account when parsing the unix_timestamp component. If data is conflicting, the subsecond value takes precedence.
• Parsing a Time with only the hour component is now supported. The minute and second, and subsecond components are assumed to be zero.

Changed

• The minimum supported Rust version is now 1.67.0.
• The debug output for Parsed has been improved.
• When parsing, invalid values are now rejected sooner. Previously, the entire input would be parsed before being rejected in the final step. Now, invalid values are rejected as soon as they are encountered. This affects the error variant returned, which may cause minor breakage for any code (incorrectly) relying on the exact error variant.
• When parsing a Time, an error is returned if components are present but not consecutive. For example, if hours and seconds are present, minutes will not be assumed to be zero.

Fixed

• The implementation of Duration::checked_div could return a slightly incorrect result in some cases. This has been fixed.

Added

• Date::next_occurrence
• Date::prev_occurrence
• Date::nth_next_occurrence
• Date::nth_prev_occurrence
• Weekday::nth_prev
• Month::nth_next
• Month::nth_prev

Changed

The minimum supported Rust version policy has been updated. See the README for details.

Fixed

• Duration::abs correctly returns Duration::MAX when near the minimum value. The nanoseconds value was previously incorrect.
• Compliance with ISO 8601 has been improved. Previously, a UTC offset would be incorrectly rejected in some cases.

Added

• OffsetDateTime::checked_to_offset

Added

• Any formattable/parsable type can now be used with the time::serde::format_description! macro.
• Weekday::nth_next

Changed

• The minimum supported Rust version is now 1.65.0.

Changed

• The minimum supported Rust version is now 1.63.0.
• On Unix-based operating systems with known thread-safe environments, functions obtaining the local offset no longer require a check that the program is single-threaded. This currently includes MacOS, illumos, and NetBSD.

Added

• [ignore] component in format descriptions. A count modifier is required, indicating the number of bytes to ignore when parsing.
• [unix_timestamp] component in format descriptions. This is currently only usable with OffsetDateTime. Users can choose between seconds, milliseconds, microseconds, and nanoseconds, and whether the sign is mandatory or optional.

Fixed

• The API for declaring soundness now uses stricter atomic orderings internally.

Fixed

This includes the update to the format_description! macro, which was supposed to be included in 0.3.18.

Changed

• The minimum supported Rust version is now 1.62.0.

Added

• [first] and [optional] items can now be included in format descriptions. To parse this at runtime, you must use the format_description::parse_owned method.
• format_description::parse_borrowed
• An API has been added to opt out of soundness checks for obtaining the local offset. This replaces the previous, officially unsupported RUSTFLAGS="--cfg unsound_local_offset". End users may call time::util::local_offset::set_soundness(time::util::local_offset::Soundness::Unsound). This method is unsafe because it enables undefined behavior if its safety requirements are not upheld. Note that libraries must not set this to Unsound, as it is impossible for a library to guarantee end users uphold the required invariants.

Fixed

• Correctly parse offset sign when hour is zero. The parse was previously unconditionally positive, even if the sign indicated otherwise.
• Compilation is fixed for WebAssembly.

Changed

• The amount of code generated by time::serde::format_description! is reduced if not all feature flags are active.
• cargo test --tests works with any configuration of feature flags. This occurs by spawning a subprocess that passes --all-features. cargo test --doc works with most combinations of feature flags, including the default. The combination of these changes means that crater will now run on time.
• libc and num_threads are only included as dependencies when needed. They were previously unconditionally included.

Added

• time::format_description::parse_owned, which returns an OwnedFormatItem. This avoids "lifetime hell", where all your structs now need a lifetime because a single field has one. Note that when possible, the borrowed format item (just called FormatItem) is still preferred, as it has significantly fewer allocations. The new OwnedFormatItem is usable for both formatting and parsing, as you would expect.

Compatibility

• The parser for runtime format descriptions has been rewritten. A side effect of this is that some errors have slightly changed. No existing API has been altered, so this is not a breaking change. However, you may notice different errors, which are hopefully better! The parser for compile-time format descriptions has not yet been swapped out. If you notice any bugs, please file an issue.

Changed

• The minimum supported Rust version is now 1.60.0.
• The serde-well-known feature flag is deprecated. The necessary features for an item to be enabled are indicated in documentation.
• Feature gates have been loosened for well-known formats.

Added

• consts can now be provided as the format description for time::serde::format_description!. The const must be of type &[FormatItem<'_>], which is what is returned by the time::macros::format_description! macro.

  const TIME_FORMAT_ALT: &[FormatItem<'_>] = time::macros::format_description!("[hour]:[minute]");
  time::serde::format_description!(time_format_alt, Time, TIME_FORMAT_ALT);
  

Compatibility

• Some feature flags have been removed. None of these have ever been documented as flags, so any use was unsupported. These flags are:
  • js-sys
  • quickcheck-dep
  • itoa
  • time-macros

Changed

• Better gating for tm_gmtoff extension. This should eliminate build failures on some untested platforms.
• Debug output for types are now human-readable. While this should not be relied upon, it is currently the same as the output with Display.
• Eliminate overflows in the constructors for `Duration. When there is an overflow, the methods now panic. This was previously only the case in debug mode.
• Panic if NaN is passed to Duration::from_secs_f32 or Duration::from_secs_f64.

Fixed

• Fix error when deserializing data types from bytes. This affects formats such as JSON.
• Eliminate a panic in an edge case when converting OffsetDateTime to another UtcOffset. This occurred due to an old assumption in code that was no longer the case.

Changed

• The minimum supported Rust version is now 1.59.0.
• Duration::unsigned_abs is now const fn.
• The const parameter for time::format_description::well_known::Iso8601 now has a default. This means Iso8601 is the same as Iso8601::DEFAULT.
• The Parsed struct has been reduced in size from 56 to 32 bytes (a 43% reduction).

Fixed

• wasm builds other than those using wasm-bindgen work again.

Added

• js-sys now supports obtaining the system's local UTC offset.

Changed

• Performance of many Date operations has improved when using the large-dates feature.
• While an internal change, OffsetDateTime now stores the value in the attached UtcOffset, not UTC. This leads to significant performance gains on nearly all OffsetDateTime methods.

Fixed

• Subtracting two Times can no longer panic. This previously occurred in some situations where the result was invalid.
• ISO 8601 parsing rounds the subseconds to avoid incorrectly truncating the value.

Fixed

• #479: regression when parsing optional values with serde
• #481: Time subtracted from Time can panic. This was caused by a bug that has always existed, in that an internal invariant was not upheld. Memory safety was not violated.

Added

• Serde support for non-self-describing formats
• Duration::unsigned_abs, which returns a std::time::Duration
• ISO 8601 well-known format
• Duration can now be formatted with a .N specifier, providing a shorter representation when using Display.
• Parse null as None on serde structs

Fixed

• Fix incorrect parsing of UTC offset in Rfc3339.

Changed

• The minimum supported Rust version is now 1.57.0.
• Performance for Rfc2822 has been improved.
• Debug assertions have been added in a few places. This should have no user facing impact, as it only serves to catch bugs and is disabled in release mode.

Added

• time::serde::format_description!
  • This macro is similar to time::format_description!, but it generates a module that can be used in #[serde(with = "foo")]. This makes it far easier to serialize/deserialize a custom format.
• Date::replace_year
• Date::replace_month
• Date::replace_day
• Time::replace_hour
• Time::replace_minute
• Time::replace_second
• Time::replace_millisecond
• Time::replace_microsecond
• Time::replace_nanosecond
• PrimitiveDateTime::replace_year
• PrimitiveDateTime::replace_month
• PrimitiveDateTime::replace_day
• PrimitiveDateTime::replace_hour
• PrimitiveDateTime::replace_minute
• PrimitiveDateTime::replace_second
• PrimitiveDateTime::replace_millisecond
• PrimitiveDateTime::replace_microsecond
• PrimitiveDateTime::replace_nanosecond
• OffsetDateTime::replace_year
• OffsetDateTime::replace_month
• OffsetDateTime::replace_day
• OffsetDateTime::replace_hour
• OffsetDateTime::replace_minute
• OffsetDateTime::replace_second
• OffsetDateTime::replace_millisecond
• OffsetDateTime::replace_microsecond
• OffsetDateTime::replace_nanosecond
• Parsed::offset_minute_signed
• Parsed::offset_second_signed
• Parsed::set_offset_minute_signed
• Parsed::set_offset_second_signed
• Parsed::with_offset_minute_signed
• Parsed::with_offset_second_signed
• error::InvalidVariant
• impl FromStr for Weekday
• impl FromStr for Month
• impl Display for Duration

Deprecated

The following methods have been deprecated in favor of the new, signed equivalent methods. The pre-existing methods

• Parsed::offset_minute
• Parsed::offset_second
• Parsed::set_offset_minute
• Parsed::set_offset_second
• Parsed::with_offset_minute
• Parsed::with_offset_second

Changed

• Well-known formats that support leap seconds now return the TryFromParsed::ComponentRange error variant if the leap second could not occur at that given moment.

This release is broken and has been yanked.

Fixed

Solaris and Illumos build again.

Added

• Date::saturating_add
• Date::saturating_sub
• PrimitiveDateTime::saturating_add
• PrimitiveDateTime::saturating_sub
• OffsetDateTime::saturating_add
• OffsetDateTime::saturating_sub
• PrimitiveDatetime::MIN
• PrimitiveDatetime::MAX
• Rfc2822 format description
• Serde support for well-known formats
  • This is placed behind the new serde-well-known feature flag.

Changed

• MacOS and FreeBSD are supported obtaining the local offset when single-threaded.
  • Starting with this version, this is delegated to the num_threads crate.
• Leap seconds are now parsed as the final nanosecond of the preceding second.
• The minimum supported Rust version is now 1.53.0.
• Deserializers for human readable formats will fall back to the binary format if the human readable format fails to deserialize.

Fixed

• Deserialization will no longer fail when given a non-borrowed string.

Added

• Date::checked_add
• Date::checked_sub
• PrimitiveDateTime::checked_add
• PrimitiveDateTime::checked_sub
• OffsetDateTime::checked_add
• OffsetDateTime::checked_sub

Changed

• Attempts to obtain the local UTC offset will now succeed on Linux if the process is single-threaded. This does not affect other Unix platforms. As a reminder, the relevant methods are fallible and may return an Err value for any reason.

Added

• error::DifferentVariant and Error::DifferentVariant
• impl From<Component> for FormatItem<'_>
• impl TryFrom<FormatItem<'_>> for Component
• impl<'a> From<&'a [FormatItem<'_>]> for FormatItem<'a>
• impl<'a> TryFrom<FormatItem<'a>> for &[FormatItem<'a>]
• impl PartialEq<Component> for FormatItem<'_>
• impl PartialEq<FormatItem<'_>> for Component
• impl PartialEq<&[FormatItem<'_>]> for FormatItem<'_>
• impl PartialEq<FormatItem<'_>> for &[FormatItem<'_>]
• impl TryFrom<Error> for error::TryFromParsed
• impl TryFrom<Error> for error::Parse
• impl TryFrom<Error> for error::ParseFromDescription
• impl TryFrom<Error> for error::InvalidFormatDescription
• impl TryFrom<Error> for error::IndeterminateOffset
• impl TryFrom<Error> for error::Format
• impl TryFrom<Error> for error::ConversionRange
• impl TryFrom<Error> for error::ComponentRange
• impl TryFrom<error::TryFromParsed> for error::ComponentRange
• impl TryFrom<error::Parse> for error::TryFromParsed
• impl TryFrom<error::Parse> for error::ParseFromDescription
• impl TryFrom<error::Format> for std::io::Error
• impl Sum for Duration
• impl Sum<&Duration> for Duration
• A const fn default() has been added to all modifiers that are structs. These methods exist to permit construction in const contexts and may be removed (without being considered a breaking change) once impl const Default is stabilized.
• FormatItem::Optional, which will consume the contained value if present but still succeed otherwise.
• FormatItem::First, which will consume the first successful parse, ignoring any prior errors.

Fixed

• Cross-building to Windows now succeeds.
• A parse error on a UtcOffset component now indicates the error comes from the offset.
• Some arithmetic no longer panics in edge cases.

Added

• Parsed::parse_item
• Parsed::parse_items
• Parsed::parse_literal
• Builder methods for Parsed
• The format_description! macro now supports the case_sensitive modifier.

Changed

The minimum supported version is now 1.51.0.

Added

• Instant is now #[repr(transparent)]

Fixed

• Constructing a Date from its ISO year, week, and weekday now returns the correct value in all circumstances. Previously, dates with an ISO year less than zero may have returned incorrect values. This affects both the Date::from_iso_week_date method and the date! macro.

Added

• Month now implements TryFrom<u8>
• From<Month> is now implemented for u8
• The parser now accepts "5 PM" and similar as a valid time. Only the 12-hour clock hour and the AM/PM suffix may be present; any other components representing a time will cause an error (this exact behavior is not guaranteed).
• The time! macro accepts the "5 PM" syntax with the same restriction.

Fixed

• Macros that have a time component (time! and datetime!) no longer accept "0:00 AM" and similar. This was previously erroneously accepted.

Added

• datetime! macro, which allows the construction of a statically verified PrimitiveDateTime or OffsetDateTime.
• PrimitiveDateTime::replace_time
• PrimitiveDateTime::replace_date
• OffsetDateTime::replace_time
• OffsetDateTime::replace_date
• OffsetDateTime::replace_date_time
• OffsetDateTime::replace_offset
• #![no_alloc] support
• Date::to_iso_week_date, replacing Date::iso_year_week
• Date::MIN
• Date::MAX
• UtcOffset::from_hms
• UtcOffset::from_whole_seconds
• UtcOffset::as_hms
• UtcOffset::whole_hours
• UtcOffset::whole_minutes
• UtcOffset::minutes_past_hour
• UtcOffset::seconds_past_minute
• UtcOffset::is_utc
• UtcOffset::is_positive
• UtcOffset::is_negative
• OffsetDateTime::sunday_based_week
• OffsetDateTime::monday_based_week
• PrimitiveDateTime::to_calendar_date
• PrimitiveDateTime::to_ordinal_date
• PrimitiveDateTime::to_iso_week_date
• PrimitiveDateTime::to_julian_day
• OffsetDateTime::to_calendar_date
• OffsetDateTime::to_ordinal_date
• OffsetDateTime::to_iso_week_date
• OffsetDateTime::to_julian_day
• Time::as_hms
• Time::as_hms_milli
• Time::as_hms_micro
• Time::as_hms_nano
• PrimitiveDateTime::as_hms
• PrimitiveDateTime::as_hms_milli
• PrimitiveDateTime::as_hms_micro
• PrimitiveDateTime::as_hms_nano
• OffsetDateTime::to_hms
• OffsetDateTime::to_hms_milli
• OffsetDateTime::to_hms_micro
• OffsetDateTime::to_hms_nano
• Duration::saturating_add
• Duration::saturating_sub
• Duration::saturating_mul
• util::days_in_year_month
• Month
• Instant::into_inner
• impl AsRef<StdInstant> and impl Borrow<StdInstant> for Instant
• Support for obtaining the local UTC offset on Unix-like systems has been re-added under a user-provided flag. This functionality is not tested in any way and is not guaranteed to work. Library authors are unable to enable this feature, as it must be passed via RUSTFLAGS. Further information is available in the documentation.

Changed

• The minimum supported Rust version is now 1.48.0. Per the policy in the README, this may be bumped within the 0.3 series without being a breaking change.
• rand has been updated to 0.8.
• quickcheck has been updated to 1.0.
• Macros are placed behind the macros feature flag.
• Renamed
  • OffsetDatetime::timestamp → OffsetDateTime::unix_timestamp
  • OffsetDatetime::timestamp_nanos → OffsetDateTime::unix_timestamp_nanos
  • Date::try_from_ymd → Date::from_calendar_date
  • Date::try_from_yo → Date::from_ordinal_date
  • Date::try_from_iso_ywd → Date::from_iso_week_date
  • Date::as_ymd → Date::to_calendar_date
  • Date::as_yo → Date::to_ordinal_date
  • Date::try_with_hms → Date::with_hms
  • Date::try_with_hms_milli → Date::with_hms_milli
  • Date::try_with_hms_micro → Date::with_hms_micro
  • Date::try_with_hms_nano → Date::with_hms_nano
  • Time::try_from_hms → Time::from_hms
  • Time::try_from_hms_milli → Time::from_hms_milli
  • Time::try_from_hms_micro → Time::from_hms_micro
  • Time::try_from_hms_nano → Time::from_hms_nano
  • UtcOffset::try_local_offset_at → UtcOffset::local_offset_at
  • UtcOffset::as_seconds → UtcOffset::whole_seconds
  • OffsetDateTime::try_now_local → OffsetDateTime::now_local
  • Date::week → Date::iso_week
  • PrimitiveDateTime::week → PrimitiveDateTime::iso_week
  • OffsetDateTime::week → OffsetDateTime::iso_week
  • Date::julian_day → Date::to_julian_day
  • All Duration unit values, as well as the minimum and maximum, are now associated constants.
  • OffsetDateTime::unix_epoch() → OffsetDateTime::UNIX_EPOCH
  • Time::midnight() → Time::MIDNIGHT
• Now const fn (on at least newer compilers)
  • Date::weekday
  • Date::next_day
  • Date::previous_day
  • PrimitiveDateTime::assume_offset
  • PrimitiveDateTime::weekday
  • Duration::checked_add
  • Duration::checked_sub
  • Duration::checked_mul
  • OffsetDateTime::from_unix_timestamp
  • OffsetDateTime::from_unix_timestamp_nanos
  • OffsetDateTime::date
  • OffsetDateTime::time
  • OffsetDateTime::year
  • OffsetDateTime::month
  • OffsetDateTime::day
  • OffsetDateTime::ordinal
  • OffsetDateTime::to_iso_week_date
  • OffsetDateTime::week
  • OffsetDateTime::weekday
  • OffsetDateTime::hour
  • OffsetDateTime::minute
  • OffsetDateTime::second
  • OffsetDateTime::millisecond
  • OffsetDateTime::microsecond
  • OffsetDateTime::nanosecond
  • OffsetDateTime::unix_timestamp
  • OffsetDateTime::unix_timestamp_nanos
• The following functions now return a Result:
  • Date::from_julian_day
  • OffsetDateTime::from_unix_timestamp
  • OffsetDateTime::from_unix_timestamp_nanos
• The following functions now return an Option:
  • Date::next_day
  • Date::previous_day
• The range of valid years has changed. By default, it is ±9999. When using the large-dates feature, this is increased to ±999,999. Enabling the feature has performance implications and introduces ambiguities when parsing.
• The following are now gated under the local-offset feature:
  • UtcOffset::local_offset_at
  • OffsetDateTime::now_local
• Instant is now guaranteed to be represented as a tuple struct containing a std::time::Instant.
• Macros are guaranteed to be evaluated at compile time.
• Date::to_julian_day now returns an i32 (was i64).
• Date::from_julian_day now accepts an i32 (was i64).
• Extension traits are only implemented for some types and are now sealed. As they are intended to be used with value literals, the breakage caused by this should be minimal.
• The new Month enum is used instead of numerical values where appropriate.

Removed

• v0.1 APIs, previously behind an enabled-by-default feature flag
  • PreciseTime
  • SteadyTime
  • precise_time_ns
  • precise_time_s
  • Instant::to
  • Duration::num_weeks
  • Duration::num_days
  • Duration::num_hours
  • Duration::num_minutes
  • Duration::num_seconds
  • Duration::num_milliseconds
  • Duration::num_microseconds
  • Duration::num_nanoseconds
  • Duration::span
  • Duration::from_std
  • Duration::to_std
• Panicking APIs, previously behind a non-default feature flag
  • Date::from_ymd
  • Date::from_yo
  • Date::from_iso_ywd
  • Date::with_hms
  • Date::with_hms_milli
  • Date::with_hms_micro
  • Date::with_hms_nano
  • Time::from_hms
  • Time::from_hms_milli
  • Time::from_hms_micro
  • Time::from_hms_nano
• APIs that assumed an offset of UTC, previously enabled unconditionally
  • Date::today
  • Time::now
  • PrimitiveDateTime::now
  • PrimitiveDateTime::unix_epoch
  • PrimitiveDateTime::from_unix_timestamp
  • PrimitiveDateTime::timestamp
  • OffsetDateTime::now
  • impl Sub<SystemTime> for PrimitiveDateTime
  • impl Sub<PrimitiveDateTime> for SystemTime
  • impl PartialEq<SystemTime> for PrimitiveDateTime
  • impl PartialEq<PrimitiveDateTime> for SystemTime
  • impl PartialOrd<SystemTime> for PrimitiveDateTime
  • impl PartialOrd<PrimitiveDateTime> for SystemTime
  • impl From<SystemTime> for PrimitiveDateTime
  • impl From<PrimitiveDateTime> for SystemTime
  • UtcOffset::local_offset_at — assumed UTC if unable to determine local offset
  • OffsetDateTime::now_local — assumed UTC if unable to determine local offset
• Other APIs deprecated during the course of 0.2, previously enabled unconditionally
  • Duration::sign
  • PrimitiveDateTime::using_offset
  • Sign
• Re-exports of APIs moved during the course of 0.2
  • days_in_year
  • is_leap_year
  • validate_format_string
  • weeks_in_year
  • ComponentRangeError
  • ConversionRangeError
  • IndeterminateOffsetError
  • ParseError
  • NumericalDuration
  • NumericalStdDuration
  • NumericalStdDurationShort
  • All top-level macros
• Lazy formatting, which was unidiomatic as a failure would have returned fmt::Error, indicating an error unrelated to the time crate.
  • Time::lazy_format
  • Date::lazy_format
  • UtcOffset::lazy_format
  • PrimitiveDateTime::lazy_format
  • OffsetDateTime::lazy_format
• Support for stdweb has been removed, as the crate is unmaintained.
• The prelude module has been removed in its entirety.
• Date::iso_year_week in favor of Date::to_iso_week_date
• PrimitiveDateTime::iso_year_week
• OffsetDateTime::iso_year_week
• UtcOffset::east_hours
• UtcOffset::west_hours
• UtcOffset::hours
• UtcOffset::east_minutes
• UtcOffset::west_minutes
• UtcOffset::minutes
• UtcOffset::east_seconds
• UtcOffset::west_seconds
• UtcOffset::seconds
• Date::month_day
• PrimitiveDateTime::month_day
• OffsetDateTime::month_day
• Weekday::iso_weekday_number (identical to Weekday::number_from_monday)
• ext::NumericalStdDurationShort