. /include/boost/url /encoding_opts.hpp
100.00% Lines (4/4) 100.00% Functions (1/1)
[ ] prev/next file n p prev/next uncovered line
TLA Baseline Branch
Line Hits Code Line Hits Code
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
HITCBC 119   44137 encoding_opts( 119   44155 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
HITCBC 123   44137 : space_as_plus(space_as_plus) 123   44155 : space_as_plus(space_as_plus)
HITCBC 124   44137 , lower_case(lower_case) 124   44155 , lower_case(lower_case)
HITCBC 125   44137 , disallow_null(disallow_null) {} 125   44155 , disallow_null(disallow_null) {}
126   }; 126   };
127   127  
128   } // urls 128   } // urls
129   } // boost 129   } // boost
130   130  
131   #endif 131   #endif