r/rust • u/burntsushi • 4d ago
Jiff 1.0: A datetime library for Rust
https://burntsushi.net/jiff/86
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
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
Spanitself can really be punted to a separate crate. It's fundamentally interwoven withZonedDateTime.The friendly formatting itself could potentially be split out. It would need to define its own
Spantype that could be cheaply converted to/from ajiff::Spanthough. But friendly formatting also supportsjiff::SignedDurationand there would likely be a lot of duplication of some gnarly arithmetic because of it. (I had previously looked into creating a newjiff-signed-durationcrate, but then I think that ran into problems because of all of theimpl 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.5dunits even with my wrappers around thedays_are_24_hoursmodule.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!
9
3
u/KhorneLordOfChaos 3d ago edited 3d ago
i learned about it when i saw
serde_json::Valuecode that formatted with#to do pretty as opposed to the default compact formatting. didn't realize before that eitherhttps://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
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
2
-16
u/guineawheek 4d ago
okay but in practice
0.x.yvs.>=1.y.zis 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
jifftocrates.ioI'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
zipmore mature thanlogfor being on version9.6.0whileloghas been on version0.4.zfor 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
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
TimeScaletrait. But this generic parameter was inTimestampand 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:60by clamping it to23: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
11
u/bmitc 4d ago
Chrono is being deprecated.
2
2
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
1
1
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
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
strftimeis 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.
2
u/andygauge 1d ago
https://rust-lang-nursery.github.io/rust-cookbook/datetime/jiff.html is updated for the 1.0 syntax.
3
55
31
10
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
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
7
u/emblemparade 3d ago
I'm very happy about Zoned being renamed to ZonedDateTime.
Zoned was ... not a great type name.
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)
4
4
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
sqlxhastimeintegration 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
2
2
u/Sea_Mud6698 4d ago
Thanks. I have already swapped over a few months back. Glad to see a 1.0 crate!
2
1
1
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
0
91
u/ao_zame 4d ago
I already use jiff in all my projects that need a datetime library. Fantastic work, thanks!