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