This release fixes the broken docrs.rs build of chrono 0.4.32.

What's Changed

• Make rkyv feature imply size_32 (#1383)
• Fixed typo in Duration::hours() exception (#1384, thanks @danwilliams)

In this release we shipped part of the effort to reduce the number of methods that could unexpectedly panic, notably for the DateTime and Duration types.

Chrono internally stores the value of a DateTime in UTC, and transparently converts it to the local value as required. For example adding a second to a DateTime needs to be done in UTC to get the correct result, but adding a day needs to be done in local time to be correct. What happens when the value is near the edge of the representable range, and the implicit conversions pushes it beyond the representable range? Many methods could panic on such inputs, including formatting the value for Debug output.

In chrono 0.4.32 the range of NaiveDate, NaiveDateTime and DateTime is made slightly smaller. This allows us to always do the implicit conversion, and in many cases return the expected result. Specifically the range is now from January 1, -262144 until December 31, 262143, one year less on both sides than before. We expect this may trip up tests if you hardcoded the MIN and MAX dates.

Duration had a similar issue. The range of this type was pretty arbitrary picked to match the range of an i64 in milliseconds. Negating an i64::MIN pushes a value out of range, and in the same way negating Duration::MIN could push it out of our defined range and cause a panic. This turns out to be somewhat common and hidden behind many layers of abstraction. We adjusted the type to have a minimum value of -Duration::MAX instead and prevent the panic case.

Other highlights:

• Duration gained new fallible initialization methods.
• Better support for rkyv.
• Most methods on NaiveDateTime are now const.
• We had to bump our MSRV to 1.61 to keep building with our dependencies. This will also allow us to make more methods on DateTime const in a future release.

Complete list of changes:

Fixes

• Fix panic in TimeZone::from_local_datetime (#1071)
• Fix out of range panics in DateTime getters and setters (#1317, #1329)

Additions

• Add NaiveDateTime::checked_(add|sub)_offset (#1313)
• Add DateTime::to_utc (#1325)
• Derive Default for Duration (#1327)
• Add Duration::subsec_nanos (#1327)
• Add try_* builders to Duration (#1327)
• Implement AddAssign and SubAssign for Duration (#1327)
• Make methods on NaiveDateTime const where possible (#1286)
• Split clock feature into clock and now (#1343, thanks @mmastrac)
• Add From<NaiveDate> for NaiveDateTime (#1355, thanks @dcechano)
• Add NaiveDateTime::from_timestamp_nanos (#1357, thanks @Ali-Mirghasemi)
• Add Months::num_months() and num_years() (#1373, thanks @danwilliams)
• Add DateTime<Utc>::from_timestamp_millis (#1374, thanks @xmakro)

Changes

• Fix panic in Duration::MIN.abs() (adjust Duration::MIN by 1 millisecond) (#1334)
• Bump MSRV to 1.61 (#1347)
• Update windows-targets requirement from 0.48 to 0.52 (#1360)
• Update windows-bindgen to 0.52 (#1379)

Deprecations

• Deprecate standalone format functions (#1306)

Documentation

• Improve doc comment and tests for timestamp_nanos_opt (#1299, thanks @mlegner)
• Switch to doc_auto_cfg (#1305, #1326)
• Document panics in Add/Sub impls and use expect (#1316)
• Improve types listed in top-level documentation (#1274)
• Improve deprecation note of TimeZone::datetime_from_str (#1342, thanks @tmccombs)
• Fix typos in Datelike impl for DateTime (#1376, thanks @ElectrifyPro)

Rkyv support

• Export Archived* types in rkyv module (#1304)
• Duplicate derives on Archived* types (#1271, thanks @Awpteamoose)
• Archive derive of PartialEq for rkyv (#959, thanks @mkatychev)
• Expose rkyv features as features for chrono users (#1368, thanks @gz)

Changes to unstable features

• Don't let unstable-locales imply the alloc feature (#1307)
• Remove format::{format_localized, format_item_localized} (#1311)
• Inline write_rfc2822_inner, don't localize (#1322)

Internal

• Add benchmark for DateTime::with_* (#1309)
• Fix *_DAYS_FROM_YEAR_0 calculation (#1312)
• Add NaiveTime::overflowing_(add|sub)_offset (#1310)
• Rewrite DateTime::overflowing_(add|sub)_offset (#1069)
• Tests calling date command set env LC_ALL (#1315, thanks @jtmoon79)
• Update deny.toml (#1320)
• Bump actions/setup-node from 3 to 4 (#1346)
• test.yml remove errant with: node-version (#1352, thanks @jtmoon79)
• CI Linting: Fix missing sources checkout in toml job (#1371, thanks @gibbz00)
• Silence clippy lint for test code with Rust 1.74.0 (#1362)

Thanks to all contributors on behalf of the chrono team, @djc and @pitdicker!

Another maintenance release.
It was not a planned effort to improve our support for UNIX timestamps, yet most PRs seem related to this.

Deprecations

• Deprecate timestamp_nanos in favor of the non-panicking timestamp_nanos_opt (#1275)

Additions

• Add DateTime::<Utc>::from_timestamp (#1279, thanks @demurgos)
• Add TimeZone::timestamp_micros (#1285, thanks @emikitas)
• Add DateTime<Tz>::timestamp_nanos_opt and NaiveDateTime::timestamp_nanos_opt (#1275)
• Add UNIX_EPOCH constants (#1291)

Fixes

• Format day of month in RFC 2822 without padding (#1272)
• Don't allow strange leap seconds which are not on a minute boundary initialization methods (#1283)
  This makes many methods a little more strict:
  • NaiveTime::from_hms_milli
  • NaiveTime::from_hms_milli_opt
  • NaiveTime::from_hms_micro
  • NaiveTime::from_hms_micro_opt
  • NaiveTime::from_hms_nano
  • NaiveTime::from_hms_nano_opt
  • NaiveTime::from_num_seconds_from_midnight
  • NaiveTime::from_num_seconds_from_midnight_opt
  • NaiveDate::and_hms_milli
  • NaiveDate::and_hms_milli_opt
  • NaiveDate::and_hms_micro
  • NaiveDate::and_hms_micro_opt
  • NaiveDate::and_hms_nano
  • NaiveDate::and_hms_nano_opt
  • NaiveDateTime::from_timestamp
  • NaiveDateTime::from_timestamp_opt
  • TimeZone::timestamp
  • TimeZone::timestamp_opt
• Fix underflow in NaiveDateTime::timestamp_nanos_opt (#1294, thanks @crepererum)

Documentation

• Add more documentation about the RFC 2822 obsolete date format (#1267)

Internal

• Remove internal __doctest feature and doc_comment dependency (#1276)
• CI: Bump actions/checkout from 3 to 4 (#1280)
• Optimize NaiveDate::add_days for small values (#1214)
• Upgrade pure-rust-locales to 0.7.0 (#1288, thanks @jeremija wo did good improvements on pure-rust-locales)

Thanks to all contributors on behalf of the chrono team, @djc and @pitdicker!

In this release, we have decided to swap out the chrono::Duration type (which has been a re-export of time 0.1 Duration type) with our own definition, which exposes a strict superset of the time::Duration API. This helps avoid warnings about the CVE-2020-26235 and RUSTSEC-2020-0071 advisories for downstream users and allows us to improve the Duration API going forward.

While this is technically a SemVer-breaking change, we expect the risk of downstream users experiencing actual incompatibility to be exceedingly limited (see our analysis of public code using a crater-like experiment), and not enough justification for the large ecosystem churn of a 0.5 release. If you have any feedback on these changes, please let us know in #1268.

Additions

• Add NaiveDate::leap_year (#1261)

Documentation

• Update main documentation from README (#1260, thanks @Stygmates)
• Add history of relation between chrono and time 0.1 to documentation (#1264, #1266)
• Clarify Timelike::num_seconds_from_midnight is a simple mapping (#1255)

Relation between chrono and time 0.1

Rust first had a time module added to std in its 0.7 release. It later moved to libextra, and then to a libtime library shipped alongside the standard library. In 2014 work on chrono started in order to provide a full-featured date and time library in Rust. Some improvements from chrono made it into the standard library; notably, chrono::Duration was included as std::time::Duration (rust#15934) in 2014.

In preparation of Rust 1.0 at the end of 2014 libtime was moved out of the Rust distro and into the time crate to eventually be redesigned (rust#18832, rust#18858), like the num and rand crates. Of course chrono kept its dependency on this time crate. time started re-exporting std::time::Duration during this period. Later, the standard library was changed to have a more limited unsigned Duration type (rust#24920, RFC 1040), while the time crate kept the full functionality with time::Duration. time::Duration had been a part of chrono's public API.

By 2016 time 0.1 lived under the rust-lang-deprecated organisation and was not actively maintained (time#136). chrono absorbed the platform functionality and Duration type of the time crate in chrono#478 (the work started in chrono#286). In order to preserve compatibility with downstream crates depending on time and chrono sharing a Duration type, chrono kept depending on time 0.1. chrono offered the option to opt out of the time dependency by disabling the oldtime feature (swapping it out for an effectively similar chrono type). In 2019, @jhpratt took over maintenance on the time crate and released what amounts to a new crate as time 0.2.

Security advisories

In November of 2020 CVE-2020-26235 and RUSTSEC-2020-0071 were opened against the time crate. @quininer had found that calls to localtime_r may be unsound (chrono#499). Eventually, almost a year later, this was also made into a security advisory against chrono as RUSTSEC-2020-0159, which had platform code similar to time.

On Unix-like systems a process is given a timezone id or description via the TZ environment variable. We need this timezone data to calculate the current local time from a value that is in UTC, such as the time from the system clock. time 0.1 and chrono used the POSIX function localtime_r to do the conversion to local time, which reads the TZ variable.

Rust assumes the environment to be writable and uses locks to access it from multiple threads. Some other programming languages and libraries use similar locking strategies, but these are typically not shared across languages. More importantly, POSIX declares modifying the environment in a multi-threaded process as unsafe, and getenv in libc can't be changed to take a lock because it returns a pointer to the data (see rust#27970 for more discussion).

Since version 4.20 chrono no longer uses localtime_r, instead using Rust code to query the timezone (from the TZ variable or via iana-time-zone as a fallback) and work with data from the system timezone database directly. The code for this was forked from the tz-rs crate by @x-hgg-x. As such, chrono now respects the Rust lock when reading the TZ environment variable. In general, code should avoid modifying the environment.

Removing time 0.1

Because time 0.1 has been unmaintained for years, however, the security advisory mentioned above has not been addressed. While chrono maintainers were careful not to break backwards compatibility with the time::Duration type, there has been a long stream of issues from users inquiring about the time 0.1 dependency with the vulnerability. We investigated the potential breakage of removing the time 0.1 dependency in chrono#1095 using a crater-like experiment and determined that the potential for breaking (public) dependencies is very low. We reached out to those few crates that did still depend on compatibility with time 0.1.

As such, for chrono 0.4.30 we have decided to swap out the time 0.1 Duration implementation for a local one that will offer a strict superset of the existing API going forward. This will prevent most downstream users from being affected by the security vulnerability in time 0.1 while minimizing the ecosystem impact of semver-incompatible version churn.

Thanks to all contributors on behalf of the chrono team, @djc and @pitdicker!

This release fixes a panic introduced in chrono 0.4.27 in FromStr<DateTime<Utc>> (#1253).

Chrono now has a Discord channel.

Fixes

• Fix arbitrary string slicing in parse_rfc3339_relaxed (#1254)

Deprecations

• Deprecate TimeZone::datetime_from_str (#1251)

Documentation

• Correct documentation for FromStr for Weekday and Month (#1226, thanks @wfraser)

Internal improvements

• Revert "add test_issue_866" (#1238)
• CI: run tests on i686 and wasm32-wasi (#1237)
• CI: Include doctests for code coverage (#1248)
• Move benchmarks to a separate crate (#1243)
  This allows us to upgrade the criterion dependency to 5.1 without changing our MSRV.
• Add Discord link to README (#1240, backported in #1256)

Thanks to all contributors on behalf of the chrono team, @djc and @pitdicker!

This release fixes a test failure on 32-bit targets introduced with 0.4.27, see #1234.

This release bumps the MSRV from 1.56 to 1.57. This allows us to take advantage of the panicking in const feature. In this release most methods on NaiveDate and NaiveTime are made const, NaiveDateTime and others will follow in a later release.

The parser for the %+ formatting specifier and the RFC3339 formatting item is switched from a strict to a relaxed parser (see #1145). This matches the existing documentation, and the parser used by DateTime::from_str. If you need to validate the input, consider using DateTime::from_rfc3339.

Deprecations

• Deprecate DateTime::{from_local, from_utc} (#1175)

Additions

• Let DateTime::signed_duration_since take argument with Borrow (#1119)
• Implement PartialOrd for Month (#999, thanks @Munksgaard)
• Add Ord and Eq for types which already derive PartialOrd and PartialEq (#1128, thanks @totikom)
• implement FusedIterator for NaiveDateDaysIterator and NaiveDateWeeksIterator (#1134)
• Make NaiveDateDaysIterator and NaiveDateWeeksIterator public (#1134)
• Add FromStr for FixedOffset (#1157, thanks @mcronce)
• Remove Tz::Offset: Display requirement from DateTime::to_rfc* (#1160)
• More flexible offset formatting (not exposed yet) (#1160)
• Make StrftimeItems with unstable-locales work without allocating (#1152)
• Make NaiveDate::from_ymd_opt const (#1172, thanks @kamadorueda)
• Implement Error trait for ParseWeekdayError and ParseMonthError (#539, thanks @mike-kfed)
• Make methods on NaiveTime const, update MSRV to 1.57 (#1080)
• Make methods on NaiveDate const (#1205)
• Implement operations for core::time::Duration on DateTime types (#1229)

Fixes

• Ensure timestamp_nanos panics on overflow in release builds (#1123)
• Fix offset_from_local_datetime for wasm_bindgen (#1131)
• Parsing: Consider %s to be a timestamp in UTC (#1136)
• Don't panic when formatting with %#z (#1140, thanks @domodwyer)
• Parsing: allow MINUS SIGN (U+2212) in offset (#1087, thanks @jtmoon79)
• Fix locale formatting for %c and %r (#1165)
• Localize decimal point with unstable-locales feature (#1168)
• Fix panic on macOS 10.12 caused by using version 1 of the TZif file format (#1201, thanks to help from @jfro)
• Fix deserialization of negative timestamps (#1194)
• Do not use Offset's Debug impl when serializing DateTime (#1035)
• Allow missing seconds in NaiveTime::from_str (#1181)
• Do not depend on android-tzdata if the clock feature is not enabled (#1220, thanks @AlexTMjugador)
• Small fixes to the RFC 3339 parsers (#1145)

Documentation

• Add "Errors" and "Panics" sections to API docs (#1120)
• Specify licenses in SPDX format (#1132, backport of #910, thanks @LingMan)
• Fix NaiveTime doc typo (#1146, thanks @zachs18)
• Clarify nanosecond formatting specifier doc (#1173)
• Add warning against combining multiple Datelike::with_* (#1199)
• Fix typo "accepted" (#1209, thanks @simon04)
• Add some examples to Utc::now and Local::now (#1192)
• Add example to Weekday::num_days_from_monday (#1193)
• Fix some comments and panic messages (#1221, thanks @umanwizard)

Internal improvements

• DateTime::to_rfc_* optimizations (#1200)
• Move all tests into modules, fix clippy warnings (#1138)
• Offset parsing cleanup (#1158)
• Factor out formatting to format/formatting.rs (#1156)
• Format refactorings (#1198)
• Format toml files with taplo (#1117, thanks @tottoto)
• Stop vendoring saturating_abs (#1124)
• CI: shell set -eux, use bash (#1103, thanks @jtmoon79)
• Fix dead code error when running dateutils test on Windows (#1125)
• Remove Makefile (#1133)
• CI: Test wasm-bindgen feature (#1131)
• Stop using deprecated methods in parse module (#1142)
• Add formatting benchmarks (#1155)
• Feature gate tests instead of methods (#1159, #1162)
• Parallelize try_verify_against_date_command (#1161)
• CI: also run integration tests with no_std (#1166)
• Split test_parse (#1170)
• Remove #![deny(dead_code)] (#1187)
• Clippy fixes for Rust 1.71 (#1186)
• Various small improvements (#1191)
• Add unit test for uncovered regions (#1149, thanks @CXWorks)
• Don't test the same thing twice in test_date_extreme_offset (#1195)
• CI: Add workflow code coverage report and upload (#1178, #1215, thanks @jtmoon79)
• CI: fail on warnings in features-check (#1216)
• Switch to windows-bindgen (#1202, thanks to help from @MarijnS95)

Thanks to all contributors on behalf of the chrono team, @djc and @pitdicker!

The changes from #807 we merged for 0.4.25 unfortunately restricted parsing in a way that was incompatible with earlier 0.4.x releases. We reverted this in #1113. A small amount of other changes were merged since.

• Update README (#1111, thanks to @pitdicker)
• Revert backport of #807 (#1113, thanks to @pitdicker)
• Update to 2021 edition (#1109, thanks to @tottoto)
• Fix DurationRound panics from issue #1010 (#1093, thanks to @pitdicker)
• tests: date path consolidate (branch 0.4.x) (#1090, thanks to @jtmoon79)
• Parse tests nanosecond bare dot (branch 0.4.x) (#1098, thanks to @jtmoon79)
• yamllint cleanup lint.yml test.yml (#1102, thanks to @jtmoon79)
• Remove num-iter dependency (#1107, thanks to @tottoto)

Thanks on behalf of the chrono team (@djc and @esheppa) to all contributors!

Time for another maintenance release. This release bumps the MSRV to 1.56; given MSRV bumps in chrono's dependencies (notably for syn 2), we felt that it no longer made sense to support any older versions. Feedback welcome in our issue tracker!

Additions

• Bump the MSRV to 1.56 (#1053)
• Apply comments from MSRV bump (#1026, thanks to @pitdicker)
• Remove num-integer dependency (#1037, thanks to @pitdicker)
• Add NaiveDateTime::and_utc() method (#952, thanks to @klnusbaum)
• derive Hash for most pub types that also derive PartialEq (#938, thanks to @bruceg)
• Add parse_and_remainder() methods (#1011, thanks to @pitdicker)
• Add DateTime::fix_offset() (#1030, thanks to @pitdicker)
• Add #[track_caller] to LocalResult::unwrap (#1046, thanks to @pitdicker)
• Add #[must_use] to some methods (#1007, thanks to @aceArt-GmbH)
• Implement PartialOrd for Month (#999, thanks to @Munksgaard)
• Add impl From<NaiveDateTime> for NaiveDate (#1012, thanks to @pezcore)
• Extract timezone info from tzdata file on Android (#978, thanks to @RumovZ)

Fixes

• Prevent string slicing inside char boundaries (#1024, thanks to @pitdicker)
• fix IsoWeek so that its flags are always correct (#991, thanks to @moshevds)
• Fix out-of-range panic in NaiveWeek::last_day (#1070, thanks to @pitdicker)
• Use correct offset in conversion from Local to FixedOffset (#1041, thanks to @pitdicker)
• Fix military timezones in RFC 2822 parsing (#1013, thanks to @pitdicker)
• Guard against overflow in NaiveDate::with_*0 methods (#1023, thanks to @pitdicker)
• Fix panic in from_num_days_from_ce_opt (#1052, thanks to @pitdicker)

Refactoring

• Rely on std for getting local time offset (#1072, thanks to @pitdicker)
• Make functions in internals const (#1043, thanks to @pitdicker)
• Refactor windows module in Local (#992, thanks to @nekevss)
• Simplify from_timestamp_millis, from_timestamp_micros (#1032, thanks to @pitdicker)
• Backport #983 and #1000 (#1063, thanks to @pitdicker)

Documentation

• Backport documentation improvements (#1066, thanks to @pitdicker)
• Add documentation for %Z quirk (#1051, thanks to @campbellcole)
• Add an example to Weekday (#1019, thanks to @pitdicker)

Internal improvements

• Gate test on clock feature (#1061, thanks to @pitdicker)
• CI: Also run tests with --no-default-features (#1059, thanks to @pitdicker)
• Prevent bench_year_flags_from_year from being optimized out (#1034, thanks to @pitdicker)
• Fix test_leap_second during DST transition (#1064, thanks to @pitdicker)
• Fix warnings when running tests on Windows (#1038, thanks to @pitdicker)
• Fix tests on AIX (#1028, thanks to @ecnelises)
• Fix doctest warnings, remove mention of deprecated methods from main doc (#1081, thanks to @pitdicker)
• Reformat test_datetime_parse_from_str (#1078, thanks to @pitdicker)
• GitHub yml shell set -eux, use bash (#1103, thanks to @jtmoon79)
• test: explicitly set LANG to c in gnu date (#1089, thanks to @scarf005)
• Switch test to TryFrom (#1086, thanks to @pitdicker)
• Add test for issue 551 (#1020, thanks to @pitdicker)
• RFC 2822 single-letter obsolete tests (#1014, thanks to @jtmoon79)
• [CI] Lint Windows target and documentation links (#1062, thanks to @pitdicker)
• add test_issue_866 (#1077, thanks to @jtmoon79)
• Remove AUTHORS metadata (#1074)

On behalf of @djc and @esheppa, thanks to all contributors!

This is a small maintenance release with accumulated fixes and improvements.

• Fix doc on Days::new() to refer to days, not months (#874, thanks to @brotskydotcom)
• Clarify out of range value for from_timestamp_opt() (#879, thanks to @xmo-odoo)
• Add format_localized() for NaiveDate (#881, thanks to @mseele)
• Fix bug in Add/Sub Days, add tests with DST timezone (#878)
• Make NaiveTime::MIN public (#890)
• Fix from_timestamp_millis() implementation and add more tests (#885)
• Fix typo in docstrings (#897, thanks to @dandxy89)
• Add test proving that #903 is fixed in 0.4.x head (#905, thanks to @umanwizard)
• Add from_timestamp_micros() function (#906, thanks to @umanwizard)
• Check cargo-deny in CI (#909)
• Derive Hash for most pub types that also derive PartialEq (#938, thanks to @bruceg)
• Update deprecated methods in from_utc() example (#939, thanks to @greg-el)
• Fix panic in DateTime::checked_add_days() (#942, thanks to @Ekleog)
• More documentation for dates before 1 BCE or after 9999 CE (#950, thanks to @cgit)
• Improve FixedOffset docs (#953, thanks to @klnusbaum)
• Add chrono-fuzz to CI and update its libfuzzer-sys dependency (#968, thanks to @LingMan)
• Fixes to parsing and calculation of week numbers (#966, thanks to @raphaelroosz)
• Make iana-time-zone a target specific dependency (#980, thanks to @krtab)
• Make eligible functions const (#984, thanks to @tormeh)

Thanks to all contributors from the chrono team, @esheppa and @djc.