boost/mysql/character_set.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_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 (EXPERIMENTAL) 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      * \n
0053      * \par Function signature
0054      * The function signature should be:
0055      * `std::size_t (*next_char)(boost::span<const unsigned char> r)`.
0056      */
0057     std::size_t (*next_char)(span<const unsigned char>);
0058 };
0059
0060 /// (EXPERIMENTAL) The utf8mb4 character set (the one you should use by default).
0061 BOOST_INLINE_CONSTEXPR character_set utf8mb4_charset
0062 #ifndef BOOST_MYSQL_DOXYGEN
0063     {"utf8mb4", detail::next_char_utf8mb4}
0064 #endif
0065 ;
0066
0067 /// (EXPERIMENTAL) The ascii character set.
0068 BOOST_INLINE_CONSTEXPR character_set ascii_charset
0069 #ifndef BOOST_MYSQL_DOXYGEN
0070     {"ascii", detail::next_char_ascii};
0071 #endif
0072 ;
0073
0074 /**
0075  * \brief (EXPERIMENTAL) Settings required to format SQL queries client-side.
0076  * \details
0077  * The recommended way to obtain a value of this type is using \ref any_connection::format_opts.
0078  */
0079 struct format_options
0080 {
0081     /// The connection's current character set.
0082     character_set charset;
0083
0084     /// Whether backslashes represent escape sequences.
0085     bool backslash_escapes;
0086 };
0087
0088 }  // namespace mysql
0089 }  // namespace boost
0090
0091 #ifdef BOOST_MYSQL_HEADER_ONLY
0092 #include <boost/mysql/impl/character_set.ipp>
0093 #endif
0094
0095 #endif