Skip to content

ST::format_writer

Michael Hansen edited this page Nov 20, 2019 · 6 revisions

ST::format_writer

Headers

#include <string_theory/formatter>

Public Functions

Name Summary
(constructor) Initialize a format_writer
(destructor) Virtual destructor
append Append some text to the output
append_char Append one or more copies of a character to the output
next_format Advance to the next format specifier in the format string
parse_format Parse the current format specifier and return it

Related Non-Members

Name Summary
apply_format Apply formatting to a format_writer
format_string Helper to correctly format a string value based on provided format flags

Details

The format_writer class is used by the formatting functions to do the actual work of writing the formatted output. This may mean writing data to a buffer in memory, to a file, etc.

When implementing a new formatter, you'll need to create a subclass of ST::format_writer which implements the append() and append_char() functions. When implementing the formatter itself, you only need to construct an appropriate formatter and then pass it to apply_format(), which will take care of formatting the output and writing to your format_writer as appropriate.

For an example of subclassing format_writer to implement a custom format backend, see the custom format writer example on the Getting Started guide.

Member Documentation

ST::format_writer constructor

Signature
format_writer(const char *format)

Constructs the format_writer with the specified format string. This will start the formatter at the beginning of format, but will not yet write any data to the output.


ST::format_writer destructor [virtual]

Signature
virtual ~format_writer() noexcept

Virtual destructor for format writers. The base class does nothing, but it is provided in case a subclass needs to do work in the destructor.


ST::format_writer::append [pure virtual]

Signature
virtual format_writer &append(const char *data, size_t size = ST_AUTO_SIZE) = 0

Called by the formatters to write size bytes of data starting from data to the output. If size is ST_SIZE_AUTO, the implementation should compute the size of data with strlen() or equivalent.

Implementations should return a reference to this object (i.e. return *this) after handling the input data.


ST::format_writer::append_char [pure virtual]

Signature
virtual format_writer &append_char(char ch, size_t count = 1) = 0

Called by formatters to write count copies of the 7-bit ASCII character ch to the output.

Implementations should return a reference to this object (i.e. return *this) after handling the input characters.


ST::format_writer::next_format

Signature
bool next_format()

This should be called by format implementations to advance to the next user-specified format spec. This call may write data to the output if there are other characters in the input before the next format specifier.

If another format specifier was found in the input string, this will return true, and the specifier can be parsed with parse_format(). Otherwise, this will return false, indicating the entire format string and its formatted components have been written to the output.

Since string_theory 2.0.


ST::format_writer::parse_format

Signature
ST::format_spec parse_format()

This will parse the format specifier at the current position in the format string and return it, as well as advancing to the next character after the format specifier. This should only be called after next_format() returns true.

Since string_theory 2.0.


Related Non-Member Documentation

ST::apply_format

Signature
template <typename arg0_T, typename... args_T>
void apply_format(ST::format_writer &data, arg0_T &&arg0, args_T &&...args)
(1)
void apply_format(ST::format_writer &data) (2)

This should be called to apply a format string and its parameters to a ST::format_writer for output. It will do all the work of fetching arguments, parsing format specs, and calling format handlers for you, and the end result is that your data object should have everything written to its output.

Note that this may throw std::out_of_range if the format string specifies an argument index (either implicitly or explicitly) that is not in the range of the arguments provided.


ST::format_string

Signature
void ST::format_string(const ST::format_spec &format, ST::format_writer &output, const char *text, size_t size, ST::alignment_t default_alignment = ST::align_left)

Helper function for writing string data to a ST::format_writer. This can be called directly by formatters to handle properties like alignment and padding for string data formatted through other means. If the size and default_alignment parameters are set to defaults, this is essentially equivalent to ST_FORMAT_FORWARD with the string data.

See also ST_FORMAT_FORWARD()