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

libs/url/include/boost/url/params_view.hpp

100.0% Lines (1/1) 100.0% Functions (1/1) -% Branches (0/0)
libs/url/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 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 BOOST_URL_DECL
187 params_view(
188 core::string_view s);
189
190 /** Constructor
191
192 This function constructs params from
193 a valid query parameter string, which
194 can contain percent escapes.
195
196 This instance will use the specified
197 @ref encoding_opts when the values
198 are decoded.
199
200 Unlike the parameters in URLs, the string
201 passed here should not start with "?".
202 Upon construction, the view will
203 reference the character buffer pointed
204 to by `s`. The caller is responsible
205 for ensuring that the lifetime of the
206 buffer extends until it is no longer
207 referenced.
208
209 @par Example
210 @code
211 encoding_opts opt;
212 opt.space_as_plus = true;
213 params_view qp( "name=John+Doe", opt );
214 @endcode
215
216 @par Effects
217 @code
218 return params_view(parse_query( s ).value(), opt);
219 @endcode
220
221 @par Postconditions
222 @code
223 this->buffer().data() == s.data()
224 @endcode
225
226 @par Complexity
227 Linear in `s`.
228
229 @par Exception Safety
230 Exceptions thrown on invalid input.
231
232 @throw system_error
233 `s` contains an invalid query parameter
234 string.
235
236 @param s The string to parse.
237
238 @param opt The options for decoding. If
239 this parameter is omitted, `space_as_plus`
240 is used.
241
242 @par BNF
243 @code
244 query-params = [ query-param ] *( "&" query-param )
245
246 query-param = key [ "=" value ]
247 @endcode
248
249 @par Specification
250 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
251 >3.4. Query</a>
252 */
253 BOOST_URL_DECL
254 params_view(
255 core::string_view s,
256 encoding_opts opt);
257
258 /** Assignment
259
260 After assignment, both views reference
261 the same underlying character buffer.
262
263 Ownership is not transferred; the caller
264 is responsible for ensuring the lifetime
265 of the buffer extends until it is no
266 longer referenced.
267
268 @par Postconditions
269 @code
270 this->buffer().data() == other.buffer().data()
271 @endcode
272
273 @par Complexity
274 Constant
275
276 @par Exception Safety
277 Throws nothing
278
279 @param other The object to assign
280 @return A reference to this object
281 */
282 params_view&
283 operator=(
284 params_view const& other) = default;
285 };
286
287 } // urls
288 } // boost
289
290 //------------------------------------------------
291 //
292 // std::ranges::enable_borrowed_range
293 //
294 //------------------------------------------------
295
296 #ifdef BOOST_URL_HAS_CONCEPTS
297 #include <ranges>
298 namespace std::ranges {
299 template<>
300 inline constexpr bool
301 enable_borrowed_range<
302 boost::urls::params_view> = true;
303 } // std::ranges
304 #endif
305
306 #endif
307