EIC code displayed by LXR master/​include/​boost/​mysql/​with_params.hpp	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-09-17 08:39:23

 //
 // Copyright (c) 2019-2025 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
 //
 // Distributed under the Boost Software License, Version 1.0. (See accompanying
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 //
 
 #ifndef BOOST_MYSQL_WITH_PARAMS_HPP
 #define BOOST_MYSQL_WITH_PARAMS_HPP
 
 #include <boost/mysql/constant_string_view.hpp>
 
 #include <boost/mysql/detail/format_sql.hpp>
 
 #include <tuple>
 #include <utility>
 
 namespace boost {
 namespace mysql {
 
 /**
  * \brief Type trait that applies the transformation performed by `std::make_tuple` to a single element.
  * \details
  * For example: \n
  *   - `make_tuple_element_t<int>` yields `int` \n
  *   - `make_tuple_element_t<const int&>` yields `int` \n
  *   - `make_tuple_element_t<std::reference_wrapper<int>>` yields `int&` \n
  * \n
  * Consult the <a href="https://en.cppreference.com/w/cpp/utility/tuple/make_tuple">`std::make_tuple`</a> docs
  * for more info.
  */
 template <class T>
 using make_tuple_element_t = typename std::tuple_element<0, decltype(std::make_tuple(std::declval<T&&>()))>::
     type;
 
 /**
  * \brief A query format string and format arguments that can be executed.
  * \details
  * Contains a query with placeholders (i.e. `{}`) and a set of parameters to
  * expand such placeholders. Satisfies `ExecutionRequest` and can thus be passed
  * to \ref any_connection::execute, \ref any_connection::start_execution and its
  * async counterparts.
  * \n
  * 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 \ref 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))
  *   );
  * ```
  * \n
  * Objects of this type are usually created using \ref with_params, which
  * creates `args` by calling `std::make_tuple`.
  *
  * \par Object lifetimes
  * The format string `query` is stored as a view, as a compile-time string should be used in most cases.
  * When using \ref with_params, `args` will usually contain copies of the passed parameters
  * (as per <a href="https://en.cppreference.com/w/cpp/utility/tuple/make_tuple">`std::make_tuple`</a>),
  * 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`.
  *
  * \par Errors
  * When passed to \ref any_connection::execute, \ref 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: \n
  *   - Any errors generated by \ref format_sql. This includes errors due to invalid format
  *     strings and unformattable arguments (e.g. invalid UTF-8).
  *   - \ref client_errc::unknown_character_set if the connection does not know the
  *     character set it's using when the query is executed (i.e. \ref any_connection::current_character_set
  *     would return an error.
  */
 template <BOOST_MYSQL_FORMATTABLE... Formattable>
 struct with_params_t
 {
     /// The query to be expanded and executed, which may contain `{}` placeholders.
     constant_string_view query;
 
     /// The arguments to use to expand the query.
     std::tuple<Formattable...> args;
 };
 
 /**
  * \brief Creates a query with parameters (client-side SQL formatting) that can be executed.
  * \details
  * Creates a \ref with_params_t object by packing the supplied arguments into a tuple,
  * calling <a href="https://en.cppreference.com/w/cpp/utility/tuple/make_tuple">`std::make_tuple`</a>.
  * As per `std::make_tuple`, parameters will be decay-copied into the resulting object.
  * This behavior can be disabled by passing `std::reference_wrapper` objects, which are
  * transformed into references.
  * \n
  * This function does not inspect the supplied query string and arguments.
  * Errors like missing format arguments are detected when the resulting object is executed.
  * This function does not involve communication with the server.
  * \n
  * The passed `args` must either satisfy `Formattable`, or be `std::reference_wrapper<T>`
  * with `T` satisfying `Formattable`.
  * \n
  * See \ref with_params_t for details on how the execution request works.
  * \n
  * \par Exception safety
  * Strong guarantee. Any exception thrown when copying `args` will be propagated.
  * \n
  */
 template <class... FormattableOrRefWrapper>
 auto with_params(constant_string_view query, FormattableOrRefWrapper&&... args)
     -> with_params_t<make_tuple_element_t<FormattableOrRefWrapper>...>
 {
     return {query, std::make_tuple(std::forward<FormattableOrRefWrapper>(args)...)};
 }
 
 }  // namespace mysql
 }  // namespace boost
 
 #include <boost/mysql/impl/with_params.hpp>
 
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team