boost/url/encode.hpp

0001 //
0002 // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
0003 // Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)
0004 //
0005 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0006 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0007 //
0008 // Official repository: https://github.com/boostorg/url
0009 //
0010
0011 #ifndef BOOST_URL_ENCODE_HPP
0012 #define BOOST_URL_ENCODE_HPP
0013
0014 #include <boost/url/detail/config.hpp>
0015 #include <boost/url/encoding_opts.hpp>
0016 #include <boost/core/detail/string_view.hpp>
0017 #include <boost/url/grammar/all_chars.hpp>
0018 #include <boost/url/grammar/string_token.hpp>
0019 #include <boost/url/grammar/type_traits.hpp>
0020 #include <boost/url/grammar/charset.hpp>
0021
0022 namespace boost {
0023 namespace urls {
0024
0025 /** Return the buffer size needed for percent-encoding
0026
0027     This function returns the exact number
0028     of bytes necessary to store the result
0029     of applying percent-encoding to the
0030     string using the given options and
0031     character set.
0032     No encoding is actually performed.
0033
0034     @par Example
0035     @code
0036     assert( encoded_size( "My Stuff", pchars ) == 10 );
0037     @endcode
0038
0039     @par Exception Safety
0040     Throws nothing.
0041
0042     @return The number of bytes needed,
0043     excluding any null terminator.
0044
0045     @param s The string to measure.
0046
0047     @param unreserved The set of characters
0048     that is not percent-encoded.
0049
0050     @param opt The options for encoding. If
0051     this parameter is omitted, the default
0052     options are be used.
0053
0054     @par Specification
0055     @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-2.1"
0056         >2.1. Percent-Encoding (rfc3986)</a>
0057
0058     @see
0059         @ref encode,
0060         @ref encoding_opts,
0061         @ref make_pct_string_view.
0062 */
0063 template<BOOST_URL_CONSTRAINT(grammar::CharSet) CS>
0064 std::size_t
0065 encoded_size(
0066     core::string_view s,
0067     CS const& unreserved,
0068     encoding_opts opt = {}) noexcept;
0069
0070 //------------------------------------------------
0071
0072 /** Apply percent-encoding to a string
0073
0074     This function applies percent-encoding
0075     to the string using the given options and
0076     character set. The destination buffer
0077     provided by the caller is used to store
0078     the result, which may be truncated if
0079     there is insufficient space.
0080
0081     @par Example
0082     @code
0083     char buf[100];
0084     assert( encode( buf, sizeof(buf), "Program Files", pchars ) == 15 );
0085     @endcode
0086
0087     @par Exception Safety
0088     Throws nothing.
0089
0090     @return The number of characters written
0091     to the destination buffer.
0092
0093     @param dest The destination buffer
0094     to write to.
0095
0096     @param size The number of writable
0097     characters pointed to by `dest`.
0098     If this is less than `encoded_size(s)`,
0099     the result is truncated.
0100
0101     @param s The string to encode.
0102
0103     @param unreserved The set of characters
0104     that is not percent-encoded.
0105
0106     @param opt The options for encoding. If
0107     this parameter is omitted, the default
0108     options are used.
0109
0110     @par Specification
0111     @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-2.1"
0112         >2.1. Percent-Encoding (rfc3986)</a>
0113
0114     @see
0115         @ref encode,
0116         @ref encoded_size,
0117         @ref make_pct_string_view.
0118 */
0119 template<BOOST_URL_CONSTRAINT(grammar::CharSet) CS>
0120 std::size_t
0121 encode(
0122     char* dest,
0123     std::size_t size,
0124     core::string_view s,
0125     CS const& unreserved,
0126     encoding_opts opt = {});
0127
0128 #ifndef BOOST_URL_DOCS
0129 // VFALCO semi-private for now
0130 template<BOOST_URL_CONSTRAINT(grammar::CharSet) CS>
0131 std::size_t
0132 encode_unsafe(
0133     char* dest,
0134     std::size_t size,
0135     core::string_view s,
0136     CS const& unreserved,
0137     encoding_opts opt);
0138 #endif
0139
0140 //------------------------------------------------
0141
0142 /** Return a percent-encoded string
0143
0144     This function applies percent-encoding
0145     to the string using the given options and
0146     character set, and returns the result as
0147     a string when called with default arguments.
0148
0149     @par Example
0150     @code
0151     encoding_opts opt;
0152     opt.space_as_plus = true;
0153     std::string s = encode( "My Stuff", opt, pchars );
0154
0155     assert( s == "My+Stuff" );
0156     @endcode
0157
0158     @par Exception Safety
0159     Calls to allocate may throw.
0160
0161     @return The string
0162
0163     @param s The string to encode.
0164
0165     @param unreserved The set of characters
0166     that is not percent-encoded.
0167
0168     @param opt The options for encoding. If
0169     this parameter is omitted, the default
0170     options are used.
0171
0172     @param token A string token.
0173
0174     @par Specification
0175     @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-2.1"
0176         >2.1. Percent-Encoding (rfc3986)</a>
0177
0178     @see
0179         @ref encode,
0180         @ref encoded_size,
0181         @ref encoding_opts,
0182 */
0183 template<
0184     BOOST_URL_STRTOK_TPARAM,
0185     BOOST_URL_CONSTRAINT(grammar::CharSet) CS>
0186 BOOST_URL_STRTOK_RETURN
0187 encode(
0188     core::string_view s,
0189     CS const& unreserved,
0190     encoding_opts opt = {},
0191     StringToken&& token = {}) noexcept;
0192
0193 } // urls
0194 } // boost
0195
0196 #include <boost/url/impl/encode.hpp>
0197
0198 #endif