Time v0.2 was an outstanding learning experience, and by all accounts is a massive improvement over v0.1. However, a number of ill-informed decisions were made which led to some inconsistencies and many deprecated APIs.

All deprecated methods and structs have ready-to-use alternatives, which will be detailed before a release. As such, I would like to remove all deprecated APIs. This currently includes the following.

Goals for v0.3:

• ~~Remove all deprecated APIs~~
• ~~Revamped parsing/formatting (#236)~~
• ~~un-constify is_leap_year and days_in_year for performance. On Rust ≥ 1.46, cfg_if_match and cfg_loop are stable, which allows re-enabling this without runtime performance loss. As a result, the only "loss" is un-constifying methods on older compilers.~~
• ~~Place macros behind a feature flag.~~
• ~~Change a number of methods to return Result, including all UtcOffset constructors.~~
• ~~Rename try_from_* to just from_*.~~
• ~~#![no_alloc] support~~
• ~~Rename OffsetDateTime::timestamp and OffsetDateTime::timestamp_nanos to OffsetDateTime::unix_timestamp and OffsetDateTime::unix_timestamp_nanos respectively.~~
• ~~Stabilize serde representations~~

Anything stricken on the above list is completed. Anything that was previously on the list but was removed was either done in 0.2 (if it's not a breaking change) or abandoned.

Hello rustaceans! Until recently, the time crate was soft-deprecated, in that bug fixes would be considered, but no features would be actively added. It is the 25th most downloaded crate all-time, and is still being downloaded slightly more than chrono. As such, I began a bottom-up rewrite of the time crate, taking inspiration from time v0.1, chrono, the standard library, and some RFCs, along with some localization pulled in from glibc.

My goal is to release time v0.2 alongside Rust 1.40, which is currently scheduled to be released on December 19. By going to the community for a public review now, this will allow me sufficient time to make any necessary changes.

To view the documentation for the master branch, you can use time-rs.github.io. There are also some helpful shortcuts, so you can go to time-rs.github.io/Duration and be brought to the relevant documentation immediately.

Follows are two pages from the wiki, which provide some detail as to what will occur in the future and the differences between existing crates.

Differences from chrono and time v0.1

Chrono has been the de facto crate for time management for quite a while. Like time, its original implementation predates rust 1.0. Presumably due to its age, chrono still relies on time v0.1 (though it's partially inlined the relevant code). The disadvantage of this is that any third-party functions that rely on chrono essentially mandate you import chrono or time v0.1 to use its Duration type. This single fact makes interoperability with the standard library quite difficult. Time v0.1 is identical to chrono in this manner.

Time v0.1 is what the standard library was built upon. Time v0.2 flips this, being built upon the standard library. This provides for a higher-level abstraction, while also supporting the same targets as the standard library.

In time v0.2, there is full interoperability with the standard library. Every type can perform the same arithmetic that its standard library counterpart can and vice versa. Types are freely convertible to and from their standard library equivalents.

Vision

Scope

Most things that simplify handling of dates and times are in the scope of the time crate.

Some things are specifically not in scope.

• Nothing should implicitly rely on the system's time zone. Passing a time zone as a parameter or a function returning the time zone is acceptable. This restriction ensures that nothing surprising happens when running the same code on different systems.

Explicitly in scope, but not yet implemented include the following:

• Full timezone support, relying on tzdb.
• Period type, which would be usable with a zoned DateTime. While this would expose a similar (if not identical) API to Duration, the advantage is that it could take into account leap seconds, DST, etc. As such, a Period would not be directly convertible to a Duration - one minute could be either 59, 60, or 61 seconds.

Both lists are explicitly non-exhaustive. Additional items that are not in scope will be added to this list as they are brought up.

Strategy

Wherever possible, types are implemented as wrappers around those in the standard library. Additional functionality is still able to be provided, such as allowing a Duration to be negative.

Some types (like Sign) were helpful to implement generically, simplifying arithmetic implementations. They may be extracted to a separate crate in the future and re-exported in time.

Future plans

If all necessary reviews go well, my intent is to release time v0.2 shortly after the release of rust 1.40.

For post-v0.2 features, eventually I'd like to support tzdb, including automatic time zone shifts for DST and native leap second support. I'd also like to be able to have 5.seconds() be able to return either a time::Duration or std::time::Duration, but the compiler is currently unable to infer the return type and choose the appropriate trait to use.

Let me know your thoughts, positive or negative. All I ask is that you be constructive and follow the code of conduct. I can be reached on Matrix either via direct message or on the #time-rs channel.

because getenv and setenv are not thread-safe, localtime_r in time may data race with std::env::set_var in libstd.

I described this problem in chrono issue, and time is also affected.

Edit from @jhpratt:

Chrono users please see this comment.

As was previously possible in time 0.1 and as requested by multiple people in #197, I would like to add a function allowing the user to obtain their local UTC offset. This information would necessarily come from the operating system.

I do not have sufficient experience with C, let alone interaction with system APIs, so I am requesting this be implemented by those that know better than myself. libc and winapi should suffice as conditional dependencies to cover Linux, MacOS, and Windows. Support for Redox would be nice, but is not essential.

When implementing, the following signature should be used.

impl UtcOffset {
    fn local() -> Self;
}

I can put together docs and tests; it's the implementation itself where assistance is needed. The relevant file is src/utc_offset.rs. Replacing #![forbid(unsafe)] with #![deny(unsafe)] and #[allow]ing the relevant bits is, of course, allowed in this situation.

If you're interested, please leave a comment!

Maintainer's note: Yes, this crate is maintained. As of November 2019, a 0.2 release is in the works.

^{Original issue follows.}

The repo lives under the rust-lang-deprecated organisation. https://github.com/rust-lang/time redirects to this repo. Does that mean this crate is deprecated?

If this crate is indeed deprecated, what should I use as replacement?

In a recent project, I needed to parse date times in the ISO 8601 format (YYYYMMDDTHHMMSSZ). I managed to implement this using a format description, but this was quite hacky and will only work for UTC dates using the Z time zone specifier.

Do you think this would be a worthwhile addition? I can provide a PR if you're willing to consider it.

Given that #293 is closed, but in such a way that UtcOffset::local_offset_at and current_local_offset are essentially useless on unix without also enabling the unsound_local_offset config in rustc flags. So I'm creating a new issue to track a solution that makes getting the local offset usable on unix again.

Some possible ways this could be solved are:

1. Re-implement determining the offset, similar to what datetime_r does in pure rust. This will probably require reading zoneinfo files (see tzfile(5) man page).
2. Hook into the lock on the environment variable in std somehow, this probably requires exposing an api for that from std.

Hi! This makes progress towards (but does not fix) #339 (which still needs a [timestamp] format component). Regardless, I would use it in its current implementation.

This is what it looks like:

declare_format_string!(my_format, "hour=[hour], minute=[minute]");

#[derive(Serialize, Deserialize)]
struct SerializesWithCustom {
    #[serde(with = "my_format")]
    dt: OffsetDateTime,
}

Is this something you'd be interested in merging in (roughly) its current shape? If so, I'm happy to take care of renaming/documenting things.

Design notes

• I couldn't figure out a way to make #[serde(with = my_macro!())] work, since with expects a string.
• Similarly, wasn't sure whether ` - names were the first thing that popped into my head; please give better suggestions :)
• I may not have handled the feature-gating correctly.
• Clippy is complaining about to_invalid_serde_value because error::Format isn't copy, so I had to call it into_invalid_serde_value.
• If we want to implement these serializer modules in other crates (a normal use case), ,we have to make the {in,}to_invalid_serde_value functions public

The current implementation of format_description::well_known::Rfc3339 allows second 60 to occur in any time, which is then rolled back to the last nanosecond of 59. As leap seconds are only really allowed at 23:59:60 UTC, this behaviour feels way too loose.

Fortunately, there is always the full parsed date for the Rfc3339 format parser to look at. So it could compute the UTC time and check if the hour is 23 and the minute is 59, otherwise it should reject the parsed time. It might make sense to also check if it's the last day of the month, though I don't know if the language in ITU-R TF.460-6 is considered normative by the IERS.

Fixes #255.

This adds two modules fulfilling the requirements for serde's with-annotation: time::serde::timestamp::{self, option}.

As this requires a public module, I published the time::serde module. Would you prefer another place for this instead?

 └─  cargo c
    Updating crates.io index
       F       Fetch [================>                                      ]  31.39%                                                                                                        Downloaded time-macros v0.1.0
  Downloaded time-macros-impl v0.1.0
  Downloaded standback v0.2.2
  Downloaded proc-macro-hack v0.5.15
  Downloaded time v0.2.9
  Downloaded 5 crates (123.9 KB) in 0.91s
   Compiling syn v1.0.17
   Compiling rustversion v1.0.2
   Compiling standback v0.2.2
   Compiling proc-macro-hack v0.5.15
    Checking cfg-if v0.1.10
error[E0463]: can't find crate for `std`
  |
  = note: the `thumbv7em-none-eabihf` target may not be installed

error: aborting due to previous error

For more information about this error, try `rustc --explain E0463`.
error: could not compile `standback`.

To learn more, run the command again with --verbose.
warning: build failed, waiting for other jobs to finish...
error: build failed

I've started to implement proper ranges for the library. This pull request is not one that is ready to be merged with the main branch. Many functions don't have an implementation yet, and it still lacks some features I would like to add. But I would like some feedback before progressing in the direction I am going.

What is new

Here is a quick summary of what is present:

• Extention of the OffsetDateTime struct, adding functions likes floor_seconds(), ceil_seconds() and next_second(). They are necessary to the OffsetDateTimeRangeExt.
• Extension of the Range<OffsetDateTime> struct with functions like days(), full_days(), overlapping_days(), intersection(), union(), ...
• Extension of &[Range<OffsetDateTime>] slices (no functions implemented yet).

Important notes about ranges:

• You need two OffsetDateTime to create one range, so it was decided that the ranges will always work with the offset of the start datetime.
• If the ranges are reversed (end < start), most methods on this range will return None or an empty Vec.

Questions I might have

Should ranges implement the Copy trait ? The struct Range<OffsetDateTime> never changes, and doesn't implement the Iterator trait, so there shouldn't be any problem with this. I would like your feedback on the idea.

EDIT: You can't implement the Copy trait, as the Range struct is not defined inside the crate.

Coming improvements

• Implementing missing functions
• Implementing OffsetDateTimeExt for RangeInclusive
• Parsing & Formatting for ranges
• More unit tests
• Double sided iterators
• Range creation macro ?
• Similar functions for millis, micros and nanos ?

Thank you for maintaining the time crate! I recently migrated the Azure for SDK to it from the chrono crate. I like the design of time:OffsetDateTime much more than chrono::DateTime<T>. One thing that was missing that would be nice to see is RFC 1123 as a well known format. From #200, I see actix-web needed it and I'm sure there are many others.

from https://github.com/Azure/azure-sdk-for-rust/pull/965/files#diff-ee1e0429ff34efb8baedc932a7b765213e4ee67b4aaff384a18048144b6b535fR44-R86 :

/// RFC 1123: Requirements for Internet Hosts - Application and Support
///
/// https://www.rfc-editor.org/rfc/rfc1123
///
/// In Azure REST API specifications it is specified as `"format": "date-time-rfc1123"`.
///
/// In .NET it is the `rfc1123pattern`.
/// https://docs.microsoft.com/dotnet/api/system.globalization.datetimeformatinfo.rfc1123pattern
///
/// This format is also the preferred HTTP date format.
/// https://httpwg.org/specs/rfc9110.html#http.date
///
/// Sun, 06 Nov 1994 08:49:37 GMT
pub fn parse_rfc1123(s: &str) -> crate::Result<OffsetDateTime> {
    Ok(PrimitiveDateTime::parse(s, RFC1123_FORMAT)
        .with_context(ErrorKind::DataConversion, || {
            format!("unable to parse rfc1123 date '{s}")
        })?
        .assume_utc())
}

const RFC1123_FORMAT: &[FormatItem] = format_description!(
    "[weekday repr:short], [day] [month repr:short] [year] [hour]:[minute]:[second] GMT"
);

/// RFC 1123: Requirements for Internet Hosts - Application and Support
///
/// https://www.rfc-editor.org/rfc/rfc1123
///
/// In Azure REST API specifications it is specified as `"format": "date-time-rfc1123"`.
///
/// In .NET it is the `rfc1123pattern`.
/// https://docs.microsoft.com/dotnet/api/system.globalization.datetimeformatinfo.rfc1123pattern
///
/// This format is also the preferred HTTP date format.
/// https://httpwg.org/specs/rfc9110.html#http.date
///
/// Sun, 06 Nov 1994 08:49:37 GMT
pub fn to_rfc1123(date: &OffsetDateTime) -> String {
    date.to_offset(UtcOffset::UTC);
    // known format does not panic
    date.format(&RFC1123_FORMAT).unwrap()
}

RFC3339 Option<OffsetDateTime> parsing does not work for flattened structures. Example to reproduce:

use serde::{Deserialize, Serialize};
        use time::OffsetDateTime;

        #[derive(Serialize, Deserialize)]
        struct Nested {
            #[serde(default, with = "time::serde::rfc3339::option")]
            v1: Option<OffsetDateTime>,
            #[serde(default, with = "time::serde::rfc3339::option")]
            v2: Option<OffsetDateTime>,
            #[serde(default, with = "time::serde::rfc3339::option")]
            v3: Option<OffsetDateTime>,
        }

        #[derive(Serialize, Deserialize)]
        struct Container {
            #[serde(flatten)]
            nested: Nested,
        }

        let input = r#"
{
  "v2": null,
  "v3": "2022-02-20T22:42:42Z"
}
"#;

        let value: Container = serde_json::from_str(input).unwrap();
        let serialized = serde_json::to_string_pretty(&value).unwrap();

        assert_eq!(
            serialized,
            r#"{
  "v1": null,
  "v2": null,
  "v3": "2022-02-20T22:42:42Z"
}"#
        );

• On time 0.3.9, this fails with invalid type: null, expected an RFC3339-formatted Option<OffsetDateTime>
• On time 0.3.10, this fails with invalid type: Option value, expected an RFC3339-formatted OffsetDateTime (duplicate of #479)

I am porting my program from chrono to time. One thing I am stuck with is serializing a Vec<OffsetDateTime> with the rfc3339 format.

This seems like a small but very useful addition. Is this something that would be considered to be included?

I'm parsing a rfc3339-ish format with some flexibility (and UTC/Local offset selected out of band). I've ended up with the following incantation:

use time::{
    format_description::{modifier::*, Component, FormatItem::*},
    parsing::Parsed,
};
let mut p = Parsed::new()
    .with_hour_24(0)
    .unwrap()
    .with_minute(0)
    .unwrap()
    .with_second(0)
    .unwrap()
    .with_offset_hour(input_offset) // Work in progress ;)
    .unwrap();
let rest = p.parse_items(
    input_str.as_bytes(),
    &[
        Component(Component::Year(Year::default())),
        Literal(b"-"),
        Component(Component::Month(Month::default())),
        Literal(b"-"),
        Component(Component::Day(Day::default())),
        Optional(&Compound(&[
            First(&[Literal(b"T"), Literal(b" ")]),
            Component(Component::Hour(Hour::default())),
            Literal(b":"),
            Component(Component::Minute(Minute::default())),
            Optional(&Compound(&[
                Literal(b":"),
                Component(Component::Second(Second::default())),
            ])),
        ])),
    ],
)?;

That does the job, but I'd prefer using time::macros::format_description for readability (and maybe compile-time goodness, I'm not sure). But AFAICT it's missing support for optional, first, and compound.

Would it be possible to extend the grammar ?

Simple (and the most common, I believe) use case - you're implementing Display or Debug for your type containing some time objects, and you are provided with std::fmt::Formatter which implements std::fmt::Write trait. (maybe I'm missing something trivial, so apologies in advance if that's the case)

Current format_into implementations though require &mut impl std::io::Write which is a different beast, more complex and aimed at different stuff, with vectored writes, flushing and all the rest. If one were to choose between the two, wouldn't it make sense to support fmt::Write and not io::Write? Is there a clean alternative way?

(There's crates like fmt2io that provide hacky bridges but that's just ugly and wrong)