1   
//
1   
//
2   
// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
2   
// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
3   
// Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)
3   
// Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)
4   
//
4   
//
5   
// Distributed under the Boost Software License, Version 1.0. (See accompanying
5   
// Distributed under the Boost Software License, Version 1.0. (See accompanying
6   
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6   
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7   
//
7   
//
8   
// Official repository: https://github.com/boostorg/url
8   
// Official repository: https://github.com/boostorg/url
9   
//
9   
//
10  
10  
11   
#ifndef BOOST_URL_ENCODING_OPTS_HPP
11   
#ifndef BOOST_URL_ENCODING_OPTS_HPP
12   
#define BOOST_URL_ENCODING_OPTS_HPP
12   
#define BOOST_URL_ENCODING_OPTS_HPP
13  
13  
14   
#include <boost/url/detail/config.hpp>
14   
#include <boost/url/detail/config.hpp>
15  
15  
16   
namespace boost {
16   
namespace boost {
17   
namespace urls {
17   
namespace urls {
18  
18  
19   
/** Percent-encoding options
19   
/** Percent-encoding options
20  
20  
21   
    These options are used to customize
21   
    These options are used to customize
22   
    the behavior of algorithms which use
22   
    the behavior of algorithms which use
23   
    percent escapes, such as encoding
23   
    percent escapes, such as encoding
24   
    or decoding.
24   
    or decoding.
25  
25  
26   
    @see
26   
    @see
27   
        @ref encode,
27   
        @ref encode,
28   
        @ref encoded_size,
28   
        @ref encoded_size,
29   
        @ref pct_string_view.
29   
        @ref pct_string_view.
30   
*/
30   
*/
31   
struct encoding_opts
31   
struct encoding_opts
32   
{
32   
{
33   
    /** True if spaces encode to and from plus signs
33   
    /** True if spaces encode to and from plus signs
34  
34  
35   
        Although not prescribed by RFC 3986,
35   
        Although not prescribed by RFC 3986,
36   
        many applications decode plus signs
36   
        many applications decode plus signs
37   
        in URL queries as spaces. In particular,
37   
        in URL queries as spaces. In particular,
38   
        the form-urlencoded Media Type in HTML
38   
        the form-urlencoded Media Type in HTML
39   
        for submitting forms uses this convention.
39   
        for submitting forms uses this convention.
40  
40  
41   
        This option controls whether
41   
        This option controls whether
42   
        the PLUS character ("+") is used to
42   
        the PLUS character ("+") is used to
43   
        represent the SP character (" ") when
43   
        represent the SP character (" ") when
44   
        encoding or decoding.
44   
        encoding or decoding.
45  
45  
46   
        When this option is `true`, both the
46   
        When this option is `true`, both the
47   
        encoded SP ("%20") and the PLUS
47   
        encoded SP ("%20") and the PLUS
48   
        character ("+") represent a space (" ")
48   
        character ("+") represent a space (" ")
49   
        when decoding. To represent a plus sign,
49   
        when decoding. To represent a plus sign,
50   
        its encoded form ("%2B") is used.
50   
        its encoded form ("%2B") is used.
51  
51  
52   
        The @ref encode and @ref encoded_size functions
52   
        The @ref encode and @ref encoded_size functions
53   
        will encode spaces as plus signs when
53   
        will encode spaces as plus signs when
54   
        this option is `true`, regardless of the
54   
        this option is `true`, regardless of the
55   
        allowed character set. They will also
55   
        allowed character set. They will also
56   
        encode plus signs as "%2B" when this
56   
        encode plus signs as "%2B" when this
57   
        option is `true`, regardless of the
57   
        option is `true`, regardless of the
58   
        allowed character set.
58   
        allowed character set.
59  
59  
60   
        Note that when a URL is normalized,
60   
        Note that when a URL is normalized,
61   
        all unreserved percent-encoded characters are
61   
        all unreserved percent-encoded characters are
62   
        replaced with their unreserved equivalents.
62   
        replaced with their unreserved equivalents.
63   
        However, normalizing the URL query maintains
63   
        However, normalizing the URL query maintains
64   
        the decoded and encoded "&=+" as they are
64   
        the decoded and encoded "&=+" as they are
65   
        because they might have different meanings.
65   
        because they might have different meanings.
66  
66  
67   
        This behavior is not optional because
67   
        This behavior is not optional because
68   
        normalization can only mitigate false
68   
        normalization can only mitigate false
69   
        negatives, but it should eliminate
69   
        negatives, but it should eliminate
70   
        false positives.
70   
        false positives.
71   
        Making it optional would allow
71   
        Making it optional would allow
72   
        a false positive because there's
72   
        a false positive because there's
73   
        at least one very relevant schema (HTTP)
73   
        at least one very relevant schema (HTTP)
74   
        where a decoded or encoded "&=+" has different
74   
        where a decoded or encoded "&=+" has different
75   
        meanings and represents different resources.
75   
        meanings and represents different resources.
76  
76  
77   
        The same considerations apply to URL comparison
77   
        The same considerations apply to URL comparison
78   
        algorithms in the library, as they treat URLs
78   
        algorithms in the library, as they treat URLs
79   
        as if they were normalized.
79   
        as if they were normalized.
80  
80  
81   
        @par Specification
81   
        @par Specification
82   
        @li <a href="https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1">
82   
        @li <a href="https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1">
83   
            application/x-www-form-urlencoded (w3.org)</a>
83   
            application/x-www-form-urlencoded (w3.org)</a>
84   
        @li <a href="https://datatracker.ietf.org/doc/html/rfc1866#section-8.2.1">
84   
        @li <a href="https://datatracker.ietf.org/doc/html/rfc1866#section-8.2.1">
85   
            The form-urlencoded Media Type (RFC 1866)</a>
85   
            The form-urlencoded Media Type (RFC 1866)</a>
86   
        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.2">
86   
        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.2">
87   
            Section 6.2.2.2. Percent-Encoding Normalization (RFC 3986)</a>
87   
            Section 6.2.2.2. Percent-Encoding Normalization (RFC 3986)</a>
88   
    */
88   
    */
89   
    bool space_as_plus = false;
89   
    bool space_as_plus = false;
90  
90  
91   
    /** True if hexadecimal digits are emitted as lower case
91   
    /** True if hexadecimal digits are emitted as lower case
92  
92  
93   
        By default, percent-encoding algorithms
93   
        By default, percent-encoding algorithms
94   
        emit hexadecimal digits A through F as
94   
        emit hexadecimal digits A through F as
95   
        uppercase letters. When this option is
95   
        uppercase letters. When this option is
96   
        `true`, lowercase letters are used.
96   
        `true`, lowercase letters are used.
97   
    */
97   
    */
98   
    bool lower_case = false;
98   
    bool lower_case = false;
99  
99  
100   
    /** True if nulls are not allowed
100   
    /** True if nulls are not allowed
101  
101  
102   
        Normally all possible character values
102   
        Normally all possible character values
103   
        (from 0 to 255) are allowed, with reserved
103   
        (from 0 to 255) are allowed, with reserved
104   
        characters being replaced with escapes
104   
        characters being replaced with escapes
105   
        upon encoding. When this option is true,
105   
        upon encoding. When this option is true,
106   
        attempting to decode a null will result
106   
        attempting to decode a null will result
107   
        in an error.
107   
        in an error.
108   
    */
108   
    */
109   
    bool disallow_null = false;
109   
    bool disallow_null = false;
110  
110  
111   
    /** Constructs an `encoding_opts` object with the specified options.
111   
    /** Constructs an `encoding_opts` object with the specified options.
112  
112  
113   
        @param space_as_plus If true, spaces will be encoded as plus signs.
113   
        @param space_as_plus If true, spaces will be encoded as plus signs.
114   
        @param lower_case If true, hexadecimal digits will be emitted as lower case.
114   
        @param lower_case If true, hexadecimal digits will be emitted as lower case.
115   
        @param disallow_null If true, null characters will not be allowed.
115   
        @param disallow_null If true, null characters will not be allowed.
116   
     */
116   
     */
117   
    BOOST_CXX14_CONSTEXPR
117   
    BOOST_CXX14_CONSTEXPR
118   
    inline
118   
    inline
119   
    encoding_opts(
119   
    encoding_opts(
120   
        bool const space_as_plus = false,
120   
        bool const space_as_plus = false,
121   
        bool const lower_case = false,
121   
        bool const lower_case = false,
122   
        bool const disallow_null = false) noexcept
122   
        bool const disallow_null = false) noexcept
123   
        : space_as_plus(space_as_plus)
123   
        : space_as_plus(space_as_plus)
124   
        , lower_case(lower_case)
124   
        , lower_case(lower_case)
125   
        , disallow_null(disallow_null) {}
125   
        , disallow_null(disallow_null) {}
126   
};
126   
};
127  
127  
128   
} // urls
128   
} // urls
129   
} // boost
129   
} // boost
130  
130  
131   
#endif
131   
#endif