| Home | Libraries | People | FAQ | More

##### format_sql_to (1 of 2 overloads)

Composes a SQL query client-side appending it to a format context.

###### Synopsis

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

    template<
        class... Formattable>
    void
    format_sql_to(
        format_context_base& ctx,
        constant_string_view format_str,
        Formattable&&... args);

###### Description

Parses `format_str` as a format string, substituting replacement fields (like `{}`, `{1}` or `{name}`) by formatted arguments, extracted from `args`.

Formatting is performed as if `format_context_base::append_raw` and `format_context_base::append_value` were called on `ctx`, effectively appending characters to its output string.

Compared to `format_sql`, this function is more flexible, allowing the following use cases:

- Appending characters to an existing context. Can be used to concatenate the output of successive format operations efficiently.
- Using string types different to `std::string` (works with any `basic_format_context`).
- Avoiding exceptions (see `basic_format_context::get`).

###### Exception safety

Basic guarantee. Memory allocations may throw.

###### Errors

- `client_errc::invalid_encoding` if `args` contains a string with byte sequences that can't be decoded with the current character set.
- `client_errc::unformattable_value` if `args` contains a floating-point value that is NaN or infinity.
- `client_errc::format_string_invalid_specifier` if a replacement field includes a specifier not supported by the type being formatted.
- Any other error generated by user-defined `formatter` specializations.
- `client_errc::format_string_invalid_syntax` if `format_str` can't be parsed as a format string.
- `client_errc::format_string_invalid_encoding` if `format_str` contains byte byte sequences that can't be decoded with the current character set.
- `client_errc::format_string_manual_auto_mix` if `format_str` contains a mix of automatic (`{}`) and manual indexed (`{1}`) replacement fields.
- `client_errc::format_arg_not_found` if an argument referenced by `format_str` isn't present in `args` (there aren't enough arguments or a named argument is not found).

Convenience header `<boost/mysql.hpp>`