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 : params_view(
104 : params_view const& other) = default;
105 :
106 : /** Constructor
107 :
108 : After construction both views will
109 : reference the same character buffer
110 : but this instance will use the specified
111 : @ref encoding_opts when the values
112 : are decoded.
113 :
114 : Ownership is not transferred; the caller
115 : is responsible for ensuring the lifetime
116 : of the buffer extends until it is no
117 : longer referenced.
118 :
119 : @par Postconditions
120 : @code
121 : this->buffer().data() == other.buffer().data()
122 : @endcode
123 :
124 : @par Complexity
125 : Constant.
126 :
127 : @par Exception Safety
128 : Throws nothing
129 : */
130 : params_view(
131 : params_view const& other,
132 : encoding_opts opt) noexcept;
133 :
134 : /** Constructor
135 :
136 : This function constructs params from
137 : a valid query parameter string, which
138 : can contain percent escapes. Unlike
139 : the parameters in URLs, the string
140 : passed here should not start with "?".
141 : Upon construction, the view references
142 : the character buffer pointed to by `s`.
143 : The caller is responsible for ensuring
144 : that the lifetime of the buffer extends
145 : until it is no longer referenced.
146 :
147 : @par Example
148 : @code
149 : params_view qp( "first=John&last=Doe" );
150 : @endcode
151 :
152 : @par Effects
153 : @code
154 : return parse_query( s ).value();
155 : @endcode
156 :
157 : @par Postconditions
158 : @code
159 : this->buffer().data() == s.data()
160 : @endcode
161 :
162 : @par Complexity
163 : Linear in `s`.
164 :
165 : @par Exception Safety
166 : Exceptions thrown on invalid input.
167 :
168 : @throw system_error
169 : `s` contains an invalid query parameter
170 : string.
171 :
172 : @param s The string to parse.
173 :
174 : @par BNF
175 : @code
176 : query-params = [ query-param ] *( "&" query-param )
177 :
178 : query-param = key [ "=" value ]
179 : @endcode
180 :
181 : @par Specification
182 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"
183 : >3.4. Query</a>
184 : */
185 : BOOST_URL_DECL
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 : BOOST_URL_DECL
253 : params_view(
254 : core::string_view s,
255 : encoding_opts opt);
256 :
257 : /** Assignment
258 :
259 : After assignment, both views reference
260 : the same underlying character buffer.
261 :
262 : Ownership is not transferred; the caller
263 : is responsible for ensuring the lifetime
264 : of the buffer extends until it is no
265 : longer referenced.
266 :
267 : @par Postconditions
268 : @code
269 : this->buffer().data() == other.buffer().data()
270 : @endcode
271 :
272 : @par Complexity
273 : Constant
274 :
275 : @par Exception Safety
276 : Throws nothing
277 : */
278 : params_view&
279 : operator=(
280 : params_view const&) = default;
281 : };
282 :
283 : } // urls
284 : } // boost
285 :
286 : #endif
|
