Documentation issues

[gnzlbg]

I was going through the documentation and found out the following minor issues:

• The features say:

Two APIs: faster concatenation-based write API and slower (but still very fast) replacement-based format API with positional arguments for localization.

But the docs do not mention much more about this. There is a link to a benchmark page but in my opinion the documentation should make it very explicit which API to use to get the fastest code (the documentation of the writer API should say this), and the documentation of the slower API (the format API) should have disclaimers that indicate that, while possibly nicer/more convenient, that API is slower.

• More examples for the format API: I missed examples of formatting floating point numbers using the format API (there is no single example that uses all the options available {:+03.2f}. ).
• It would be nice if for each syntax option like f or g or e the syntax page would show, next to the option, how a particular floating point number would get formatted out. That is, it would be nice to have one or two examples of "number + syntax + result" next to each option. It would be nice if the examples would range for simple {:e} to more complicated involving also +/-, precision, positional arguments, corner cases (inf, nan). For example there is a situation where it is explained how to translate from C fprintf syntax to fmt syntax. While this is nice, I actually had to google what the C fprintf syntax actually meant.
• I wanted to format floating point numbers as fast as possible and wanted to use the writer API for this but there are no comprehensive examples about how to use the writer API to format floating point numbers as fast as possible.
• Is it posible to reserve the size of a BasicMemoryWriter? I thought this would be very important for performance but it doesn't seem to be possible.

These are just nitpicks, all the information is there, but the docs make me in my opinion invest too much effort into putting it all together. Complicated examples that make use of all the features would really help.

[gnzlbg]

Or in other words, while everything there might be common knowledge for someone doing formatting every day, 99% of the time I just do std::cout << value and it does the right thing (or just write print({}, value)). Every couple of months I actually need more precise formatting and it would be nice if the docs would be "comprehensive enough" to be instantaneously useful for somebody that doesn't need this every day.

[gnzlbg]

One use case I have is efficiently formatting a lot of floating point numbers into a large file.

My plan was to open a new file in append mode, creating a writer, reserving some memory, and in a loop: clear the writers contents (without freeing the memory), formating into the writer, appending writer contents to a file.

However it doesn't seem to be possible to neither reserve nor clear a writers memory, so maybe I shouldn't be using the writer API for this.

[vitaut]

Thanks for the detailed feedback.

in my opinion the documentation should make it very explicit which API to use to get the fastest code (the documentation of the writer API should say this), and the documentation of the slower API (the format API) should have disclaimers that indicate that, while possibly nicer/more convenient, that API is slower.

I've tried to clarify this in f765832. You can view the development docs here: http://fmtlib.net/dev/api.html

More examples for the format API: I missed examples of formatting floating point numbers using the format API (there is no single example that uses all the options available {:+03.2f}. ).

Do you mean examples in the syntax or API section?

It would be nice if for each syntax option like f or g or e the syntax page would show, next to the option, how a particular floating point number would get formatted out.

Good idea.

I wanted to format floating point numbers as fast as possible and wanted to use the writer API for this but there are no comprehensive examples about how to use the writer API to format floating point numbers as fast as possible.

Floating-point formatting is currently based on printf and the only advantage that the write API provides right now compared to the format API is avoiding std::string construction. There are plans to improve this: #147, #85.

Is it posible to reserve the size of a BasicMemoryWriter? I thought this would be very important for performance but it doesn't seem to be possible.

No, but it should be easy to add.

I think you have nice ideas for improving the docs. Would you by any chance be interested in contributing?

[vitaut]

My plan was to open a new file in append mode, creating a writer, reserving some memory, and in a loop: clear the writers contents (without freeing the memory), formating into the writer, appending writer contents to a file.

Sounds reasonable. The buffer will grow dynamically and subsequent writes can reuse it without reallocation. There are undocumented methods to get access to and clear the buffer called BasicWriter::buffer and BasicWriter::clear, but I am not 100% convinced that they fit the writer concept. It might be better to open a separate issue to discuss clear/reserve functionality.

[vitaut]

Migrated the item about examples to #213.