GCC Code Coverage Report

Line	Branch	Exec	Source
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
287