| Home | Libraries | People | FAQ | More

#### formatter

(EXPERIMENTAL) An extension point to customize SQL formatting.

##### Synopsis

Defined in header `<boost/mysql/format_sql.hpp>`

    template<
        class T>
    struct formatter

##### Description

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:

- An instance of `formatter<T>` is default-constructed, where `T` is the type of the value being formatted after removing const and references.
- The `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`:
  - In `"SELECT {}"`, the range would be empty.
  - In `"SELECT {:abc}"`, the range would be `"abc"`.
  - In `"SELECT {0:i}"`, the range would be `"i"`.
- If `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.
- Otherwise, `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.