boost/mysql/statement.hpp

0001 //
0002 // Copyright (c) 2019-2023 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
0003 //
0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0006 //
0007
0008 #ifndef BOOST_MYSQL_STATEMENT_HPP
0009 #define BOOST_MYSQL_STATEMENT_HPP
0010
0011 #include <boost/mysql/detail/access.hpp>
0012 #include <boost/mysql/detail/writable_field_traits.hpp>
0013
0014 #include <boost/assert.hpp>
0015
0016 #include <cstdint>
0017 #include <tuple>
0018 #include <type_traits>
0019
0020 namespace boost {
0021 namespace mysql {
0022
0023 /**
0024  * \brief A statement with bound parameters, represented as a `std::tuple`.
0025  * \details
0026  * This class satisfies `ExecutionRequest`. You can pass instances of this class to \ref connection::execute,
0027  * \ref connection::start_execution or their async counterparts.
0028  */
0029 template <BOOST_MYSQL_WRITABLE_FIELD_TUPLE WritableFieldTuple>
0030 class bound_statement_tuple;
0031
0032 /**
0033  * \brief A statement with bound parameters, represented as an iterator range.
0034  * \details
0035  * This class satisfies `ExecutionRequest`. You can pass instances of this class to \ref connection::execute,
0036  * \ref connection::start_execution or their async counterparts.
0037  */
0038 template <BOOST_MYSQL_FIELD_VIEW_FORWARD_ITERATOR FieldViewFwdIterator>
0039 class bound_statement_iterator_range;
0040
0041 /**
0042  * \brief Represents a server-side prepared statement.
0043  * \details
0044  * This is a lightweight class, holding a handle to a server-side prepared statement.
0045  * \n
0046  * Note that statement's destructor doesn't deallocate the statement from the
0047  * server, as this implies a network transfer that may fail.
0048  *
0049  * \par Thread safety
0050  * Distinct objects: safe. \n
0051  * Shared objects: unsafe. \n
0052  */
0053 class statement
0054 {
0055 public:
0056     /**
0057      * \brief Default constructor.
0058      * \details Default constructed statements have `this->valid() == false`.
0059      *
0060      * \par Exception safety
0061      * No-throw guarantee.
0062      */
0063     statement() = default;
0064
0065     /**
0066      * \brief Returns `true` if the object represents an actual server statement.
0067      * \details Calling any function other than assignment on a statement for which
0068      * this function returns `false` results in undefined behavior.
0069      * \n
0070      * Returns `false` for default-constructed statements.
0071      *
0072      * \par Exception safety
0073      * No-throw guarantee.
0074      */
0075     bool valid() const noexcept { return valid_; }
0076
0077     /**
0078      * \brief Returns a server-side identifier for the statement (unique in a per-connection basis).
0079      * \details Note that, once a statement is closed, the server may recycle its ID.
0080      *
0081      * \par Preconditions
0082      * `this->valid() == true`
0083      *
0084      * \par Exception safety
0085      * No-throw guarantee.
0086      */
0087     std::uint32_t id() const noexcept
0088     {
0089         BOOST_ASSERT(valid());
0090         return id_;
0091     }
0092
0093     /**
0094      * \brief Returns the number of parameters that should be provided when executing the statement.
0095      * \par Preconditions
0096      * `this->valid() == true`
0097      *
0098      * \par Exception safety
0099      * No-throw guarantee.
0100      */
0101     unsigned num_params() const noexcept
0102     {
0103         BOOST_ASSERT(valid());
0104         return num_params_;
0105     }
0106
0107     /**
0108      * \brief Binds parameters to a statement.
0109      * \details
0110      * Creates an object that packages `*this` and the statement actual parameters `params`.
0111      * This object can be passed to \ref connection::execute, \ref connection::start_execution
0112      * and their async counterparts.
0113      * \n
0114      * The parameters are copied into a `std::tuple` by using `std::make_tuple`. This function
0115      * only participates in overload resolution if `std::make_tuple(FWD(args)...)` yields a
0116      * `WritableFieldTuple`. Equivalent to `this->bind(std::make_tuple(std::forward<T>(params)...))`.
0117      * \n
0118      * This function doesn't involve communication with the server.
0119      *
0120      * \par Preconditions
0121      * `this->valid() == true`
0122      * \n
0123      * \par Exception safety
0124      * Strong guarantee. Only throws if constructing any of the internal tuple elements throws.
0125      */
0126     template <class... T>
0127 #ifdef BOOST_MYSQL_DOXYGEN
0128     bound_statement_tuple<std::tuple<__see_below__>>
0129 #else
0130     auto
0131 #endif
0132     bind(T&&... params) const->typename std::enable_if<
0133         detail::is_writable_field_tuple<decltype(std::make_tuple(std::forward<T>(params)...))>::value,
0134         bound_statement_tuple<decltype(std::make_tuple(std::forward<T>(params)...))>>::type
0135     {
0136         return bind(std::make_tuple(std::forward<T>(params)...));
0137     }
0138
0139     /**
0140      * \brief Binds parameters to a statement.
0141      * \details
0142      * Creates an object that packages `*this` and the statement actual parameters `params`.
0143      * This object can be passed to \ref connection::execute, \ref connection::start_execution
0144      * or their async counterparts.
0145      * \n
0146      * The `params` tuple is decay-copied into the returned object.
0147      * \n
0148      * This function doesn't involve communication with the server.
0149      *
0150      * \par Preconditions
0151      * `this->valid() == true`
0152      * \n
0153      * \par Exception safety
0154      * Strong guarantee. Only throws if the decay-copy of the tuple throws.
0155      */
0156     template <
0157         BOOST_MYSQL_WRITABLE_FIELD_TUPLE WritableFieldTuple,
0158         typename EnableIf =
0159             typename std::enable_if<detail::is_writable_field_tuple<WritableFieldTuple>::value>::type>
0160     bound_statement_tuple<typename std::decay<WritableFieldTuple>::type> bind(WritableFieldTuple&& params
0161     ) const;
0162
0163     /**
0164      * \brief Binds parameters to a statement (iterator range overload).
0165      * \details
0166      * Creates an object that packages `*this` and the statement actual parameters, represented
0167      * as the iterator range `[params_first, params_last)`.
0168      * This object can be passed to \ref connection::execute, \ref connection::start_execution
0169      * or their async counterparts.
0170      * \n
0171      * This function doesn't involve communication with the server.
0172      *
0173      * \par Preconditions
0174      * `this->valid() == true`
0175      * \n
0176      * \par Exception safety
0177      * Strong guarantee. Only throws if copy-constructing iterators throws.
0178      */
0179     template <
0180         BOOST_MYSQL_FIELD_VIEW_FORWARD_ITERATOR FieldViewFwdIterator,
0181         typename EnableIf = typename std::enable_if<
0182             detail::is_field_view_forward_iterator<FieldViewFwdIterator>::value>::type>
0183     bound_statement_iterator_range<FieldViewFwdIterator> bind(
0184         FieldViewFwdIterator params_first,
0185         FieldViewFwdIterator params_last
0186     ) const;
0187
0188 private:
0189     bool valid_{false};
0190     std::uint32_t id_{0};
0191     std::uint16_t num_params_{0};
0192
0193     statement(std::uint32_t id, std::uint16_t num_params) noexcept
0194         : valid_(true), id_(id), num_params_(num_params)
0195     {
0196     }
0197
0198 #ifndef BOOST_MYSQL_DOXYGEN
0199     friend struct detail::access;
0200 #endif
0201 };
0202
0203 }  // namespace mysql
0204 }  // namespace boost
0205
0206 #include <boost/mysql/impl/statement.hpp>
0207
0208 #endif