boost/mysql/character_set.hpp

0001 //
0002 // Copyright (c) 2019-2025 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_CHARACTER_SET_HPP
0009 #define BOOST_MYSQL_CHARACTER_SET_HPP
0010
0011 #include <boost/mysql/detail/character_set.hpp>
0012 #include <boost/mysql/detail/config.hpp>
0013
0014 #include <boost/core/span.hpp>
0015
0016 #include <cstddef>
0017
0018 namespace boost {
0019 namespace mysql {
0020
0021 /**
0022  * \brief Represents a MySQL character set.
0023  * \details
0024  * By default, you should always use \ref utf8mb4_charset, unless there is
0025  * a strong reason not to. This struct allows you to extend this library
0026  * with character sets that are not supported out of the box.
0027  */
0028 struct character_set
0029 {
0030     /**
0031      * \brief The character set name, as a NULL-terminated string.
0032      * \details
0033      * This should match the character set name in MySQL. This is the string
0034      * you specify when issuing `SET NAMES` statements. You can find available
0035      * character sets using the `SHOW CHARACTER SET` statement.
0036      */
0037     const char* name;
0038
0039     /**
0040      * \brief Obtains the size of the first character of a string.
0041      * \details
0042      * Given a range of bytes, `r`, this function must interpret `r` as a
0043      * string encoded using this character set, and return the number of
0044      * bytes that the first character in the string spans, or 0 in case of error.
0045      * `r` is guaranteed to be non-empty (`r.size() > 0`).
0046      * \n
0047      * In some character sets (like UTF-8), not all byte sequences represent
0048      * valid characters. If this function finds an invalid byte sequence while
0049      * trying to interpret the first character, it should return 0 to signal the error.
0050      * \n
0051      * This function must not throw exceptions or have side effects.
0052      */
0053     std::size_t (*next_char)(span<const unsigned char>);
0054 };
0055
0056 /// The utf8mb4 character set (the one you should use by default).
0057 BOOST_INLINE_CONSTEXPR character_set utf8mb4_charset
0058 #ifndef BOOST_MYSQL_DOXYGEN
0059     {"utf8mb4", detail::next_char_utf8mb4}
0060 #endif
0061 ;
0062
0063 /// The ascii character set.
0064 BOOST_INLINE_CONSTEXPR character_set ascii_charset
0065 #ifndef BOOST_MYSQL_DOXYGEN
0066     {"ascii", detail::next_char_ascii};
0067 #endif
0068 ;
0069
0070 /**
0071  * \brief Settings required to format SQL queries client-side.
0072  * \details
0073  * The recommended way to obtain a value of this type is using \ref any_connection::format_opts.
0074  */
0075 struct format_options
0076 {
0077     /// The connection's current character set.
0078     character_set charset;
0079
0080     /// Whether backslashes represent escape sequences.
0081     bool backslash_escapes;
0082 };
0083
0084 }  // namespace mysql
0085 }  // namespace boost
0086
0087 #ifdef BOOST_MYSQL_HEADER_ONLY
0088 #include <boost/mysql/impl/character_set.ipp>
0089 #endif
0090
0091 #endif