![]() |
Home | Libraries | People | FAQ | More |
An extension point to customize SQL formatting.
Defined in header <boost/mysql/format_sql.hpp>
template< class T> struct formatter;
This type can be specialized for custom types to make them formattable. This
makes them satisfy the Formattable
concept, and thus usable in format_sql and similar functions.
A formatter specialization
for a type T should have
the following form:
template <> struct formatter<T> { const char* parse(const char* begin, const char* end); // parse format specs void format(const T& value, format_context_base& ctx) const; // perform the actual formatting };
When a value with a custom formatter is formatted (using format_sql or a similar function),
the library performs the following actions:
formatter<T> is default-constructed, where T is the type of the value being formatted
after removing const and references.
parse function is
invoked on the constructed instance, with [begin, end)
pointing to the format specifier that the current replacement field has.
If parse finds specifiers
it understands, it should remember them, usually setting some flag in
the formatter instance.
parse must return an
iterator to the first unparsed character in the range (or the end iterator, if everything was parsed).
Some examples of what would get passed to parse:
"SELECT {}",
the range would be empty.
"SELECT {:abc}",
the range would be "abc".
"SELECT {0:i}",
the range would be "i".
parse didn't manage
to parse all the passed specifiers (i.e. if it returned an iterator different
to the passed's end), a client_errc::format_string_invalid_specifier
is emitted and the format operation finishes.
format is
invoked on the formatter instance, passing the value to be formatted
and the format_context_base where format
operation is running. This function should perform the actual formatting,
usually calling format_sql_to on the passed
context.
Don't specialize formatter
for built-in types, like int,
std::string or optionals (formally, any type
satisfying WritableField),
as the specializations will be ignored.
Convenience header <boost/mysql.hpp>