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