Why don't Jiff's strftime and strptime routines validate the format string separately from formatting or parsing a datetime?

[indianakernick]

I've been considering moving from chrono to jiff. So far, I've been liking what I'm reading, especially when it comes to time zones. However, one thing stood out to me. That's the strftime and strptime functions. These functions take the format string and the data to be formatted/parsed and do the parsing of the format string together with the processing of the input data. Combining these two operations into one seems wrong to me.

The format string is typically going to be static. An invalid format string is typically going to be a bug in the program rather than invalid input data that needs to be handled. An invalid format string and invalid input data are two distinct failure modes that shouldn't be conflated. I'd like to parse the format string on program startup and crash immediately if it's invalid. When formatting or parsing a date using that format, I'd like the only errors to be due to the input data, not the format string.

What if problems in the format string somehow only revealed themselves when combined with particular input data? That's probably not possible but the API allows it to be.

chrono and time both make this separation in their APIs. I'm looking for something in the shape of this:

// Once, on startup.
let format_spec = parse_format_string("...").unwrap();

// Later, for many inputs.
let output_string = format_spec.format(input_date)?;
let output_date = format_spec.parse(input_string)?;

// Can still do this if you want.
let output_string = format(format_string, input_date)?;
let output_date = parse(format_string, input_string)?;

Of course, performance is a side benefit to this separation but it's not my primary motivation. Although, the benchmark results in the comparison document show jiff's print/strftime/oneshot/buffer being faster than chrono's print/strftime/prebuilt/buffer which I found surprising.

I'm interested to know your opinion on this. Is it something that you've already considered and decided against?

[BurntSushi]

Combining these two operations into one seems wrong to me.

Indeed, I have the same feeling. Your philosophical approach to this is
indeed my default position in how I think about APIs like this! But there are
extremely compelling reasons for doing things differently in this case.

While perhaps surprising, performance is one of the main motivators!
Even if I didn't want to expose a separate validation step in the API,
I could still do so internally if it helped things. But this pushes
you hard to doing two passes. One pass is parsing the format string
into a structured representation. The second pass is over the resulting
structured representation to either do the actual parsing (strptime) or
formatting (strftime). Doing a separate validation step is quite a bit
slower. It looks like the time crate has come to the same conclusion
recently.
Note that I don't think that change is in a release yet. In any
case, here are some micro-benchmarks comparing jiff, time and chrono (the
latest release of each at time of writing):

$ cd bench
$ cargo bench -- 'strftime|strptime' --save-baseline strtime
$ critcmp strtime -g '(.*/)[^/]+$'
group                                         strtime/chrono                         strtime/jiff                           strtime/time                           strtime/time-format
-----                                         --------------                         ------------                           ------------                           -------------------
parse/strptime/oneshot/                       2.87    194.5±0.65ns        ? ?/sec    1.00     67.9±1.22ns        ? ?/sec
parse/strptime/prebuilt/                      1.16     81.0±1.15ns        ? ?/sec                                           1.00     69.9±1.13ns        ? ?/sec
print/strftime/oneshot/buffer/                3.62    220.6±1.26ns        ? ?/sec    1.00     60.9±0.75ns        ? ?/sec    6.31    384.5±2.85ns        ? ?/sec
print/strftime/oneshot/to_string/             3.01    272.7±0.94ns        ? ?/sec    1.00     90.7±0.59ns        ? ?/sec    4.97    450.8±1.71ns        ? ?/sec    2.61    236.5±1.26ns        ? ?/sec
print/strftime/oneshot/zoned/                                                        1.00     72.5±0.57ns        ? ?/sec
print/strftime/prebuilt/buffer/               1.00     88.6±0.55ns        ? ?/sec                                           1.11     98.0±1.46ns        ? ?/sec
print/strftime/prebuilt/buffer/bespoke/                                                                                     1.00    110.1±1.57ns        ? ?/sec
print/strftime/prebuilt/to_string/            1.00    157.2±0.78ns        ? ?/sec                                           1.14    179.7±1.65ns        ? ?/sec
print/strftime/prebuilt/to_string/bespoke/                                                                                  1.00    183.7±0.54ns        ? ?/sec

The big thing to notice here is that Jiff doesn't have a distinction between
"oneshot" and "prebuilt." Both chrono and time do. That is, all of Jiff's
APIs and implementations here are "oneshot." Meaning that the format string is
parsed in a single coupled step with the input (whether parsing a datetime or
formatting one).

It works for this because the formatting string grammar is incredibly simple.
Things get a little dicey when parsing some directive options, but this is
basically the parser:

https://github.com/BurntSushi/jiff/blob/48a9292e8aca036105607768324d97942d22b84e/src/fmt/strtime/printer.rs

With respect to parsing failures, it's very rare to have them. The main
footgun here are the various [datetime type]::strftime routines because they
present as infallible but in fact are fallible. For example, println!("{}", Zoned::now().strftime("%")) is guaranteed to panic. There isn't too much to do
here because it's a consequence of how std's APIs are designed. With that said,
as you point out, for APIs like Zoned::strftime, it's quite common for the
formatting string to be a static literal. And so that a panic is somewhat defensible,
but still a panic. Basically, std's formatting machinery has built-in assumptions
that producing a string from a value that implements Display and Debug is always
infallible. So if you hook into that, you have to play that game. Which is fair.

Anyway... I'm rambling. For things like Zoned::strptime("%"), the utility of
knowing if the format string is valid ahead of time is questionable. This is a
parsing routine, so you always expect for it to be fallible in some way.

This is explain in more detail on the jiff::fmt::strtime::Display type. It
also shows how you can use lower level (but far less convenient) APIs for using
truly fallible routines that never panic.

(The above 3 paragraphs feel a bit rambly and tangential, but also relevant. So
I've left them in.)

What if problems in the format string somehow only revealed themselves when
combined with particular input data? That's probably not possible but the API
allows it to be.

For parsing, this is expected. For formatting, it's very much intentional
that this isn't possible. The API is not just types and methods. It's also
documentation. And, for example, jiff::fmt::strtime::Display specifically
says:

Therefore, only use this type if you know your formatting string is valid and
that the datetime type being formatted has all of the information required
by the format string. Moreover, the strftime implementation in this crate is
specifically designed to never error based on the specific values.

So by this, I would argue that the API very specifically and intentionally
does not allow it. You can still use, e.g., %z on a jiff::civil::DateTime
and get an error. But if nothing else mattered, this could be made a compile
time error because it's an invariant property of the data provided by a civil
datetime. (It will never have a time zone offset.) In other words, for actual
datetime values (year, month, hour, second, etc), either all values work or
none of them do. That's an important property of these APIs.

The format string is typically going to be static. An invalid format string
is typically going to be a bug in the program rather than invalid input data
that needs to be handled.

OK, now we're going to really get into the meat and potatoes of why the API is
the way it is.

What might surprise you is that I hate hate hate the strftime and strptime
APIs. Largely for the reasons you state. It's a relic of an ancient Unix
tradition to guess the user's intent even when the input is nonsense. That's
what strftime is. If you go look at the POSIX strftime routine, you can
see that it has the same coupling as Jiff: you pass both the format string
and the datetime to the same routine. The POSIX API essentially forces the
implementation (aside from thread local caching tricks or other shenanigans) to
do everything in a single pass. This has a whole bunch of knock on effects in
terms of how things are designed.

Now, who gives a fuck about POSIX? Goodness, I certainly wish it would die.
But it's here. We need to live with it. And there are many many different
implementations of strftime (and strptime) with their own little quirks and
peccadilloes. All of them still use %Y to represent a 4 digit year though.
So there's a core overlap. In many cases, the differences are just that the
implementation doesn't support everything that, e.g., GNU's implementation
does. (Which extends POSIX in almost every direction everywhere.)

So, Jiff's implementation and API are modeled on POSIX, for better or worse.
The documentation calls this out:

While the routines exposed in this module very closely resemble the
corresponding strptime and strftime POSIX functions, it is not a goal for the
formatting machinery to precisely match POSIX semantics.

The main reason why I didn't go all the way and promise POSIX semantics is mostly
just a function of the fact that I want to remain sane. I simply do not want to
spend my time trying to deal with the tail compatibility problems of POSIX.

There is some data that this strategy has paid off. The uutils project is now
using Jiff for its datetime handling in lieu of Chrono. There
were a number of issues with the strtime APIs that Jiff helped resolve
specifically because I modeled its behavior based on the POSIX routines.

And that's kind of what it comes down. The cursed strtime APIs exist because
they are ubiquitous. I don't know anybody that really likes them, but everybody
knows them.

This is also why...

The format string is typically going to be static.

... is perhaps less true than you might think. The strtime format string
grammar is so ubiquitous that it is quite common for it to find its way into
end user facing behavior. It often becomes part of the CLI API even when Jiff
is itself an implementation detail. This was yet another crucial point I
carefully considered to migration from Chrono easier.

---

Now that I'm here, I feel like I've done a poor job of answering this question.
It's hard. My answer is all over the place. But the short summary is:

1. Performance. One pass is much faster. Otherwise you need to build up some
   intermediate representation of the formatting string. And then do a pass over
   that to do the actual parsing or formatting. You could make your validation
   step do produce nothing I guess. But that seems silly. And you still need two
   passes.
2. Modeling how the existing strtime APIs work.
3. Use in not only no_std but no_alloc.

The last one is pretty cool and not something I touched on before. With
this Cargo.toml:

[package]
publish = false
name = "jiff-play"
version = "0.1.0"
edition = "2024"

[dependencies]
anyhow = "1.0.102"
jiff = { version = "0.2.25", default-features = false }

[[bin]]
name = "jiff-play"
path = "main.rs"

[profile.release]
debug = true

And this main.rs:

fn main() {
    let Ok(dt) = jiff::civil::DateTime::strptime(
        "%Y-%m-%d %H:%M%P",
        "2026-05-25 5:30pm",
    ) else {
        eprintln!("parse failure");
        std::process::exit(1);
    };
    println!("{}", dt.strftime("%m/%d/%Y"));
}

We get:

$ cargo r -q
05/25/2026

If we built up an intermediate structure internally, where would we put that?
In this configuration, Jiff can't allocate. The only real way around this is to
add a proc macro for use in no-std no-alloc environments. Which is something I
despise. I hate that jiff::tz::get! exists for example. Hah.

Indeed, this is likely the entire motivation behind how and why the POSIX APIs
were designed in the first place. Allocation is a somewhat special and commonly
avoided thing in the implementations of low level system APIs. Indeed, Jiff
itself uses allocation very sparingly. The entire formatting infrastructure is
designed around a trait that doesn't require allocation, similar to std.

Finally, I'll note that there are parallels to regular expressions here.
Regexes are also often used in the interface to end users (from tools like
grep all the way to regexes for use with Discord by moderators). But:

1. Regexes are far more complicated and running them in a single pass is
   not feasible outside of toy implementations. (Or, for completeness, non-toy
   implementations specifically designed to have very low overhead for patterns
   not known at compile time but with other significant trade-offs that aren't
   germane in a particular context or are mitigated in some other way.)
2. There is way less expectation on regexes to have a single unified API.
   Even POSIX lets you compile regexes as a separate step.
3. Regexes are used way more overall and, hand waving, a more significant
   portion are literals in a program.

Apologies for the very long winded reply here, but you asked a question that
really cuts deep into the intersection of API design, legacy interfaces and
performance in rather subtle ways. You can see how Chrono made a mistake in
its design and how time is only now moving to a single-pass architecture. (I
might eat some crow saying that about time because I really haven't looked
closely yet.) I think that urge to "parse" in one step and then "execute" in
another is extremely strong and can be hard to resist. But it really truly
isn't appropriate in all contexts. This is one of them.

[indianakernick]

Thank you for taking the time to write such a detailed response! It was quite interesting. I should make it clear that I didn't allow this quibble to stop me from trying out jiff. I've been finding it quite pleasant to use.

You point out that one pass is faster. Maybe we're misunderstanding each other here. It seems quite likely that the same format string is going to be applied to multiple dates. When would you need to process millions of dates each with their own unique format string? You're saying that the single-pass architecture that jiff uses is faster in that case and I agree. However, that seems like such a rare use case. If you're processing millions of dates all with the same format string, then validating as a separate step to produce an efficient intermediate representation would surely be faster.

Neither chrono nor time prove this point though. From briefly glancing at their code, they seem to be prioritising readability and maintainability over performance for their intermediate representations. That makes sense because we're talking about nanoseconds here. I mean, it's already fast enough. After looking at their code, it doesn't seem so surprising anymore that jiff beats their prebuilt benchmarks.

To go as fast as possible, I'd imagine that the intermediate representation would be one contiguous block of memory (much like the format string itself). Each of the format specifiers could be encoded in a single-byte opcode. Additionally, there could be an opcode that means "the following byte is a literal" because single-byte literals between components are common. Finally, there could be an opcode that means "the following byte (or two) is a length and following that are the literal bytes". I'm quite confident that this would be faster because less work is being done on validating multi-byte sequences. Of course, a benchmark would be required to determine just how much of a difference this makes. I may end up writing that benchmark just for my own enjoyment!

My proposal to have a separate validation step doesn't prevent jiff from exposing the existing API alongside it. It would be a non-breaking change. At least, that's what I thought until you pointed out no_alloc. Avoiding memory allocations seems to me like the strongest reason for jiff staying as it is. If jiff couldn't allocate memory, then it could take a slice of uninitialised bytes to fill with the intermediate representation. People working with embedded systems are probably used to that sort of thing but it's inconvenient compared to the current API. You point out another option of using a macro which would be more convenient but that wouldn't be suitable for cases where the format string is dynamic.

Memory allocations might also significantly worsen the wrapper function that does validation and formatting in one step. To avoid allocating and deallocating the intermediate representation on every call, it could reuse a thread-local vector. That doesn't sound too bad but it's a bit of extra global state that wasn't there before. The alternative is to allocate and deallocate each time because if you're using that API, maybe the extra nanoseconds don't matter to you.

I still believe that the error semantics and performance (of the prebuilt scenario) could be improved. However, the sacrifices as I see them are:

1. Performance of the oneshot scenario would be worsened.
2. Usability in the no_alloc scenario would be worsened.

I would selfishly go forth despite these sacrifices because:

1. I don't understand why the performance of the oneshot scenario matters.
2. I don't use no_alloc.

Of course, you have different priorities because jiff may well become the Rust date-time crate. Especially with your name behind it!

[BurntSushi]

Maybe we're misunderstanding each other here. It seems quite likely that the same format string is going to be applied to multiple dates. When would you need to process millions of dates each with their own unique format string? You're saying that the single-pass architecture that jiff uses is faster in that case and I agree. However, that seems like such a rare use case. If you're processing millions of dates all with the same format string, then validating as a separate step to produce an efficient intermediate representation would surely be faster.

Oh! I see now. I get it. You may indeed be right about this. If the IR is done correctly and you're in a situation where you can amortize things, then yes, it's plausible there is a way to save some cycles here. I'd be curious how much is possible. My barometer here were the pre-built measurements I got from chrono and time being worse than measurements from the one-shot jiff APIs. But nothing really says that the prebuilt implementations in chrono and time are the fastest possible thing.

With that said, I would push back here and say that the format string itself can be see as an intermediate representation. The parsing really is that simple, and it's not clear to me that a structured representation would fair better.

Benefiting from a new IR representation that is prebuilt from the format string as a separate step does mean a new API. And it wouldn't mean deleting any existing APIs. So this is always something that can be added later if a use case really demands it. On perf alone, I'd want to see something really meaningful to justify the added code complexity.

One last thing I want to point out here is that I wouldn't necessarily expect to see strftime (or even strptime) used a ton in these situations if performance really mattered... Or at least, Jiff has an escape hatch here: all of the core datetime types have a Display impl. And there are lower level APIs that really let you amortize things by printing right into an existing buffer:

$ cargo bench -- 'print.*/(rfc|strftime).*buffer.*jiff' --save-baseline printing

$ critcmp printing
group                                 printing
-----                                 --------
print/rfc2822/buffer/jiff             1.00     13.2±0.13ns        ? ?/sec
print/rfc3339/buffer/jiff             1.00     21.8±0.07ns        ? ?/sec
print/rfc9557/buffer/jiff             1.00     16.9±0.17ns        ? ?/sec
print/strftime/oneshot/buffer/jiff    1.00     60.6±0.62ns        ? ?/sec

That's a very big difference. This is use case dependent, but if you're looking to format datetimes and you can use one of the standard formats, then you'll benefit massively in terms of performance if you do so. Moreover, if performance really really matters and you need a bespoke format, then I'd expect one to bypass strftime altogether and just write it out yourself. It's not that crazy to do. Jiff's printing machinery is only complicated because 1) it tries to optimize the shit out of everything, 2) it has to support the full range of values and 3) it has to support a bunch of knobs. If you take (2) + (3) out of the equation, then you can write something far simpler than what Jiff has and likely even faster and with less code bloat.

After looking at their code, it doesn't seem so surprising anymore that jiff beats their prebuilt benchmarks.

It was a little surprising to me! Hah. I had read that code. I went with the existing API before thinking too much about performance interestingly enough. It was originally almost twice as slow, and slower than the prebuilt versions of both chrono and time:

$ git co 836bc15e379a05aa3ab068b5298b2ce385364dfc

$ cargo bench -- strftime --save-baseline strftime-old

$ critcmp strftime-old
group                             strftime-old
-----                             ------------
print/strftime/oneshot/chrono     1.00    215.1±1.76ns        ? ?/sec
print/strftime/oneshot/jiff       1.00    159.1±1.18ns        ? ?/sec
print/strftime/prebuilt/chrono    1.00     85.1±0.88ns        ? ?/sec
print/strftime/prebuilt/time      1.00    102.1±0.90ns        ? ?/sec

To go as fast as possible, I'd imagine that the intermediate representation would be one contiguous block of memory (much like the format string itself). Each of the format specifiers could be encoded in a single-byte opcode. Additionally, there could be an opcode that means "the following byte is a literal" because single-byte literals between components are common. Finally, there could be an opcode that means "the following byte (or two) is a length and following that are the literal bytes". I'm quite confident that this would be faster because less work is being done on validating multi-byte sequences. Of course, a benchmark would be required to determine just how much of a difference this makes. I may end up writing that benchmark just for my own enjoyment!

I would love to see this. I would be quite surprised if you turned out to be right in any meaningful way. Because your description of the IR sounds a lot like the format string itself. :P Strings are valid representations! Don't discriminate against them! (I am poking fun a bit here.)

My proposal to have a separate validation step doesn't prevent jiff from exposing the existing API alongside it.

Oh for sure indeed. And at the API level, I'd be okay with this. Because the jiff::fmt submodule "makes room" for these sorts of more annoying-to-use APIs.

It's really the implementation that is concerning to me. If you're doing two passes, will the performance of the common high level API suffer? You might say that using it is rare, but my aspiration here is that needing the prebuilt API is rare. That's how I want to think about it. If folks can use the higher level APIs and get best-in-class perf or even close to it, then that really is the best of all worlds I think.

At least, that's what I thought until you pointed out no_alloc. Avoiding memory allocations seems to me like the strongest reason for jiff staying as it is. If jiff couldn't allocate memory, then it could take a slice of uninitialised bytes to fill with the intermediate representation. People working with embedded systems are probably used to that sort of thing but it's inconvenient compared to the current API. You point out another option of using a macro which would be more convenient but that wouldn't be suitable for cases where the format string is dynamic.

This could still be done in non-breaking ways. And yeah, there are ways to make an API like this work in no-alloc. It's just important that it's an API tucked away somewhere and not the default convenience API for folks working with a dynamic memory allocator.

The alternative is to allocate and deallocate each time because if you're using that API, maybe the extra nanoseconds don't matter to you.

This is another point that goes to what I said above. I'd rather flip the perspective around and say, "if you're using the prebuilt API, then your best case scenario is gaining a handful of nanoseconds (which I am still skeptical is possible) for a 1) bespoke datetime format not covered by existing types and 2) with less convenient API." Such that using the convenient and more accessible API is the common case because it's already very fast. And you don't need to optimize every bit of your program. It may not be the bottleneck in the first place.

Hopefully this perspective helps with this:

I don't understand why the performance of the oneshot scenario matters.

...

Of course, you have different priorities because jiff may well become the Rust date-time crate. Especially with your name behind it!

Yeah sure that goes without saying haha. I try hard to incorporate all perspectives. And there is always a frustrating amount of hand-waving. Especially around perceptions involving what is common and what is rare. For that, I rely on people sharing experience reports (which I would kinda sorta bin this discussion under, and which I am very appreciative of!) and just looking every once in a while at Jiff's dependents to see how it's being used.

Thank you for the thoughtful discussion. :-)

[BurntSushi]

If you do the benchmarking with a structured IR, I strongly encourage you to do it as a patch into Jiff itself. Do not go off and build your own thing. Not because I don't want you to publish something (I'd encourage that if that's what you want to do!), but if your goal is an apples-to-apples benchmark comparison, then you really want to be on the inside of Jiff doing it, not the outside. This is one of those tasks where being able to handle the full generality of jiff::fmt::strtime::BrokenDownTime and the directive DSL is critical. Any implementation can sacrifice one or more things in there and easily beat Jiff. Jiff itself does this, and you can observe it by comparing the performance of %Y-%m-%dT%H:%M:%S%.f%:z via strftime for a Timestamp with jiff::fmt::temporal::DateTimePrinter::print_timestamp_with_offset. That example is on the nose, but there are more subtle things.

Basically, your implementation with a structured IR should pass the test suite inside of jiff::fmt::strtime.

[BurntSushi]

Also, for benchmarking, you might look at biff as a "real world" workload. You'll need to bring your own data, but it will give you a real program in which to try things. e.g.,

$ journalctl --this-boot -o short-iso-precise | biff tag lines | biff time fmt -f '%c' | biff untag -s | tail
Wed, May 27, 2026, 4:11:40 PM GMT-4 duff sudo[267686]: pam_unix(sudo:session): session closed for user root
Wed, May 27, 2026, 4:11:54 PM GMT-4 duff sudo[267697]:   andrew : TTY=pts/4 ; PWD=/home/andrew/code/rust/biff ; USER=root ; COMMAND=/usr/bin/journalctl --this-boot -o short-iso-precise
Wed, May 27, 2026, 4:11:54 PM GMT-4 duff sudo[267697]: pam_unix(sudo:session): session opened for user root(uid=0) by andrew(uid=1000)
Wed, May 27, 2026, 4:11:54 PM GMT-4 duff sudo[267697]: pam_unix(sudo:session): session closed for user root
Wed, May 27, 2026, 4:11:59 PM GMT-4 duff sudo[267708]:   andrew : TTY=pts/4 ; PWD=/home/andrew/code/rust/biff ; USER=root ; COMMAND=/usr/bin/journalctl --this-boot -o short-iso-precise
Wed, May 27, 2026, 4:11:59 PM GMT-4 duff sudo[267708]: pam_unix(sudo:session): session opened for user root(uid=0) by andrew(uid=1000)
Wed, May 27, 2026, 4:11:59 PM GMT-4 duff sudo[267708]: pam_unix(sudo:session): session closed for user root
Wed, May 27, 2026, 4:12:04 PM GMT-4 duff sudo[267721]:   andrew : TTY=pts/4 ; PWD=/home/andrew/code/rust/biff ; USER=root ; COMMAND=/usr/bin/journalctl --this-boot -o short-iso-precise
Wed, May 27, 2026, 4:12:04 PM GMT-4 duff sudo[267721]: pam_unix(sudo:session): session opened for user root(uid=0) by andrew(uid=1000)
Wed, May 27, 2026, 4:12:04 PM GMT-4 duff sudo[267721]: pam_unix(sudo:session): session closed for user root