boost/mysql/constant_string_view.hpp

0001 //
0002 // Copyright (c) 2019-2024 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_CONSTANT_STRING_VIEW_HPP
0009 #define BOOST_MYSQL_CONSTANT_STRING_VIEW_HPP
0010
0011 #include <boost/mysql/string_view.hpp>
0012
0013 #include <boost/mysql/detail/config.hpp>
0014
0015 #include <boost/config.hpp>
0016
0017 #include <type_traits>
0018
0019 namespace boost {
0020 namespace mysql {
0021
0022 /**
0023  * \brief (EXPERIMENTAL) A string view that should be known at compile-time.
0024  * \details
0025  * This type is used when a string function argument must always be known at compile-time
0026  * except in rare cases. See \ref format_sql format strings for an example.
0027  * \n
0028  * \par Object lifetimes
0029  * This type holds internally a \ref string_view, and follows the same lifetime rules as `string_view`.
0030  * We recommend to only use this type as a function argument, to provide compile-time checks.
0031  */
0032 class constant_string_view
0033 {
0034     string_view impl_;
0035
0036 #ifndef BOOST_MYSQL_DOXYGEN
0037     constexpr constant_string_view(string_view value, int) noexcept : impl_(value) {}
0038     friend constexpr constant_string_view runtime(string_view) noexcept;
0039 #endif
0040
0041 public:
0042     /**
0043      * \brief Consteval constructor.
0044      * \details
0045      * Constructs a \ref string_view from the passed argument.
0046      * \n
0047      * This function is `consteval`: it results in a compile-time error
0048      * if the passed value is not known at compile-time. You can bypass
0049      * this check using the \ref runtime function. This check works only
0050      * for C++20 and above. No check is performed for lower C++ standard versions.
0051      * \n
0052      * This constructor is only considered if a \ref string_view can be constructed
0053      * from the passed value.
0054      *
0055      * \par Exception safety
0056      * No-throw guarantee.
0057      *
0058      * \par Object lifetimes
0059      * Ownership is not transferred to the constructed object. As with `string_view`,
0060      * the user is responsible for keeping the original character buffer alive.
0061      */
0062     template <
0063         class T
0064 #ifndef BOOST_MYSQL_DOXYGEN
0065         ,
0066         class = typename std::enable_if<std::is_convertible<const T&, string_view>::value>::type
0067 #endif
0068         >
0069     BOOST_MYSQL_CONSTEVAL constant_string_view(const T& value) noexcept : impl_(value)
0070     {
0071     }
0072
0073     /**
0074      * \brief Retrieves the underlying string view.
0075      *
0076      * \par Exception safety
0077      * No-throw guarantee.
0078      *
0079      * \par Object lifetimes
0080      * The returned view has the same lifetime rules as `*this`.
0081      */
0082     constexpr string_view get() const noexcept { return impl_; }
0083 };
0084
0085 /**
0086  * \brief (EXPERIMENTAL) Creates a \ref constant_string_view from a runtime value.
0087  * \details
0088  * You can use this function to bypass the `consteval` check performed by \ref constant_string_view
0089  * constructor.
0090  * \n
0091  * Don't use this function unless you know what you are doing. `consteval` checks exist
0092  * for the sake of security. Make sure to only pass trusted values to the relevant API.
0093  *
0094  * \par Exception safety
0095  * No-throw guarantee.
0096  *
0097  * \par Object lifetimes
0098  * The returned value has the same lifetime semantics as the passed view.
0099  */
0100 constexpr constant_string_view runtime(string_view value) noexcept { return constant_string_view(value, 0); }
0101
0102 }  // namespace mysql
0103 }  // namespace boost
0104
0105 #endif