boost/mysql/diagnostics.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_DIAGNOSTICS_HPP
0009 #define BOOST_MYSQL_DIAGNOSTICS_HPP
0010
0011 #include <boost/mysql/string_view.hpp>
0012
0013 #include <boost/mysql/detail/access.hpp>
0014
0015 #include <string>
0016
0017 namespace boost {
0018 namespace mysql {
0019
0020 /**
0021  * \brief Contains additional information about errors.
0022  * \details
0023  * This class is a container for additional diagnostics about an operation that
0024  * failed. It can contain server-generated messages (\ref server_message) or client-side messages
0025  * (\ref client_message). More members may be added in the future.
0026  */
0027 class diagnostics
0028 {
0029 public:
0030     /**
0031      * \brief Constructs a diagnostics object with empty error messages.
0032      * \par Exception safety
0033      * No-throw guarantee.
0034      */
0035     diagnostics() = default;
0036
0037     /**
0038      * \brief Gets the client-generated error message.
0039      * \details
0040      * Contrary to \ref server_message, the client message never contains any string data
0041      * returned by the server, and is always ASCII-encoded. If you're using the static interface,
0042      * it may contain C++ type identifiers, too.
0043      *
0044      * \par Exception safety
0045      * No-throw guarantee.
0046      *
0047      * \par Object lifetimes
0048      * The returned view is valid as long as `*this` is alive, hasn't been assigned-to
0049      * or moved-from, and \ref clear hasn't been called. Moving `*this` invalidates the view.
0050      */
0051     string_view client_message() const noexcept
0052     {
0053         return impl_.is_server ? string_view() : string_view(impl_.msg);
0054     }
0055
0056     /**
0057      * \brief Gets the server-generated error message.
0058      * \details
0059      * It's encoded according to `character_set_results` character set, which
0060      * usually matches the connection's character set. It may potentially contain user input.
0061      *
0062      * \par Exception safety
0063      * No-throw guarantee.
0064      *
0065      * \par Object lifetimes
0066      * The returned view is valid as long as `*this` is alive, hasn't been assigned-to
0067      * or moved-from, and \ref clear hasn't been called. Moving `*this` invalidates the view.
0068      */
0069     string_view server_message() const noexcept
0070     {
0071         return impl_.is_server ? string_view(impl_.msg) : string_view();
0072     }
0073
0074     /**
0075      * \brief Clears the error messages.
0076      * \par Exception safety
0077      * No-throw guarantee.
0078      */
0079     void clear() noexcept
0080     {
0081         impl_.is_server = false;
0082         impl_.msg.clear();
0083     }
0084
0085 private:
0086 #ifndef BOOST_MYSQL_DOXYGEN
0087     struct
0088     {
0089         bool is_server{};
0090         std::string msg;
0091
0092         void assign_client(std::string from)
0093         {
0094             msg = std::move(from);
0095             is_server = false;
0096         }
0097
0098         void assign_server(std::string from)
0099         {
0100             msg = std::move(from);
0101             is_server = true;
0102         }
0103
0104     } impl_;
0105
0106     friend bool operator==(const diagnostics& lhs, const diagnostics& rhs) noexcept;
0107     friend struct detail::access;
0108 #endif
0109 };
0110
0111 /**
0112  * \relates diagnostics
0113  * \brief Compares two diagnostics objects.
0114  * \par Exception safety
0115  * No-throw guarantee.
0116  */
0117 inline bool operator==(const diagnostics& lhs, const diagnostics& rhs) noexcept
0118 {
0119     return lhs.impl_.is_server == rhs.impl_.is_server && lhs.impl_.msg == rhs.impl_.msg;
0120 }
0121
0122 /**
0123  * \relates diagnostics
0124  * \brief Compares two diagnostics objects.
0125  * \par Exception safety
0126  * No-throw guarantee.
0127  */
0128 inline bool operator!=(const diagnostics& lhs, const diagnostics& rhs) noexcept { return !(lhs == rhs); }
0129
0130 }  // namespace mysql
0131 }  // namespace boost
0132
0133 #endif