| Home | Libraries | People | FAQ | More

#### with_params_t

A query format string and format arguments that can be executed.

##### Synopsis

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

    template<
        class... Formattable>
    struct with_params_t;

##### Data Members

Name | Description
--- | ---
args | The arguments to use to expand the query.
query | The query to be expanded and executed, which may contain `{}` placeholders.

##### Description

Contains a query with placeholders (i.e. `{}`) and a set of parameters to expand such placeholders. Satisfies `ExecutionRequest` and can thus be passed to `any_connection::execute`, `any_connection::start_execution` and its async counterparts.

When executed, client-side SQL formatting is invoked to expand the provided query with the supplied parameters. The resulting query is then sent to the server for execution. Formally, given a `conn` variable of `any_connection` type, the query is generated as if the following was called:

    format_sql(
        this->query,
        conn.format_opts().value(),
        std::get<i>(this->args)... // for i in [0, sizeof...(Formattable))
    );

Objects of this type are usually created using `with_params`, which creates `args` by calling `std::make_tuple`.

##### Object lifetimes

The format string `query` is stored as a view, as a compile-time string should be used in most cases. When using `with_params`, `args` will usually contain copies of the passed parameters (as per `std::make_tuple`), which is safe even when using async functions with deferred completion tokens. You may disable such copies using `std::ref`, as you would when using `std::make_tuple`.

##### Errors

When passed to `any_connection::execute`, `any_connection::start_execution` or its async counterparts, in addition to the usual network and server-generated errors, `with_params_t` may generate the following errors:

- Any errors generated by `format_sql`. This includes errors due to invalid format strings and unformattable arguments (e.g. invalid UTF-8).
- `client_errc::unknown_character_set` if the connection does not know the character set it's using when the query is executed (i.e. `any_connection::current_character_set` would return an error.

Convenience header `<boost/mysql.hpp>`