url/include/boost/url/encoding_opts.hpp at develop · boostorg/url · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
//
// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
// Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
//
// Official repository: https://github.com/boostorg/url
//

#ifndef BOOST_URL_ENCODING_OPTS_HPP
#define BOOST_URL_ENCODING_OPTS_HPP

#include <boost/url/detail/config.hpp>

namespace boost {
namespace urls {

/** Percent-encoding options

    These options are used to customize
    the behavior of algorithms which use
    percent escapes, such as encoding
    or decoding.

    @see
        @ref encode,
        @ref encoded_size,
        @ref pct_string_view.
*/
struct encoding_opts
{
    /** True if spaces encode to and from plus signs

        Although not prescribed by RFC 3986,
        many applications decode plus signs
        in URL queries as spaces. In particular,
        the form-urlencoded Media Type in HTML
        for submitting forms uses this convention.

        This option controls whether
        the PLUS character ("+") is used to
        represent the SP character (" ") when
        encoding or decoding.

        When this option is `true`, both the
        encoded SP ("%20") and the PLUS
        character ("+") represent a space (" ")
        when decoding. To represent a plus sign,
        its encoded form ("%2B") is used.

        The @ref encode and @ref encoded_size functions
        will encode spaces as plus signs when
        this option is `true`, regardless of the
        allowed character set. They will also
        encode plus signs as "%2B" when this
        option is `true`, regardless of the
        allowed character set.

        Note that when a URL is normalized,
        all unreserved percent-encoded characters are
        replaced with their unreserved equivalents.
        However, normalizing the URL query maintains
        the decoded and encoded "&=+" as they are
        because they might have different meanings.

        This behavior is not optional because
        normalization can only mitigate false
        negatives, but it should eliminate
        false positives.
        Making it optional would allow
        a false positive because there's
        at least one very relevant schema (HTTP)
        where a decoded or encoded "&=+" has different
        meanings and represents different resources.

        The same considerations apply to URL comparison
        algorithms in the library, as they treat URLs
        as if they were normalized.

        @par Specification
        @li <a href="https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1">
            application/x-www-form-urlencoded (w3.org)</a>
        @li <a href="https://datatracker.ietf.org/doc/html/rfc1866#section-8.2.1">
            The form-urlencoded Media Type (RFC 1866)</a>
        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2.2">
            Section 6.2.2.2. Percent-Encoding Normalization (RFC 3986)</a>
    */
    bool space_as_plus = false;

    /** True if hexadecimal digits are emitted as lower case

        By default, percent-encoding algorithms
        emit hexadecimal digits A through F as
        uppercase letters. When this option is
        `true`, lowercase letters are used.
    */
    bool lower_case = false;

    /** True if nulls are not allowed

        Normally all possible character values
        (from 0 to 255) are allowed, with reserved
        characters being replaced with escapes
        upon encoding. When this option is true,
        attempting to decode a null will result
        in an error.
    */
    bool disallow_null = false;

    /** Constructs an `encoding_opts` object with the specified options.

        @param space_as_plus If true, spaces will be encoded as plus signs.
        @param lower_case If true, hexadecimal digits will be emitted as lower case.
        @param disallow_null If true, null characters will not be allowed.
     */
    BOOST_CXX14_CONSTEXPR
    inline
    encoding_opts(
        bool const space_as_plus = false,
        bool const lower_case = false,
        bool const disallow_null = false) noexcept
        : space_as_plus(space_as_plus)
        , lower_case(lower_case)
        , disallow_null(disallow_null) {}
};

} // urls
} // boost

#endif