Index/include / boost / url / params_view.hpp
Prev Index Next

include/boost/url/params_view.hpp

100.0% Lines (1/1) 100.0% Functions (1/1) -% Branches (0/0)
include/boost/url/params_view.hpp
Line Hits Source Code
1 //
2 // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
3 // Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)
4 //
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)
7 //
8 // Official repository: https://github.com/boostorg/url
9 //
10
11 #ifndef BOOST_URL_PARAMS_VIEW_HPP
12 #define BOOST_URL_PARAMS_VIEW_HPP
13
14 #include <boost/url/detail/config.hpp>
15 #include <boost/url/params_base.hpp>
16
17 namespace boost {
18 namespace urls {
19
20 /** Non-owning decoded query parameter view
21
22 This read-only range interprets the query
23 string of a URL as bidirectional key/value
24 pairs with percent-decoding applied on
25 access. It merely references the original
26 character buffer; callers must keep that
27 buffer alive while the view is used.
28
29 @par Example
30 @code
31 url_view u( "?first=John&last=Doe" );
32
33 params_view p = u.params();
34 @endcode
35
36 Strings retrieved from the iterators are
37 automatically percent-decoded.
38
39 @par Iterator Invalidation
40 Changes to the underlying character buffer
41 can invalidate iterators which reference it.
42 */
43 class BOOST_URL_DECL params_view
44 : public params_base
45 {
46 friend class url_view_base;
47 friend class params_encoded_view;
48 friend class params_ref;
49
50 params_view(
51 detail::query_ref const& ref,
52 encoding_opts opt) noexcept;
53
54 public:
55 /** Constructor
56
57 Default-constructed params have
58 zero elements.
59
60 @par Example
61 @code
62 params_view qp;
63 @endcode
64
65 @par Effects
66 @code
67 return params_view( "" );
68 @endcode
69
70 @par Complexity
71 Constant.
72
73 @par Exception Safety
74 Throws nothing.
75 */
76 1 params_view() = default;
77
78 /** Constructor
79
80 After construction both views reference
81 the same character buffer.
82
83 Ownership is not transferred; the caller
84 is responsible for ensuring the lifetime
85 of the buffer extends until it is no
86 longer referenced.
87
88 @par Postconditions
89 @code
90 this->buffer().data() == other.buffer().data()
91 @endcode
92
93 @par Complexity
94 Constant.
95
96 @par Exception Safety
97 Throws nothing
98
99 @param other The object to copy
100 */
101 params_view(
102 params_view const& other) = default;
103
104 /** Constructor
105
106 After construction both views will
107 reference the same character buffer
108 but this instance will use the specified
109 @ref encoding_opts when the values
110 are decoded.
111
112 Ownership is not transferred; the caller
113 is responsible for ensuring the lifetime
114 of the buffer extends until it is no
115 longer referenced.
116
117 @par Postconditions
118 @code
119 this->buffer().data() == other.buffer().data()
120 @endcode
121
122 @par Complexity
123 Constant.
124
125 @par Exception Safety
126 Throws nothing
127
128 @param other The object to copy
129 @param opt The options for decoding
130 */
131 params_view(
132 params_view const& other,
133 encoding_opts opt) noexcept;
134
135 /** Constructor
136
137 This function constructs params from
138 a valid query parameter string, which
139 can contain percent escapes. Unlike
140 the parameters in URLs, the string
141 passed here should not start with "?".
142 Upon construction, the view references
143 the character buffer pointed to by `s`.
144 The caller is responsible for ensuring
145 that the lifetime of the buffer extends
146 until it is no longer referenced.
147
148 @par Example
149 @code
150 params_view qp( "first=John&last=Doe" );
151 @endcode
152
153 @par Effects
154 @code
155 return parse_query( s ).value();
156 @endcode
157
158 @par Postconditions
159 @code
160 this->buffer().data() == s.data()
161 @endcode
162
163 @par Complexity
164 Linear in `s`.
165
166 @par Exception Safety
167 Exceptions thrown on invalid input.
168
169 @throw system_error
170 `s` contains an invalid query parameter
171 string.
172
173 @param s The string to parse.
174
175 @par BNF
176 @code
177 query-params = [ query-param ] *( "&" query-param )
178
179 query-param = key [ "=" value ]
180 @endcode
181
182 @par Specification
183 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
184 >3.4. Query</a>
185 */
186 params_view(
187 core::string_view s);
188
189 /** Constructor
190
191 This function constructs params from
192 a valid query parameter string, which
193 can contain percent escapes.
194
195 This instance will use the specified
196 @ref encoding_opts when the values
197 are decoded.
198
199 Unlike the parameters in URLs, the string
200 passed here should not start with "?".
201 Upon construction, the view will
202 reference the character buffer pointed
203 to by `s`. The caller is responsible
204 for ensuring that the lifetime of the
205 buffer extends until it is no longer
206 referenced.
207
208 @par Example
209 @code
210 encoding_opts opt;
211 opt.space_as_plus = true;
212 params_view qp( "name=John+Doe", opt );
213 @endcode
214
215 @par Effects
216 @code
217 return params_view(parse_query( s ).value(), opt);
218 @endcode
219
220 @par Postconditions
221 @code
222 this->buffer().data() == s.data()
223 @endcode
224
225 @par Complexity
226 Linear in `s`.
227
228 @par Exception Safety
229 Exceptions thrown on invalid input.
230
231 @throw system_error
232 `s` contains an invalid query parameter
233 string.
234
235 @param s The string to parse.
236
237 @param opt The options for decoding. If
238 this parameter is omitted, `space_as_plus`
239 is used.
240
241 @par BNF
242 @code
243 query-params = [ query-param ] *( "&" query-param )
244
245 query-param = key [ "=" value ]
246 @endcode
247
248 @par Specification
249 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
250 >3.4. Query</a>
251 */
252 params_view(
253 core::string_view s,
254 encoding_opts opt);
255
256 /** Assignment
257
258 After assignment, both views reference
259 the same underlying character buffer.
260
261 Ownership is not transferred; the caller
262 is responsible for ensuring the lifetime
263 of the buffer extends until it is no
264 longer referenced.
265
266 @par Postconditions
267 @code
268 this->buffer().data() == other.buffer().data()
269 @endcode
270
271 @par Complexity
272 Constant
273
274 @par Exception Safety
275 Throws nothing
276
277 @param other The object to assign
278 @return A reference to this object
279 */
280 params_view&
281 operator=(
282 params_view const& other) = default;
283 };
284
285 } // urls
286 } // boost
287
288 //------------------------------------------------
289 //
290 // std::ranges::enable_borrowed_range
291 //
292 //------------------------------------------------
293
294 #ifdef BOOST_URL_HAS_CONCEPTS
295 #include <ranges>
296 namespace std::ranges {
297 template<>
298 inline constexpr bool
299 enable_borrowed_range<
300 boost::urls::params_view> = true;
301 } // std::ranges
302 #endif
303
304 #endif
305