-
Notifications
You must be signed in to change notification settings - Fork 12
ST::format_writer
#include <string_theory/formatter>
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 |
Name | Summary |
---|---|
apply_format | Apply formatting to a format_writer
|
format_string | Helper to correctly format a string value based on provided format flags |
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.
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.
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.
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.
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.
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.
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.
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.
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()