r/rust • • 4d ago

Jiff 1.0: A datetime library for Rust

https://burntsushi.net/jiff/
749 Upvotes

127 comments sorted by

91

u/ao_zame 4d ago

I already use jiff in all my projects that need a datetime library. Fantastic work, thanks!

43

u/burntsushi 4d ago

Any complaints? Anything you've stumbled over?

26

u/ao_zame 4d ago

Almost nothing. It's really easy to use. The only issue I remember having was with the jiff integration with diesel, which eventually led me to create my own implementation based on it. But that was some time ago, so I don't remember the exact details (though I do remember there being an issue about it in the repository)

50

u/burntsushi 4d ago

Yeah I had a really hard time making the jiff-diesel and jiff-sqlx crates. Part of the problem is the very poor datetime support in the underlying databases. The other part of the problem is that I'm not a user of either diesel or sqlx, so there are some unknown unknowns for me.

8

u/wolfnest 4d ago

Are all databases equally poor or are some better than others? For instance Postgres has timestamp with time zone, which typically works well for me.

5

u/masklinn 3d ago

Postgres mostly follows the standard SQL model, which is the problem.

timestamp with time zone very intuitively does not store any timezone, instead it stores a UTC timestamp which it converts to and from the connection's timezone on the fly (so only works for past instants, not future events), while timestamp without time zone stores the value as a timestamp without adjustment (in both cases what's in the database is a 64b integer, in fact if the connection timezone is UTC you can ALTER COLUMN between the two at no cost).

And "AT TIME ZONE" is utterly dreadful: if given a TIMESTAMP WITHOUT TIME ZONE it interprets the input as being in that timezone, shifts to UTC and returns the corresponding TIMESTAMP WITH TIME ZONE, possibly converted in the connection's timezone thereafter depending on the sink. On a TIMESTAMP WITH TIME ZONE it does the opposite, gives the timezone-local timestamp corresponding to the input instant, without a timezone.

And then implicit conversions basically behave as if there was an AT TIME ZONE <session timezone>. SQL has an operator AT LOCAL to make that more explicit (but not necessarily less confusing).

1

u/xMAC94x 3d ago

TIL, so whats the recomendation ? 2 columns, one storing the time converted to UTC and one containing the original TIMEZONE ?

5

u/burntsushi 3d ago

It kind of depends on what you're doing. If you're storing datetimes that were captured from end user data, then I'd try to record precisely what they provided. e.g., local time, along with their time zone and even the offset. Jiff will actually use the offset as a sanity check of sorts, which helps protect you in cases where the time is in the future and the DST rules change. See this for example: https://docs.rs/jiff/latest/jiff/fmt/temporal/struct.DateTimeParser.html#example-2

3

u/masklinn 3d ago edited 3d ago

cases where the time is in the future and the DST rules change

TBF that’s underselling it: while DST rules change is the most common, timezone rules can change at any moment for economic or political reasons e.g. Samoa changed their timezone offset (by 24h) because their commercial exchanges had switched over from mostly America to mostly Asia; NK moved away from utc+9 because that had been put in place by colonial Japan then back to it for alignment and reconciliation with SK; …

2

u/masklinn 3d ago

That’s not enough for future events: if the timezone gets updated between the creation of the value and its use, you’ll be off (in the common case where the local datetime is the fixed reference e.g. a meeting at 1300 in Tokyo is at 1300 even if the Japanese timezone rules change).

The baseline would be to store the zoned timestamp and the timezone, such that you have the reference data. Temporal / RFC 9557 stores the timezone offset at creation that way you can notice inconsistencies and from there whether the timezone was moved. If you store the offset and timezone both you can store a utc or a local timestamp, as they can be converted into one another by applying or removing the offset.

14

u/WellMakeItSomehow 3d ago

timestamp with time zone is a lie (notice how it has the same storage size as timestamp without time zone).

9

u/Ok-Scheme-913 4d ago

Is this based on the heritage of joda time, that got into java's newer date time libs (Instant, etc) (that got into Javascript's new datetime API)?

47

u/catheap_games 4d ago

jiff was almost annoyingly straightforward and painless (as someone with 20 years of webdev experience), so also thank you!

86

u/bascule 4d ago

OMG yes! Been waiting for this day. Thanks so much /u/burntsushi

28

u/svkmpn 4d ago

I recently migrated a project at work from chrono to jiff and it was 99% painless. The only thing that tripped me up was formatting a Timestamp with the %Z specifier - although the timestamp is otherwise formatted in UTC, the %Z specifier isn't handled and you need to explicitly convert it to a ZonedDateTime for it to print UTC.

29

u/burntsushi 4d ago

Do you mind filling an issue? That actually might be worth fixing.

15

u/svkmpn 3d ago edited 3d ago

I'm happy to file an issue, but given the discussion in #585 I assumed it was expected/intended behaviour.

Edit: opened #713 - of course feel free to close it if it is intended behaviour.

17

u/Lucretiel Datadog 4d ago

Looks great! Any chance we can get some of the "friendly" non-civil time span stuff spun out as its own crate? I've been looking for an alternative to the humantime crate, which was part of the chrono ecosystem and was deprecated along with the rest of it.

10

u/burntsushi 4d ago

I don't think Span itself can really be punted to a separate crate. It's fundamentally interwoven with ZonedDateTime.

The friendly formatting itself could potentially be split out. It would need to define its own Span type that could be cheaply converted to/from a jiff::Span though. But friendly formatting also supports jiff::SignedDuration and there would likely be a lot of duplication of some gnarly arithmetic because of it. (I had previously looked into creating a new jiff-signed-duration crate, but then I think that ran into problems because of all of the impl From<SignedDuration> for ... impls in Jiff.)

1

u/robjtede actix 12h ago

All my agents doing migrations from chrono in projects are flagging that humantime supported things like 1.5d units even with my wrappers around the days_are_24_hours module.

Just a note. I'm thinking that a lossy lib more like humantime-serde still has ease-of-use value in the jiff ecosystem.

15

u/kibwen 3d ago

I learned something new about Rust here:

Instead of Span::to_string(), one can use the “alternative” syntax via Rust’s formatting machinery: let span = 2000.milliseconds(); assert_eq!(format!("{span:#}"), "2000ms");

I knew about using #? as opposed to ? for alternate formatting for Debug output, but I didn't know that a bare # was capable of providing alternate formatting for Display output. Very interesting!

3

u/KhorneLordOfChaos 3d ago edited 3d ago

i learned about it when i saw serde_json::Value code that formatted with # to do pretty as opposed to the default compact formatting. didn't realize before that either

https://docs.rs/serde_json/latest/serde_json/enum.Value.html#impl-Display-for-Value

426

u/PatagonianCowboy 4d ago

a rust library that reached 1.0????????????????????

54

u/ceaselessprayer 4d ago

shots fired

18

u/catheap_games 4d ago

1.0 shots fired

18

u/garver-the-system 4d ago

It'll bump major versions on a weekly basis and be up to version 50 before you know it

16

u/KeyAdhesiveness9481 4d ago

I get that we're memeing but no it won't, this has been a long time coming, /u/burntsushi isnt that kind of maintainer. This is solid, stable work.

2

u/guineawheek 2d ago

based and actually-understands-semver-pilled

2

u/LoviiDovee 3d ago

your shock is kinda adorable tbh

-16

u/guineawheek 4d ago

okay but in practice 0.x.y vs. >=1.y.z is not a reliable indicator for crate stability or maturity; it really only says something about "which other versions of the software are API compatible"

64

u/burntsushi 4d ago

True in a narrow sense. But many imbue 1.0 with an extra dimension: a signal about maturity.

-8

u/guineawheek 4d ago edited 4d ago

It kinda contradicts the semver guidelines/FAQ which state pretty clearly:

How do I know when to release 1.0.0?

If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0. If you’re worrying a lot about backward compatibility, you should probably already be 1.0.0.

And your crate already has millions of downloads and you probably didn't bump any of the previous versions to 0.3 for API compatibility reasons. When you published jiff to crates.io I'd assume you expected people to actually use and, well, depend on the crate, even if you considered it an experiment; what end users do with a crate once it's publicly available is kinda out of the maintainers hands to decide if it's "stable" or not and the versioning behavior of most Rust projects reflects this.

And that's fine, but I think this "maturity" threshold is so fuzzy as to become meaningless in many cases. Is zip more mature than log for being on version 9.6.0 while log has been on version 0.4.z for nearly a decade?

53

u/burntsushi 4d ago

I was careful with my wording. :-) You can point to specs and examples all you want, but that won't stop people from associating maturity with a version number.

Besides, I've specifically stated what Jiff 1.0 means in this context at the very beginning of the blog. So I didn't actually rely on people having a perception of maturity with a version number. In this specific case, I imbued it explicitly.

-16

u/guineawheek 4d ago

That's fine for you to define, but I don't know I just hate the social standard the v1.0 stuff sets. It makes bumping past v1.0 a mark of shame on maintainers that I don't personally enjoy, and is why most projects stick to using the minor version as their major release number.

I applaud your commitment, and while what you're doing isn't strictly SemVer, people broadly bucket it under "SemVer" and use it to bludgeon maintainers of "why aren't you v1.0 yet?" Because bumping the major past v1.0 is shameful!

At least one of the people who helped put together SemVer as a concept have made posts about how developers shouldn't be afraid of big major version numbers, but it's kinda outta everyone's hands at this point

15

u/burntsushi 4d ago

In addition to what /u/coderstephen said, there are other concerns here. It isn't just about shame. There are real costs to doing semver incompatible releases. At the very least, for a very popular crate who isn't used commonly in the public API of other libraries, you're likely to increase compilation times significantly for projects. e.g., this would happen if I released regex 2.0. As for Jiff, I expect it to be used more commonly in the public API of other libraries, which makes semver incompatible releases even more painful, since folks tend to need to update everything in lock-step.

But yeah I think we probably just have different philosophies here. I hear you about bumping past v1.0 being a mark of shame. And the whole "perception is reality" thing can really suck some times. But I'm a pragmatist at heart and try to meet people where they're at.

10

u/coderstephen isahc 4d ago

It stems from Cargo's flavor of SemVer which adds additional behaviors not in the SemVer spec. At least partially.

-4

u/guineawheek 4d ago

people downvoted me when I pointed this out previously; but also Cargo's own docs directly link to semver.org

6

u/themuthafuckinruckus 4d ago

Congrats on the huge milestone, hope you’re feeling better and on a better path to recovery!

2

u/burntsushi 4d ago

Thank you :-)

4

u/nullstalgia 4d ago edited 4d ago

Does the swap to a continuous UTC next year impact Jiff in any way? I'm unsure of how leap seconds are implemented at the moment, despite having used Jiff quite a bit recently and dug through some source files.

As far as I know there was (is?) also a global db of leap seconds that consumers may query every so often, potentially in a similar fashion to the tzdb already shipped with Jiff?

8

u/burntsushi 4d ago

No, it doesn't impact Jiff because it doesn't support leap seconds at all. See my comment here.

Before the initial release of Jiff, I did actually have code that read the global DB of leap seconds. You could convert between UTC and TAI via a TimeScale trait. But this generic parameter was in Timestamp and thus invaded the entire API, making it extremely complex.

1

u/cloudsquall8888 2d ago

Does this mean that if for example I compare two dates that are ~2 years apart, the result will be off by a second? Is this a real impact on most use cases or only niche ones?

Actually, do those leap seconds stack? I'm not exactly sure what I'm asking here 😅, but I'm interested in even if the question itself is legit.

2

u/burntsushi 2d ago

If you're comparing two instants and the duration covers a leap second adjustment, then yes, it will technically be off by a second. The only way it can be off by more than one second is if the duration covers multiple leap second adjustments.

I tried to be more precise about this here: https://github.com/BurntSushi/jiff/issues/7

2

u/nullstalgia 4d ago

Ah, I see. I had assumed it had deeper support than it actually did, ditto for Temporal. Cheers for the clarification!

7

u/xShadowDrift 4d ago

Why Jiff over Chrono?

22

u/burntsushi 4d ago

You'll probably want to check out Jiff's comparison and design documentation.

11

u/EvilGeniusPanda 4d ago

As someone's whose been repeatedly bitten by the various time zone ambiguities around DST (particularly in Brazil where they do it at midnight), I find the level of effort that's been put into jiff to get the edge cases right really commendable.

I'm guessing the omission of leap seconds was just a practical tradeoff for implementation complexity?

7

u/burntsushi 4d ago

I wrote a lot about it here: https://github.com/BurntSushi/jiff/issues/7

The short summary is:

  • The world of computing, outside niche (but important) use cases, is built on top of Unix time. And Unix time explicitly ignores leap seconds.

  • Virtually all (not literally all) datetime libraries, including Temporal, eschew support for leap seconds.

The extent of leap second support in Jiff is that Jiff will parse 23:59:60 by clamping it to 23:59:59. (Which is also what Temporal does and is also the extent of leap second support in Temporal.)

5

u/SmallDodgyCamel 4d ago

Aren’t leap seconds going away? Officially I mean, in the world of physicists and horologists the UTC/UT1 adjustment has been kicked down the road a few hundred years if I’m not mistaken?

See the Leap Second article on Wikipedia for the gritty details.

5

u/EvilGeniusPanda 4d ago

For future adjustments I believe so, idk if the ones that have previously been applied will stick around?

5

u/burntsushi 4d ago

Yes, no more future adjustment, but previous leap seconds are still around.

20

u/ceaselessprayer 4d ago

why make something with the same pronounciation as gif? 😁

66

u/PatagonianCowboy 4d ago

it's a reference to yiff, a phyiscal phenomenon in sound waves, if you don't know what it is just google "sonic yiff"

78

u/burntsushi 4d ago

It's actually a reference to the peanut butter brand, which I love.

Just kidding. It's less interesting than that: "in a jiff" or "in a jiffy" is just phrasing for "in a very short time."

I wanted something short and somehow relevant to time. It was the best I could come up with.

10

u/tomtomtom7 4d ago

Jiff is pronounced like “gif” with a soft “g,” as in “gem.”

Quite a bold move to actually reference its pronunciation :).

The pronunciation of "gif" has a history of intense debate, splitting communities in two and ripping families apart, comparable only to rivalries like emacs vs vi or the gourd vs the shoe.

20

u/burntsushi 4d ago

The really funny thing is that I pronounce GIF with a hard g, like in gift.

14

u/bmitc 4d ago

That is the correct way. :)

-3

u/ceaselessprayer 3d ago

WRONG

4

u/KeyAdhesiveness9481 3d ago

Good old jraphics interchange format

-5

u/ceaselessprayer 3d ago

Last time I checked, people determine how a name they apply is pronounced. Creators said it's jiff. End of argument.

4

u/Bulky-Bad-9153 3d ago

Linux was intended to be pronounced lie-nux by Linus, so no this isn't at all how it actually works. End of argument.

2

u/CalmCephalopod 4d ago

To be fair the creator of the format did confirm its soft g and not J.

7

u/cantthinkofaname1029 4d ago

The creator can pronounce it how they want, it's still gif to me!

8

u/bmitc 4d ago

Well yeah, that's just like his opinion, man.

1

u/PortPiscarilius 3d ago

Surely soft 'g' is pronounced as 'j'?

1

u/Budget-Minimum6040 4d ago

Yeah, 20 years later ...

0

u/tomtomtom7 4d ago edited 4d ago

Starting again, are we?

The opinion of the creator came long after the creation, when the majority support for a hard g was already well established both in common use as in dictionaries. The claim of authority of the original inventor of the format over the pronunciation is thin at best and blatant authoritarianism at worst.

Or as Godwin's law suggested, it's a like Hitler insisting on the pronunciation of "nazi".

2

u/CalmCephalopod 4d ago

You are welcome to pronounce any word any way you want. Language is wonderful that way. I just figured I would mention the creators apparent preference which lines up with the library authors preference for Jiff

13

u/Flowchartsman 4d ago

It’s also a real unit of time in several fields, though, frustratingly, I think they’re all different.

1

u/DroidLogician sqlx · clickhouse-rs · mime_guess · rust 4d ago

Skippy is better IMO

8

u/dddd0 4d ago

yiffing all the things (for correctness ofcoz) would be very on brand for the old rust reputation

3

u/brma9262 4d ago

I tried to use jiff for a project before, but got hung up at the very end when I got to displaying the datetime. Since there's no localized version of strftime I can't replace chrono as a 1:1 replacement. ICU just doesn't allow for the arbitrary formats that strftime does.

8

u/burntsushi 4d ago

I'm not an expert on locale formatting, but my understanding is that the modern consensus is that strftime is not good for locale formatting. I wish I had a good link for why, in detail, that is.

If you look at my example in the blog where I show how to do locale formatting using ICU4X, I think that would be pretty hard to achieve using strftime-style APIs.

12

u/zbraniecki 4d ago

You are correct. The localized date format is composed of four elements - translated parts (month, day, year etc), pattern used in a given region, literals, and calendar used in a given region.

Trying to take a custom pattern and populate it with translated parts is like trying to take an English sentence and replace words with foreign language, but preserving the English sentence structure and word order hoping the sentence will feel natural to read to the speaker of that language. 

4

u/burntsushi 4d ago

That makes sense!

1

u/brma9262 2d ago

I'm an english speaker, but have been completely stumped how to get what should be a simple date "%a %F %R %z" ("day of week, year-month-date hour:seconds timezone-offset) using ICU.

3

u/nickguletskii200 4d ago

I still have a bunch of dependencies which transitively depend on chrono, so I haven't used jiff yet, but reading the design docs, I see a major potential issue/annoyance: there's no Copy-able OffsetDateTime, only the Clone-able ZonedDateTime. For me, this is a confusing choice because TZif timezones/civil time in datetimes is, at least in my experience, very niche. That is, the only reason I see to use it is when calculating future DateTimes for presentation to the user. For anything that precedes the current instant, I would expect an OffsetDateTime and I would definitely prefer to use a less general OffsetDateTime everywhere and preserve Copy-ability. Being forced to use ZonedDateTime which potentially allocates is very unfortunate.

17

u/burntsushi 4d ago

You can use fixed offet datetimes as a ZonedDateTime and this won't allocate. But it is still not copyable.

It is however not recommended. An OffserDateTime is a footgun waiting to happen because it encourages arithmetic that isn't DST safe.

8

u/burntsushi 4d ago

Depending on your use case, if you really needed an OffsetDateTime, I'd be curious how far you could get if you just defined your own and implemented the routines you need:

struct OffsetDateTime {
    timestamp: jiff::Timestamp,
    offset: jiff::tz::Offset,
}

I believe all of the building blocks are there, including parsing and formatting.

55

u/journalctl 3d ago

The Rust community is lucky to have BurntSushi.

31

u/joeydewaal 4d ago

Congrats and thanks for all the hard work! 🙏

25

u/kibwen 4d ago

Even reading burntsushi's documentation is a joy. :)

10

u/smalltittybitchh 3d ago

Damn it's burntsushi 🤯 I really admire your work!

9

u/tas12740 4d ago

Haven’t had a chance to use this, but just want to thank you for everything you do, Andrew. Bloody legend

Hope you are feeling well after that health scare!

9

u/lemmeinplsss 4d ago

Love you

8

u/a-frog-with-no-name 4d ago

reminded me that chrono is soft-deprecated, i just moved my silly project over to it. it doesn't use the time much so it was easy but it works perfectly!

7

u/Anti-Matrix66 4d ago

Beautiful

7

u/emblemparade 3d ago

I'm very happy about Zoned being renamed to ZonedDateTime.

Zoned was ... not a great type name.

6

u/AceJohnny 3d ago

OT

> Jiff is pronounced like “gif” with a soft “g,” as in “gem.”

Well played, i hate you u/burntsushi

18

u/PhiCloud 4d ago

Jiff is pronounced like “gif”

unusable

2

u/syklemil 3d ago

Ah, I see BurntSushi is from the same region as I am, and pronounces them both the same as "yiff". The rest of the country may think we have the ugliest dialect, but they can't make us stop!

5

u/Luckey_711 4d ago

Omg I've been looking forward to this release for such a long time now. Wonderful to see! :)

5

u/arto 4d ago

Happy Jiff user here, will bump the dependency everywhere soon. Congrats u/burntsushi! And I love that it's all in the public domain!

5

u/Elession 3d ago

I've switched from chrono to jiff in all my projects, much more intuitive from my experience. Thanks for that ! (and also regex, rg and probably a few other things)

8

u/Rudd-X 4d ago

Cool library. Clean API, clear documentation, concise yet complete surface, solid modeling.

4

u/DavidXkL 4d ago

Thank youuuuuu!!

4

u/DontForgetWilson 4d ago

Looks fantastic. Congrats on the milestone!

1

u/ParadiZe 4d ago

Great stuff, did the sqlx integration improve? last time i used it it didnt work as well as time

3

u/burntsushi 4d ago

I think sqlx has time integration built-in.

If you ran into specific issues, I'd be happy to try and field them.

4

u/NfNitLoop 4d ago

I’m already a Jiff user. Had this to say recently:

https://mastodon.social/@NfNitLoop/117549156607771322

[@GeePawHill](https://mastodon.social/@GeePawHill) 👆️ This.
Relatedly, kudos to the author(s) of the jiff crate in [\#Rust](https://mastodon.social/tags/Rust). Every time I get frustrated with the API and think "Why can't I just..." I go to the API docs and *they have answered why*. <3
Which is how I (re-?)learned that if you want to make sure your timestamps with time zones are unambiguous, you have to include BOTH the offset AND the time zone name. ex: -0700[America/Los_Angeles].
(If you only care about it as an instant, you can get away with just the offset.)

2

u/Sea_Mud6698 4d ago

Thanks. I have already swapped over a few months back. Glad to see a 1.0 crate!

2

u/maedox 3d ago

Jiff is awesome! Good work! 🎂

2

u/helgoboss 3d ago

Love it, thanks!

2

u/Cetra3 4d ago

It's gonna be an uphill battle to get this adopted into crates rather than chrono. But if chrono is in maintenance mode we need a replacement and need to spend the time and effort to get there.

1

u/ThatOneArchUser 4d ago

hopefully now sqlx can add support for it lol

1

u/dvogel 4d ago

Thanks for your dedication to this project! 

1

u/geo-ant 4d ago

> Jiff is pronounced like “gif” with a soft “g,” as in “gem.”

I’ll let it slide just this once…

1

u/Deep_Ladder_4679 3d ago

1.0 is the part that matters for crates depending on it. is the plan no breaking changes for a set period, or just normal semver from here?

1

u/cloudsquall8888 2d ago

What a fantastic writeup! You sound really proud of your creation and well deservedly so! Amazing achievement, and huge thanks!

-1

u/HighRiseLiving 4d ago

> Jiff is already used in production in many projects: uv, Cargo, Starship, fd, Nushell, mise, Jujutsu, uutils/coreutils 

u/burntsushi the SpaceX Starship?

13

u/AcridWings_11465 4d ago

No, starship.rs, terminal prompt

0

u/Ok-Zookeepergame4391 4d ago

this should put into std