boost/mysql/escape_string.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_ESCAPE_STRING_HPP
0009 #define BOOST_MYSQL_ESCAPE_STRING_HPP
0010
0011 #include <boost/mysql/error_code.hpp>
0012 #include <boost/mysql/string_view.hpp>
0013
0014 #include <boost/mysql/detail/escape_string.hpp>
0015 #include <boost/mysql/detail/output_string.hpp>
0016
0017 #include <boost/config.hpp>
0018
0019 namespace boost {
0020 namespace mysql {
0021
0022 struct format_options;
0023
0024 /**
0025  * \brief Identifies the context which a string is being escaped for.
0026  */
0027 enum class quoting_context : char
0028 {
0029     /// The string is surrounded by double quotes.
0030     double_quote = '"',
0031
0032     /// The string is surrounded by single quotes.
0033     single_quote = '\'',
0034
0035     /// The string is surrounded by backticks.
0036     backtick = '`',
0037 };
0038
0039 /**
0040  * \brief Escapes a string, making it safe for query composition.
0041  * \details
0042  * Given a string `input`, computes a string with special characters
0043  * escaped, and places it in `output`. This function is a low-level building
0044  * block for composing client-side queries with runtime string values without
0045  * incurring in SQL injection vulnerabilities.
0046  * If you can, prefer using higher-level functions like \ref format_sql.
0047  * \n
0048  * Escaping rules are different depending on the context a string is
0049  * being used in. `quot_ctx` identifies where the string will appear in
0050  * a query. Possible values are: \n
0051  * \li \ref quoting_context::double_quote : the string is surrounded by
0052  *     double quotes.
0053  * \li \ref quoting_context::single_quote : the string is surrounded by
0054  *     single quotes.
0055  * \li \ref quoting_context::backtick : the string is surrounded by
0056  *     backticks, as happens when escaping identifiers.
0057  * \n
0058  * By default, MySQL treats backslash characters as escapes in string values
0059  * (for instance, the string `"\n"` is treated as a newline). This behavior is
0060  * enabled by default, but can be disabled by enabling the
0061  * <a
0062  *    href="https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_no_backslash_escapes">`NO_BACKSLASH_ESCAPES`</a>
0063  * SQL mode. When enabled, backslashes no longer have a special meaning, which changes
0064  * the escaping rules. `opts.backslash_escapes` should be set to `true` if backslashes represent
0065  * escapes (i.e. `NO_BACKSLASH_ESCAPES` is not enabled), and `false` otherwise.
0066  * \n
0067  * MySQL can be configured to treat double-quoted strings as identifiers instead of values.
0068  * This is enabled by activating the
0069  * <a href="https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_ansi_quotes">`ANSI_QUOTES`</a> or
0070  * <a href="https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#sqlmode_ansi">`ANSI`</a> SQL modes.
0071  * Servers don't report whether this mode is enabled to clients.
0072  * This SQL mode is not directly supported by this function.
0073  * \n
0074  * `opts.charset` should identify the connection's character set (as given by the
0075  * `character_set_client` session variable). The character set is used to iterate
0076  * over the input string. It must be an ASCII-compatible character set (like \ref utf8mb4_charset).
0077  * All character sets allowed by `character_set_client` satisfy this requirement.
0078  * \n
0079  * You can use \ref any_connection::format_opts to retrieve an `opts` value suitable for your connection.
0080  * \n
0081  * \par Exception safety
0082  * Basic guarantee. Memory allocations may throw.
0083  *
0084  * \par Complexity
0085  * Linear in `input.size()`.
0086  *
0087  * \par Errors
0088  * \ref client_errc::invalid_encoding if `input` contains a string
0089  *      that is not valid according to `opts.charset`.
0090  */
0091 template <BOOST_MYSQL_OUTPUT_STRING OutputString>
0092 BOOST_ATTRIBUTE_NODISCARD error_code
0093 escape_string(string_view input, const format_options& opts, quoting_context quot_ctx, OutputString& output)
0094 {
0095     output.clear();
0096     return detail::escape_string(
0097         input,
0098         opts,
0099         static_cast<char>(quot_ctx),
0100         detail::output_string_ref::create(output)
0101     );
0102 }
0103
0104 }  // namespace mysql
0105 }  // namespace boost
0106
0107 #endif