Improve documentation for best practices around specializing fmt::formatter

[yeswalrus]

This is a request/discussion issue:
I feel the documentation around how to do this well is somewhat minimal. If there are known best practices, it'd be really nice to document them, perhaps by adding a few more complex examples. One good case might be how to provide formatting for a custom 'point' type. Such a type might have an underlying floating point storage, so a user might want to be able to format using the full range of floating point specs and have them be used. Are there known pitfalls to doing this? Certainly the width spec is a little weird since it's hard to say if it's the user's intent for that to apply to each coordinate or the overall point output. Currently this would require re-implementing (or just copy-pasting) the internals of the existing floating point spec parser since those fields are all understandably private to, I'm guessing, limit API surface. Is this even an expected use-case?

[yeswalrus]

Edit: This is a bad example since this just works with ranges.h. However, imagining we wanted to do it for a struct with x and y coordinates or some other thing where we might want to handle a similar range of formatting specifiers would be interesting.

[vitaut]

Thanks for the suggestion. I agree that the extension API documentation is somewhat lacking at the moment.

Are there known pitfalls to doing this?

Not sure about pitfalls, the format spec API just needs some cleanup and documentation.

Is this even an expected use-case?

Yes.

[AndrewJD79]

It's not clear from documentation should I use FMT_STRING or simple string literal in case of I need the best performance?

[vitaut]

should I use FMT_STRING or simple string literal in case of I need the best performance?

There is no difference in perf between the two.

[LukeMauldin]

Is there a link somewhere to the updated documentation on overloading fmt::formatter? I am able to override it for a base class but it is not being invoked on a derived class.

[vitaut]

The documentation for the latest release is available here: https://fmt.dev/latest/api.html#formatting-user-defined-types

[mmolch]

Hi, I am new to fmt and since my small issue deals with the same section of the documentation, I decided to put it here.
I tried to print an std::array and got the following error message:
error: static assertion failed: Cannot format an argument. To make type T formattable provide a formatter specialization: https://fmt.dev/latest/api.html#udt

It's great that there's a link, but unfortunately there's no immediate mention of ranges.h so I unknowingly reinvented the wheel and only just now found out about it. It would be great IMHO if the API reference would have a short notice right at the beginning of the "Formatting User-defined Types" section saying something like:
Note: The fmt library already contains formatters for a lot of C++ standard data types. See ranges.h (link to #ranges-api) for containers and tuples and chrono.h (link to #chrono-api) for date and time formatting.

Maybe the error message itself could be a little more verbose in this regard as well?

Thank you very much for this great library and kind regards,
Moritz

[vitaut]

@mmolch, good idea, thanks! Added (slightly tweaked) to the current dev docs in https://fmt.dev/dev/api.html#udt.

[provtemp]

@vitaut There you have »The formatter should parse specifiers until '}' or the end of the range.« - wouldn't you have to check at least for }} to follow the convention that doubling escapes the delimiter?

[vitaut]

wouldn't you have to check at least for }} to follow the convention that doubling escapes the delimiter?

No, } is not allowed in format specs, at least not in the standard ones.

[provtemp]

@vitaut So implementations of the parse method are free to pick an end point as they see fit, so long as it's a } between ctx.begin() and ctx.end(), like all 3 of these points would be fine:

{0:}}}{1}
   1 2  3

I would have expected that I can look at a format string and tell what is literal text and what isn't.

[vitaut]

In theory yes but I wouldn't recommend it. None of the standard formatters do this.

[cfyzium]

Correct me if I'm wrong, but it seems the only options for custom formatter are either do format spec parsing manually or completely delegate the whole process to some other existing formatter, with no utilities to parse the standard format spec string.

If I want a custom formatter that supports standard format spec parameters like fill/alignment, the proposed solution is to derive from fmt::formatter<fmt::string_view> to reuse its behavior.

Well, the base formatter may handle fill and alignment, but what about other parameters: floating-point format and precision, sign, alternative form, locale flag? There is no access to these in a derived formatter.

Furthermore, treatment of some parameters becomes somewhat inconsistent. The default alignment of string and numeric arguments is different:

fmt::format("{:6}", 10);                // "      10"
fmt::format("{:6}", Point<int>{1, 2});  // "(1,2)   "

And even if you somehow do a scan of the spec string to extract the precision option, the base string formatter has a very different purpose for precision:

fmt::format("{:.2}", Point<float>{1.5f, 2.0f});  // "(1" instead of "(1.50,2.00)"

Ah, and things like {:e} are impossible.

Seems like reusing existing formatters for anything beyond basic string alignment is not feasible.

But then it means in the general case you have to reimplement the entire formatting spec parsing and some of the standard formatting behavior from scratch.

Which is a fairly complex task with a few obscure and subtle parts. Things like access to nested width and precision arguments are complicated, conformance to standard behavior is tedious, and how many people would notice right away that the fill character may not be a single char but a multi-byte UTF-8 codepoint?

Complex, error-prone, and not very productive task but what are the alternatives? While the library parses standard format spec string in its base formatter implementation, it seems to be hidden inside the detail namespace with no official way to access the parse results.

I think it would be useful to have a public type for parsing results of standard format spec, with either a field accessible for inspection and modification in derived formatters or simply a utility function to explicitly parse the standard format spec.

[vitaut]

Format string parsing is indeed not exposed in the public API at the moment.