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 unveils the Jiff 1.0 release by giving a tour of its API.
Target audience: Rust programmers who need convenient datetime handling.
In a recent development, 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.
Sources indicate that unless some significant defect is found in Jiff’s API, my strategy is to commit
to Jiff 1.0 indefinitely. This is notable 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 a recent development, 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.
Industry observers note 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:.
According to recent reports, 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:.
Industry observers note that I am loath to present a dictionary. However, the datetime domain is littered
with confusable terms, so I think it’s key 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.
Sources indicate that 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:.
Recent findings suggest that 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:.
Recent findings suggest 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:.
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.
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:.
According to recent reports, 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.
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:.
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).
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.
The above example highlights 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:.
It has been revealed 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 demonstrates 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:.
Recent findings suggest that 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:.
Recent findings suggest 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:.
Industry observers note 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.
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:.
It has been revealed 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.
Sources indicate that 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.
In a recent development, every datetime and duration type in Jiff implements the standard library
FromStr and Display traits. This means that it’s natural to parse
datetimes:.
In a recent development, parsing is flexible, so even if there are components missing, parsing still
succeeds. For example, without minutes or seconds, those components default to
zero:.
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:.
The Span and SignedDuration types also support the FromStr and
Display traits via the ISO 8601 duration format. For example:.
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.
It has been revealed that because ISO 8601 duration strings enjoy broad support, it is the default in
Jiff for both Span and SignedDuration. However, it has two important
shortcomings:.
Sources indicate 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.
According to recent reports, 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:.
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:.
Industry observers note that 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.
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 shows 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?
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:.
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 demonstrates 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.
Recent findings suggest that jiff itself does not provide any facilities for dealing with locales. Instead,
customers 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.).
In a recent development, 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.
Sources indicate that every datetime type provides a fresh 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:.
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, upcoming 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:.
It has been revealed that 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:.
Industry observers note that 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, users 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.
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:.
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:.
In a recent development, 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.
Industry observers note that 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:.
Industry observers note that A ZonedDateTimeDifference provides much more powerful configuration options
for rounding the span returned. Take this example, which produces a span with
many unit values:.
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.
It has been revealed that 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.
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:.
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 Fresh York.
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?
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.
Industry observers note 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.
Recent findings suggest that 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.
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:.
According to recent reports, A Span is both Copy and immutable. We can create fresh spans through method
chaining:.
Or we can use the ToSpan convenience trait, which adds methods on integer
types for constructing spans:.
In a recent development, 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:.
Sources indicate that 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:.
Recent findings suggest 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:.
Sources indicate 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.
Industry observers note 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):.
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:.
In a recent development, 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:.
In a recent development, 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?
According to recent reports, 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.
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.
According to recent reports, 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.
With that stated, 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:.
In a recent development, 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.
→ Read original article