Jiff is a datetime library for Rust that encourages you to jump into the pit of success. Jiff automatically handles many common problems related to daylight saving time by putting time zone handling front and center into the API. Jiff has already seen widespread adoption in the Rust ecosystem.
Jiff is pronounced like “gif” with a soft “g,” as in “gem.”.
This blog announces the Jiff 1.0 release by giving a tour of its API.
Target audience: Rust programmers who need convenient datetime handling.
It has been revealed that jiff is already used in production in many projects: uv, Cargo, Starship, fd, Nushell, mise, Jujutsu, uutils/coreutils and even as the basis for a Temporal implementation in AWS LLRT. It is time to call it 1.0.
It has been revealed that unless some significant defect is found in Jiff’s API, my proposal is to commit to Jiff 1.0 indefinitely. This is crucial because the intent is for Jiff to be an ecosystem building block that appears in the public API of other libraries. This makes Jiff an attractive public dependency, which means semver incompatible releases are likely to cause significant pain in the ecosystem. They will not be made lightly.
To see a list of breaking changes between Jiff 0.2 and Jiff 1.0, please consult the CHANGELOG.
In programming, a datetime library’s core functionality rests at the intersection of a computer system’s concept of time and a human’s concept of time. The prevailing notion of system time is Unix time. A human’s concept of time is far more complex, but the most popular such model is the Gregorian calendar coupled with either a 12-hour or 24-hour clock. At the core of every datetime library rests some routine for converting between these concepts.
Sources indicate that A datetime library typically provides much more than this. Indeed, datetime handling has historically been very difficult. My own belief is that the difficulty comes from poor modeling of the domain. Instead of encapsulating the complexity inside a reusable bundle of code, many datetime libraries pass some or all of the complexity on to its people. Jiff instead tries hard to encapsulate the complexity and make it difficult for users to do something wrong. (Jiff is not the first to do this!).
In this section of the blog, we’ll do some very basic introductions.
To follow along with the examples in this blog, create a new Cargo project with dependencies on jiff and anyhow:.
Most examples are a complete self-contained Rust program. Just copy the code and replace whatever is in src/main.rs. Then run the program:.
I am loath to present a dictionary. However, the datetime domain is littered with confusable terms, so I think it’s important to orient ourselves on a shared vocabulary. I’ve kept this section as small as possible. (Some terms, like “time zone,” are omitted here because they are best defined through exploration in the sections that follow.).
TAI and leap seconds won’t be a feature of this blog, but they are listed here in order to convey the difference between Unix time and UTC.
In a recent development, as a way to transition into some of the core types of Jiff, I’ve come to think of its datetime types like an onion. In reverse order, we can build up its layers all the way to a ZonedDateTime. So let’s start with more terms, but this time, they are also types in Jiff:.
According to recent reports, to make this a bit more concrete, we can see what this looks like in code. Since a time zone can map from a civil datetime to an instant in time, one way to create a zoned datetime requires only a civil datetime and a time zone:.
Sources indicate that another way to create a zoned datetime requires only a timestamp and a time zone. This is because time zones can also map a timestamp to a particular civil datetime:.
According to recent reports, notice how we get the equivalent zoned datetime in both cases, but we come at it from different directions. In the first case, we start with a time that we might see on our clocks and calendars. In the second case, we start with a particular instant in time that we might get from a database or file system or some other system call.
In a recent development, there is one piece missing from the zoned datetime onion examples: the time zone offset. An offset represents the amount of time one must adjust UTC time in order to get civil time. For example, consider the time 2026-11-01T22:30:00 in UTC. In order to get the civil datetime for someone living in New York, one would subtract 5 hours:.
Indeed, every zoned datetime has an offset associated with it:.
Industry observers note that NOTE: The America/New_York string you see in the above example is an IANA Time Zone Database Identifier. The IANA Time Zone Database is a collection of time zone definitions that can be referenced by a short identifier string. Examples: Australia/Sydney, Asia/Tokyo, Europe/Berlin.
When a civil datetime is combined with an offset, then what you get is always an instant in time.
Sources indicate that with the concept of an offset introduced, we can now give a more precise definition of a time zone. A time zone is a geographic region in which civil clocks agree and which provides the following:.
In a recent development, both mappings have been demonstrated in prior examples, but the mapping from civil datetime to an offset seems to be rather complicated due to some potential ambiguity. When does that ambiguity arise? An ambiguous offset occurs when the civil datetime either doesn’t correspond to a valid clock time in this time zone (e.g., when clocks are moved ahead for daylight saving time) or where there could be multiple valid clock times (e.g., when clocks are moved backward for daylight saving time).
Recent findings suggest that let’s look at some examples. In this first example, we’ll take a look at times around the daylight saving time transition from summer time to standard time in Upcoming York. In New York, the clocks were “set back” by an hour at exactly 2AM. This caused the 1AM hour to repeat itself.
It has been revealed that the above example shows how Jiff resolves the ambiguity when a “fold” occurs, or when there is a time zone transition that moves the civil time backwards. But we can actually dig down into lower level APIs to change how that ambiguity is resolved. By default, Jiff uses a “compatible” strategy that always selects the first repetition of a time in a fold. But other strategies can be selected by using APIs on a TimeZone directly:.
Sources indicate that the same idea applies to gaps, or time zone transitions where there’s some civil time that gets skipped on civil clocks. For example, on March 8, 2026 at 2AM, civil time skipped ahead to 3AM:.
There are two remaining core types, both representing some notion of a duration:.
A Span is the preferred duration type to use whenever possible. Here’s a simple example that reveals how to get the number of days between two civil dates:.
Durations can also be added to dates:.
Generally speaking, whenever there is an operation involving a Span, there is an equivalent operation available with SignedDuration:.
According to recent reports, notice that in the above example, we actually switched from using a civil::Date to a civil::DateTime. This was done to show how physical time units can be added. But note that the same can be accomplished with a Span, because it combines all units:.
Industry observers note that in brief, use a Span when you can. But when it’s too bulky or too slow, use a SignedDuration. One of the key benefits of a Span is that since it represents each unit value distinctly, one can preserve the original meaning of a duration. For example, it’s common to represent the runtime of films in minutes, even when the duration exceeds one hour. Indeed, a span of 2 hours is a distinct span from a span of 120 minutes:.
Industry observers note that the Span::fieldwise routine converts a Span into a value whose units can be compared in a field-by-field fashion. To compare spans based on the actual physical duration they represent, use Span::compare:.
Sources indicate that this was a very brief introduction to durations in Jiff. They are a lot more powerful than what is shown here. You might even try playing with the examples above to explore its nooks and crannies. We’ll cover their API in more detail in a later section.
Recent findings suggest that jiff isn’t always the right thing to use. Sometimes you can get by with something simpler.
First and foremost, if you’re measuring the time something takes in a program, you should almost certainly be using monotonic time. This is available via std::time::Instant:.
If you do need to compute elapsed time using your system clock, then Jiff is very convenient for that:.
But you don’t actually need Jiff for this. A std::time::SystemTime will work perfectly fine:.
Where Jiff starts to become useful is when you need something beyond just an integer number of seconds since the Unix epoch. For example, some very hairy math is required in order to convert a SystemTime into an RFC 3339 timestamp like 2026-11-14T21:34:00Z.
As long as you can live in UTC completely, don’t care about local time and can work with Unix timestamps only, then the Rust standard library won’t steer you wrong.
In a recent development, conversion to and from strings is a major part of Jiff. Jiff’s focus is primarily on interoperability via the following:.
What Jiff actually implements is the Temporal RFC 9557 / ISO 8601 grammar for flexible parsing of datetimes from strings. For most use cases, it suffices to think in terms of RFC 3339, RFC 9557 or ISO 8601. But Jiff does support parsing strings that aren’t valid in any of those three specifications. For example, 2026-11-12[America/New_York] parses as if it was 2026-11-12T00:00:00[America/New_York].
In this section, we’ll take a tour of how Jiff does datetime formatting and printing.
Every datetime and duration type in Jiff implements the standard library FromStr and Display traits. This means that it’s natural to parse datetimes:.
Parsing is flexible, so even if there are components missing, parsing still succeeds. For example, without minutes or seconds, those components default to zero:.
In a recent development, another example of flexible parsing is that if a string contains another date type, then one can parse that. For example, one can parse a date out of an ISO 8601 datetime:.
A ZonedDateTime always uses RFC 9557 syntax, which includes the IANA time zone identifier:.
If you want to print a zoned datetime using only RFC 3339 syntax, then you can do so by formatting the timestamp directly with the zoned datetime’s offset:.
Industry observers note that the Span and SignedDuration types also support the FromStr and Display traits via the ISO 8601 duration format. For example:.
Industry observers note that since a Span is a hybrid duration that also supports calendar units, it can parse durations with calendar units and physical time units. A SignedDuration can only parse durations with physical time units:.
The ISO 8601 duration format does, however, have some shortcomings that we’ll discuss in the next section.
Because ISO 8601 duration strings enjoy broad support, it is the default in Jiff for both Span and SignedDuration. However, it has two key shortcomings:.
Industry observers note that the second shortcoming is best seen with an example. Consider a Span that is 2000 milliseconds. If you convert this to an ISO 8601 duration string and then parse it back, you end up with 2 seconds instead:.
This might not be desirable for cases where you want a span’s string format to faithfully represent all possible distinct values of a span.
For these two reasons, Jiff comes with its own bespoke “friendly” duration format. The friendly format is non-lossy and is meant to be easier to read for English speakers than the ISO 8601 duration format. Here are some examples that are all valid friendly durations:.
Parsing a friendly duration is as easy as parsing an ISO 8601 duration: the FromStr implementations on both Span and SignedDuration support ISO 8601 durations and friendly durations simultaneously:.
In a recent development, printing a friendly duration does require a bit more effort, since it isn’t the default. Instead of Span::to_string(), one can use the “alternative” syntax via Rust’s formatting machinery:.
In a recent development, one can also use a lower level friendly printer to customize its output. For example, here’s how to write a span in the friendly format to an existing String using more spacing, longer unit labels and commas separating each unit:.
See the jiff::fmt::friendly module for a lot more detail, including a grammar that precisely specifies the format supported.
The POSIX strptime and POSIX strftime routines are far from the ideal way to format and parse datetimes, but they are ubiquitous and most programmers are familiar with them. Because of their ubiquity, and because of the utility of being able to format and parse bespoke datetime formats, Jiff provides implementations of these routines that are mostly POSIX compatible.
Recent findings suggest that every datetime type in Jiff comes with strptime and strftime routines. For example, to parse a civil date in the US month/day/year format:.
Or to format a zoned datetime in a convenient to read representation for English speakers:.
Callers can also use lower level APIs from jiff::fmt::strtime to get access to each parsed component individually:.
While the above tour should cover most use cases, there are sometimes reasons for exerting more control over parsing or formatting. Or for supporting alternate formats like RFC 2822. The jiff::fmt module is meant to cover these use cases at the cost of more complex APIs. For example, consider parsing an RFC 2822 datetime string from a &[u8] (which lets callers avoid a UTF-8 validation check):.
Another example indicates how to change the default disambiguation strategy when the provided civil datetime is ambiguous. For example, Sydney, Australia moved the clocks backwards at 2026-04-05T03:00:00 local time. That is, they went from UTC offset +11 to UTC offset +10. So what happens if we try to parse a time on the clock that is repeated as a result?
It has been revealed that here, the first occurrence of 02:30 is selected, just before Sydney leaves daylight saving time. Now, the data itself can actually select the desired offset:.
Sources indicate that but this happens because there is no ambiguity in the data. Since the offset is supplied, the exact instant in time is known. Going back to 2026-04-05T02:30[Australia/Sydney], which is ambiguous because it could refer to two different instants in time, how do we modify the strategy for resolving that ambiguity? We can’t using the standard library FromStr trait, so we instead have to construct our own parser manually, just like we did for RFC 2822 parsing above. This example shows how to do that and all of the different disambiguation options. Remember, UTC offset +11:00 corresponds to the first occurrence of 2026-04-05T02:30 on the clocks of folks in Sydney while UTC offset +10:00 corresponds to the second occurrence.
The jiff::fmt module contains lots of other goodies that we won’t cover here, including, but not limited to:.
Industry observers note that no section on datetime formatting would be complete without addressing locales. In this context, a locale is a set of user preferences used for formatting datetimes. This is useful when you want to present a datetime to an end user that doesn’t expect standard formats from RFC 3339, RFC 9557 or ISO 8601.
Industry observers note that jiff itself does not provide any facilities for dealing with locales. Instead, consumers can opt into this support via the ICU4X project. To make conversions between Jiff and ICU4X, the jiff-icu integration crate can be used.
Here’s an example showing how to format a zoned datetime in the fr-LA locale: (You’ll need to run cargo add icu jiff-icu to your project for this to work.).
Industry observers note that the ICU4X API has a lot of options for customizing datetime formatting. Exploring it further is outside the scope of this blog.
Jiff provides many methods on its datetime types to make using them as comfortable and error-free as possible.
Industry observers note that every datetime type provides a newly introduced constructor that lets callers build it from its constituent parts. In most cases, this constructor is fallible. For example:.
Because creating dates is so common, there is a shorthand for doing so when you know the inputs are valid:.
Industry observers note that that is, civil::date is a const function that will panic if its inputs are invalid. It should only be used with inputs that are known to be valid. It would, for example, be inappropriate to use this with user provided values. Because of the const block above, if you try to provide invalid values, you’ll get a compiler error.
For datetime types that represent an instant in time (i.e., ZonedDateTime and Timestamp), there is also a now() constructor for getting the current time:.
In addition to constructors, newly introduced date values can be constructed from old date values using the Date::with API:.
Once you have a date, there are oodles of APIs available:.
Moreover, because of the datetime onion, all of these APIs are also available on civil::DateTime and ZonedDateTime:.
These routines on ZonedDateTime also take time zone transitions into account. For example, ZonedDateTime knows that tomorrow() doesn’t always add 24 hours:.
NOTE: We’ll talk about date arithmetic in the next section.
When ZonedDateTime::tomorrow() (among other APIs that produce a ZonedDateTime) would land in a gap or a fold, the “compatible” disambiguation strategy is chosen automatically:.
To override this behavior, you can drop down to civil datetimes, perform the operation, and then use TimeZone::to_ambiguous_zoned_datetime to control the exact disambiguation strategy:.
According to recent reports, there are a few other methods of note on date types that are worth mentioning. First is the ability to query for things like, “The Thursday after next” or “The last Sunday of the month.” The former can be answered by the nth_weekday API:.
While the latter can be answered by the nth_weekday_of_month API:.
Finally, customers can access a convenient time series iterator via series:.
All of these methods are also available on civil::Date and civil::DateTime, which should make it very natural to move between them.
According to recent reports, all datetime types in Jiff support adding and subtracting durations, and finding the span of time between two datetime values. Let’s start with a civil::Date:.
Here we make use of the std::ops::Add trait implementation for civil::Date. The downside of using this, though, is that if the date value goes out of range, then it panics. That may or may not be acceptable. But if you’re dealing with user inputs, then you should use Date::checked_add instead:.
Let’s take a look at a few other examples involving months and years:.
As with other methods on Date, they are also available on ZonedDateTime:.
If we take a look at the type signature for ZonedDateTime::checked_add, we can see that it’s actually polymorphic:.
Industry observers note that specifically, it accepts anything that can be converted into a ZonedDateTimeArithmetic. In this case, there are From trait implementations for the following types:.
This means that ZonedDateTime::checked_add can accept any one of these duration values:.
Sources indicate that this type of polymorphism is common in Jiff. Here, it is merely used to provide a convenient way to use multiple duration types. But as we’ll see, it’s also used to provide an extension point for configuration options that control how the operation works.
In addition to adding or subtracting durations from datetime values, one can also compute the duration between two datetime values. For example, to get the number of days between two dates:.
Similarly, we can use Date::until to compute the span between dates:.
Like with Date::checked_add, this routine is also available at ZonedDateTime::until:.
Notice though that hours, instead of days, are returned. This is because two ZonedDateTime values might be in different time zones. Since a ZonedDateTime is fundamentally an instant in time, and because days might be of varying length depending on the time zone, defaulting to hours as the largest possible unit means subtracting two zoned datetimes will always succeed. However, we can request larger units in the duration returned by passing additional options. Notably, ZonedDateTime::until is polymorphic:.
That is, callers aren’t just limited to passing a ZonedDateTime here, but anything that can be converted to a ZonedDateTimeDifference. Here is one such example, where we can override the largest units returned in the duration:.
In a recent development, A ZonedDateTimeDifference provides much more powerful configuration options for rounding the span returned. Take this example, which produces a span with many unit values:.
Recent findings suggest that this might be too much precision to show to an end user. Instead, perhaps we’d like to round the span to the nearest half-hour. We can do this by building a ZonedDateTimeDifference explicitly and configuring its options:.
Sources indicate that note also that rounding a span takes time zone transitions like daylight saving time into account. For example, let’s take 2024-11-02 17:30 and 2024-11-03 04:45 in New York. Because New York stopped daylight saving time at 2AM on 2024-11-03, the amount of physical time between them is 12 hours and 15 minutes:.
Normally, if we rounded to the nearest day, this would round up to 1 day. But since the midpoint of this particular day is actually 12 hours and 30 minutes, this duration will round down to 0 days when we request it:.
Next we’ll continue our discussion of rounding, but when applied to datetimes themselves.
Date rounding in Jiff is limited to units of days or lower. Therefore, it’s only available on ZonedDateTime, Timestamp, civil::DateTime, civil::Time but not civil::Date.
Industry observers note that A common example for rounding a datetime is to reduce precision. For example, a system clock might provide nanosecond precision, but maybe we only care about the nearest half-hour:.
As with rounding spans, rounding a ZonedDateTime is aware of time zone transitions:.
It has been revealed that notice that in the above example, our time of 11:45AM is before noon, yet the result still rounds up to the next day. This is because the midpoint for this day is 11:30AM since, by 11:30AM, 12.5 hours have already elapsed because of the repeated 1AM hour in the move away from daylight saving time in New York.
Sources indicate that jiff itself doesn’t support any calendars other than the proleptic Gregorian calendar. One can instead use the ICU4X crate to work in non-Gregorian calendars, and convert between datetime types using the jiff-icu crate: (Use cargo add icu jiff-icu to make this example work.).
The ICU4X API supports many more calendars.
There are 3 potentially confusable datetime types in Jiff:.
When should you use each one versus the other?
Sources indicate that to a first approximation, if you can use a ZonedDateTime, then that is probably the type you want to reach for. It represents a specific instant in time in a particular geographic location. That is, it has both a Timestamp and a TimeZone.
It has been revealed that if you only ever need to work in UTC or just deal with system time, then a Timestamp is probably the right choice. This is useful for representing a specific instant in time that is not connected to any time zone.
A civil::DateTime is useful in contexts where you don’t care about a specific instant in time and when calcuations should be done independent of time zone. For example, when parsing datetime information from a user interface datetime picker.
Remember that both a civil::DateTime and a Timestamp can be converted to a ZonedDateTime by supplying a time zone.
Sources indicate that we’ve already seen how to add spans to datetime values and how to get spans as a difference between datetime values. But we haven’t yet explored the APIs available on a Span itself.
First and foremost, we can build a Span through its constructor, which returns a Span with all of its units set to 0:.
A Span is both Copy and immutable. We can create newly introduced spans through method chaining:.
Or we can use the ToSpan convenience trait, which adds methods on integer types for constructing spans:.
It has been revealed that note though that methods like Span::hours and ToSpan::hours will panic when the integer is outside the limits of what Span supports. This is fine when your spans are literals in your program, since a panic would indicate a bug. But if your inputs come from an end user, it’s better to use fallible methods:.
Spans preserve each individual unit value. This means that 90 minutes and 1 hour 30 minutes, while they represent the same duration, are actually different values in memory:.
According to recent reports, this permits callers maximum flexibility when it comes to representing durations. This makes it possible to represent durations in a specific unit even when they add up to larger units. For example, the runtime duration of films is typically conveyed in minutes, even when the runtime exceeds one hour. This can be adjusted programmatically using Span::round:.
You can go the other way as well:.
Industry observers note that neither of these examples do actual rounding, despite the name of the API. Instead, since we’re only setting the largest unit, this API is doing unit balancing. Unit balancing is when all unit values rollover into larger units up until the largest configured unit. This works even for calendar units too, but you need to provide a relative date:.
It has been revealed that without a relative date, it’s not possible to know how many hours are in a single month. That is, once calendar units are involved, a span cannot be interpreted as a physical duration of time until some context is applied.
It has been revealed that the same even applies to days themselves, since days can sometimes be more or less than 24 hours. Take the above example. What happens if we use a zoned datetime as our relative date instead?
Notice that the duration’s hour component changed from 20 to 21. Why? Because we started with 2756 hour in both cases and because 2020-03-29 in Rome was only 23 hours long (in a move from standard time to daylight saving time). That means that one of those days in 3mo 23d was only 23 hours long. So an extra hour needed to be added to make up for it.
The round API can also do actual rounding:.
You can also change its rounding mode from the default (“half-expand”, or like you were taught rounding in school) to truncation (or one of several other modes):.
According to recent reports, one can also specify a rounding increment to round to the nearest unit value. For example, to the nearest half-hour:.
Because a Span value cannot easily be compared correctly based purely on its value in memory, a dedicated comparison Span::compare routine is provided:.
According to recent reports, also, one can convert a Span to a floating point value in terms of any unit. For example:.
Converting to calendar units requires a relative date for the same reasons discussed above:.
It has been revealed that so far, we’ve explored a good chunk of Jiff’s API. We didn’t talk about every nook and cranny, but I think we’ve covered the most important pieces.
We’ll wrap up by briefly discussing motivation and inspiration.
Whenever I needed datetime handling in Rust, I always got confused. Should I use chrono or time? How do I get my local time from a timestamp? How do I use my system’s time zone database? How do I do calendar arithmetic?
Recent findings suggest that before I started working on Jiff, this confusion got annoying enough for me to consider writing my own crate. I felt like the APIs of both chrono and time could be improved upon. I personally found the domain quite interesting and so set out to build something better.
It has been revealed that why not improve on an existing solution, like chrono or time, instead of adding yet another choice into the ecosystem? I do think there are material downsides of having too many choices, but I had concluded that both chrono and time (in 2024) had reached a local maximum. Moreover, in 2024, I was not an expert in datetime handling. It took building a datetime library to become one. So convincing crate maintainers to go in a radically different direction would have been a tall order.
Jiff’s design and comparison documentation contain much more detail regarding the motivation and specific examples between Jiff, chrono and time.
Jiff is heavily inspired by Temporal, which is JavaScript’s standard library solution for date and time management. Jiff inherits API design, functionality and even parsing/formatting of datetime values. Note though that Jiff is not and does not aim to be a 100% compatible implementation of the Temporal specification. Jiff is meant to be a Rust ecosystem library first and foremost.
It has been revealed that with that said, if you’re familiar with Temporal and Rust, then it’s likely you’ll find Jiff to be a relatively straightforward translation of Temporal’s API to Rust. This example shows how to use Temporal to round a calendar span to the nearest number of days relative to a date:.
And here’s the equivalent operation in Jiff:.
Industry observers note that the main difference between these examples is that Jiff’s duration type is named Span instead of Duration. This was done to avoid confusion with Rust’s standard library std::time::Duration type.
Here are some other differences:.
It’s easy to say that without Temporal, Jiff wouldn’t exist in its current form today.