Line data 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
|
