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_REF_HPP
12			#define BOOST_URL_PARAMS_REF_HPP
13
14			#include <boost/url/detail/config.hpp>
15			#include <boost/url/ignore_case.hpp>
16			#include <boost/url/params_base.hpp>
17			#include <initializer_list>
18			#include <iterator>
19
20			namespace boost {
21			namespace urls {
22
23			#ifndef BOOST_URL_DOCS
24			class url_base;
25			class params_view;
26			#endif
27
28			/** Mutable decoded query parameter proxy
29
30			This container presents the decoded query
31			parameters of a @ref url_base as a bidirectional
32			range whose modifying operations update the
33			underlying URL in-place. It references (but
34			does not own) the character buffer, so the
35			referenced URL must stay alive while the proxy
36			is used.
37
38			<br>
39
40			Percent escapes in strings returned when
41			dereferencing iterators are automatically
42			decoded.
43			Reserved characters in strings supplied
44			to modifier functions are automatically
45			percent-escaped.
46
47			@par Example
48			@code
49			url u( "?first=John&last=Doe" );
50
51			params_ref p = u.params();
52			@endcode
53
54			@par Iterator Invalidation
55			Changes to the underlying character buffer
56			can invalidate iterators which reference it.
57			Modifications made through the container
58			invalidate some or all iterators:
59			<br>
60
61			@li @ref append : Only `end()`.
62
63			@li @ref assign, @ref clear,
64			`operator=` : All elements.
65
66			@li @ref erase : Erased elements and all
67			elements after (including `end()`).
68
69			@li @ref insert : All elements at or after
70			the insertion point (including `end()`).
71
72			@li @ref replace, @ref set : Modified
73			elements and all elements
74			after (including `end()`).
75
76			@par Reads vs. writes
77			Although this is a mutable proxy, all
78			observer helpers inherited from
79			@ref params_base (such as @ref contains,
80			@ref find, and @ref get_or) operate in the
81			same way as they do on @ref params_view:
82			they perform their lookup against the
83			current contents of the referenced URL
84			without modifying it.
85			*/
86			class BOOST_URL_DECL params_ref
87			: public params_base
88			{
89			friend class url_base;
90
91			url_base* u_ = nullptr;
92
93			params_ref(
94			url_base& u,
95			encoding_opts opt) noexcept;
96
97			public:
98			//--------------------------------------------
99			//
100			// Special Members
101			//
102			//--------------------------------------------
103
104			/** Constructor
105
106			After construction, both views
107			reference the same url. Ownership is not
108			transferred; the caller is responsible
109			for ensuring the lifetime of the url
110			extends until it is no longer
111			referenced.
112
113			@par Postconditions
114			@code
115			&this->url() == &other.url()
116			@endcode
117
118			@par Complexity
119			Constant.
120
121			@par Exception Safety
122			Throws nothing.
123
124			@param other The other view.
125			*/
126			params_ref(
127			params_ref const& other) = default;
128
129			/** Constructor
130
131			After construction, both views will
132			reference the same url but this
133			instance will use the specified
134			@ref encoding_opts when the values
135			are decoded.
136
137			Ownership is not transferred; the
138			caller is responsible for ensuring
139			the lifetime of the url extends
140			until it is no longer referenced.
141
142			@par Postconditions
143			@code
144			&this->url() == &other.url()
145			@endcode
146
147			@par Complexity
148			Constant.
149
150			@par Exception Safety
151			Throws nothing.
152
153			@param other The other view.
154			@param opt The options for decoding. If
155			this parameter is omitted, `space_as_plus`
156			is used.
157
158			*/
159			params_ref(
160			params_ref const& other,
161			encoding_opts opt) noexcept;
162
163			/** Assignment
164
165			The previous contents of this are
166			replaced by the contents of `other.
167
168			<br>
169			All iterators are invalidated.
170
171			@note
172			The strings referenced by `other`
173			must not come from the underlying url,
174			or else the behavior is undefined.
175
176			@par Effects
177			@code
178			this->assign( other.begin(), other.end() );
179			@endcode
180
181			@par Complexity
182			Linear in `other.buffer().size()`.
183
184			@par Exception Safety
185			Strong guarantee.
186			Calls to allocate may throw.
187
188			@param other The params to assign.
189			@return `*this`
190			*/
191			params_ref&
192			operator=(
193			params_ref const& other);
194
195			/** Assignment
196
197			After assignment, the previous contents
198			of the query parameters are replaced by
199			the contents of the initializer-list.
200
201			@par Preconditions
202			None of character buffers referenced by
203			`init` may overlap the character buffer of
204			the underlying url, or else the behavior
205			is undefined.
206
207			@par Effects
208			@code
209			this->assign( init );
210			@endcode
211
212			@par Complexity
213			Linear in `init.size()`.
214
215			@par Exception Safety
216			Strong guarantee.
217			Calls to allocate may throw.
218
219			@param init The list of params to assign.
220			@return `*this`
221			*/
222			params_ref&
223			operator=(
224			std::initializer_list<
225			param_view> init);
226
227			/** Conversion
228
229			@return A view of the query parameters.
230			*/
231			operator
232			params_view() const noexcept;
233
234			//--------------------------------------------
235			//
236			// Observers
237			//
238			//--------------------------------------------
239
240			/** Return the referenced url
241
242			This function returns the url referenced
243			by the view.
244
245			@par Example
246			@code
247			url u( "?key=value" );
248
249			assert( &u.segments().url() == &u );
250			@endcode
251
252			@par Exception Safety
253			@code
254			Throws nothing.
255			@endcode
256
257			@return A reference to the url.
258			*/
259			url_base&
260		10	url() const noexcept
261			{
262		10	return *u_;
263			}
264
265			//--------------------------------------------
266			//
267			// Modifiers
268			//
269			//--------------------------------------------
270
271			/** Clear the contents of the container
272
273			<br>
274			All iterators are invalidated.
275
276			@par Effects
277			@code
278			this->url().remove_query();
279			@endcode
280
281			@par Postconditions
282			@code
283			this->empty() == true && this->url().has_query() == false
284			@endcode
285
286			@par Complexity
287			Constant.
288
289			@par Exception Safety
290			Throws nothing.
291			*/
292			void
293			clear() noexcept;
294
295			//--------------------------------------------
296
297			/** Assign elements
298
299			This function replaces the entire
300			contents of the view with the params
301			in the <em>initializer-list</em>.
302
303			<br>
304			All iterators are invalidated.
305
306			@note
307			The strings referenced by the inputs
308			must not come from the underlying url,
309			or else the behavior is undefined.
310
311			@par Example
312			@code
313			url u;
314
315			u.params().assign( {{ "first", "John" }, { "last", "Doe" }} );
316			@endcode
317
318			@par Complexity
319			Linear in `init.size()`.
320
321			@par Exception Safety
322			Strong guarantee.
323			Calls to allocate may throw.
324
325			@param init The list of params to assign.
326			*/
327			void
328			assign(
329			std::initializer_list<
330			param_view> init);
331
332			/** Assign elements
333
334			This function replaces the entire
335			contents of the view with the params
336			in the range.
337
338			<br>
339			All iterators are invalidated.
340
341			@note
342			The strings referenced by the inputs
343			must not come from the underlying url,
344			or else the behavior is undefined.
345
346			@par Mandates
347			@code
348			std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true
349			@endcode
350
351			@par Complexity
352			Linear in the size of the range.
353
354			@par Exception Safety
355			Strong guarantee.
356			Calls to allocate may throw.
357
358			@param first The first element to assign.
359			@param last One past the last element to assign.
360			*/
361			template<class FwdIt>
362			void
363			assign(FwdIt first, FwdIt last);
364
365			//--------------------------------------------
366
367			/** Append elements
368
369			This function appends a param to the view.
370
371			<br>
372			The `end()` iterator is invalidated.
373
374			@par Example
375			@code
376			url u;
377
378			u.params().append( { "first", "John" } );
379			@endcode
380
381			@par Complexity
382			Linear in `this->url().encoded_query().size()`.
383
384			@par Exception Safety
385			Strong guarantee.
386			Calls to allocate may throw.
387
388			@return An iterator to the new element.
389
390			@param p The param to append.
391			*/
392			iterator
393			append(
394			param_view const& p);
395
396			/** Append elements
397
398			This function appends the params in
399			an <em>initializer-list</em> to the view.
400
401			<br>
402			The `end()` iterator is invalidated.
403
404			@par Example
405			@code
406			url u;
407
408			u.params().append({ { "first", "John" }, { "last", "Doe" } });
409			@endcode
410
411			@par Complexity
412			Linear in `this->url().encoded_query().size()`.
413
414			@par Exception Safety
415			Strong guarantee.
416			Calls to allocate may throw.
417
418			@return An iterator to the first new element.
419
420			@param init The list of params to append.
421			*/
422			iterator
423			append(
424			std::initializer_list<
425			param_view> init);
426
427			/** Append elements
428
429			This function appends a range of params
430			to the view.
431
432			<br>
433			The `end()` iterator is invalidated.
434
435			@note
436			The strings referenced by the inputs
437			must not come from the underlying url,
438			or else the behavior is undefined.
439
440			@par Mandates
441			@code
442			std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true
443			@endcode
444
445			@par Complexity
446			Linear in `this->url().encoded_query().size()`.
447
448			@par Exception Safety
449			Strong guarantee.
450			Calls to allocate may throw.
451
452			@param first The first element to append.
453			@param last One past the last element to append.
454			@return An iterator to the first new element.
455			*/
456			template<class FwdIt>
457			iterator
458			append(
459			FwdIt first, FwdIt last);
460
461			//--------------------------------------------
462
463			/** Insert elements
464
465			This function inserts a param
466			before the specified position.
467
468			<br>
469			All iterators that are equal to
470			`before` or come after are invalidated.
471
472			@par Complexity
473			Linear in `this->url().encoded_query().size()`.
474
475			@par Exception Safety
476			Strong guarantee.
477			Calls to allocate may throw.
478
479			@return An iterator to the inserted
480			element.
481
482			@param before An iterator before which
483			the param is inserted. This may
484			be equal to `end()`.
485
486			@param p The param to insert.
487			*/
488			iterator
489			insert(
490			iterator before,
491			param_view const& p);
492
493			/** Insert elements
494
495			This function inserts the params in
496			an <em>initializer-list</em> before
497			the specified position.
498
499			<br>
500			All iterators that are equal to
501			`before` or come after are invalidated.
502
503			@note
504			The strings referenced by the inputs
505			must not come from the underlying url,
506			or else the behavior is undefined.
507
508			@par Complexity
509			Linear in `this->url().encoded_query().size()`.
510
511			@par Exception Safety
512			Strong guarantee.
513			Calls to allocate may throw.
514
515			@return An iterator to the first
516			element inserted, or `before` if
517			`init.size() == 0`.
518
519			@param before An iterator before which
520			the element is inserted. This may
521			be equal to `end()`.
522
523			@param init The list of params to insert.
524			*/
525			iterator
526			insert(
527			iterator before,
528			std::initializer_list<
529			param_view> init);
530
531			/** Insert elements
532
533			This function inserts a range of
534			params before the specified position.
535
536			<br>
537			All iterators that are equal to
538			`before` or come after are invalidated.
539
540			@note
541			The strings referenced by the inputs
542			must not come from the underlying url,
543			or else the behavior is undefined.
544
545			@par Mandates
546			@code
547			std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true
548			@endcode
549
550			@par Complexity
551			Linear in `this->url().encoded_query().size()`.
552
553			@par Exception Safety
554			Strong guarantee.
555			Calls to allocate may throw.
556
557			@return An iterator to the first
558			element inserted, or `before` if
559			`first == last`.
560
561			@param before An iterator before which
562			the element is inserted. This may
563			be equal to `end()`.
564			@param first The first element to insert.
565			@param last One past the last element to insert.
566			@return An iterator to the first element inserted, or `before` if `first == last`.
567			*/
568			template<class FwdIt>
569			iterator
570			insert(
571			iterator before,
572			FwdIt first,
573			FwdIt last);
574
575			//--------------------------------------------
576
577			/** Erase elements
578
579			This function removes an element from
580			the container.
581
582			<br>
583			All iterators that are equal to
584			`pos` or come after are invalidated.
585
586			@par Example
587			@code
588			url u( "?first=John&last=Doe" );
589
590			params_ref::iterator it = u.params().erase( u.params().begin() );
591
592			assert( u.encoded_query() == "last=Doe" );
593			@endcode
594
595			@par Complexity
596			Linear in `this->url().encoded_query().size()`.
597
598			@par Exception Safety
599			Throws nothing.
600
601			@return An iterator to one past
602			the removed element.
603
604			@param pos An iterator to the element.
605			*/
606			iterator
607			erase(iterator pos) noexcept;
608
609			/** Erase elements
610
611			This function removes a range of elements
612			from the container.
613
614			<br>
615			All iterators that are equal to
616			`first` or come after are invalidated.
617
618			@par Complexity
619			Linear in `this->url().encoded_query().size()`.
620
621			@par Exception Safety
622			Throws nothing.
623
624			@param first The first element to remove.
625			@param last One past the last element to remove.
626			@return An iterator to one past the removed range.
627			*/
628			iterator
629			erase(
630			iterator first,
631			iterator last) noexcept;
632
633			/** Erase elements
634
635			<br>
636			All iterators are invalidated.
637
638			@par Postconditions
639			@code
640			this->count( key, ic ) == 0
641			@endcode
642
643			@par Complexity
644			Linear in `this->url().encoded_query().size()`.
645
646			@par Exception Safety
647			Throws nothing.
648
649			@return The number of elements removed
650			from the container.
651
652			@param key The key to match.
653			By default, a case-sensitive
654			comparison is used.
655
656			@param ic An optional parameter. If
657			the value @ref ignore_case is passed
658			here, the comparison is
659			case-insensitive.
660			*/
661			std::size_t
662			erase(
663			core::string_view key,
664			ignore_case_param ic = {}) noexcept;
665
666			//--------------------------------------------
667
668			/** Replace elements
669
670			This function replaces the contents
671			of the element at `pos` with the
672			specified param.
673
674			<br>
675			All iterators that are equal to
676			`pos` or come after are invalidated.
677
678			@par Example
679			@code
680			url u( "?first=John&last=Doe" );
681
682			u.params().replace( u.params().begin(), { "title", "Mr" });
683
684			assert( u.encoded_query() == "title=Mr&last=Doe" );
685			@endcode
686
687			@par Complexity
688			Linear in `this->url().encoded_query().size()`.
689
690			@par Exception Safety
691			Strong guarantee.
692			Calls to allocate may throw.
693
694			@return An iterator to the element.
695
696			@param pos An iterator to the element.
697
698			@param p The param to assign.
699			*/
700			iterator
701			replace(
702			iterator pos,
703			param_view const& p);
704
705			/** Replace elements
706
707			This function replaces a range of
708			elements with the params in an
709			<em>initializer-list</em>.
710
711			<br>
712			All iterators that are equal to
713			`from` or come after are invalidated.
714
715			@note
716			The strings referenced by the inputs
717			must not come from the underlying url,
718			or else the behavior is undefined.
719
720			@par Complexity
721			Linear in `this->url().encoded_query().size()`.
722
723			@par Exception Safety
724			Strong guarantee.
725			Calls to allocate may throw.
726
727			@return An iterator to the first
728			element inserted, or one past `to` if
729			`init.size() == 0`.
730
731			@param from,to The range of elements
732			to replace.
733
734			@param init The list of params to assign.
735			*/
736			iterator
737			replace(
738			iterator from,
739			iterator to,
740			std::initializer_list<
741			param_view> init);
742
743			/** Replace elements
744
745			This function replaces a range of
746			elements with a range of params.
747
748			<br>
749			All iterators that are equal to
750			`from` or come after are invalidated.
751
752			@note
753			The strings referenced by the inputs
754			must not come from the underlying url,
755			or else the behavior is undefined.
756
757			@par Mandates
758			@code
759			std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true
760			@endcode
761
762			@par Complexity
763			Linear in `this->url().encoded_query().size()`.
764
765			@par Exception Safety
766			Strong guarantee.
767			Calls to allocate may throw.
768
769			@return An iterator to the first
770			element inserted, or one past `to` if
771			`first == last`.
772
773			@param from The first element to replace.
774			@param to One past the last element to replace.
775			@param first The first element to insert.
776			@param last One past the last element to insert.
777			@return An iterator to the first element inserted, or one past `to` if `first == last`.
778			*/
779			template<class FwdIt>
780			iterator
781			replace(
782			iterator from,
783			iterator to,
784			FwdIt first,
785			FwdIt last);
786
787			//--------------------------------------------
788
789			/** Remove the value on an element
790
791			This function removes the value of
792			an element at the specified position.
793			After the call returns, `has_value`
794			for the element is false.
795
796			<br>
797			All iterators that are equal to
798			`pos` or come after are invalidated.
799
800			@par Example
801			@code
802			url u( "?first=John&last=Doe" );
803
804			u.params().unset( u.params().begin() );
805
806			assert( u.encoded_query() == "first&last=Doe" );
807			@endcode
808
809			@par Complexity
810			Linear in `this->url().encoded_query().size()`.
811
812			@par Exception Safety
813			Throws nothing.
814
815			@return An iterator to the element.
816
817			@param pos An iterator to the element.
818			*/
819			iterator
820			unset(
821			iterator pos) noexcept;
822
823			/** Set a value
824
825			This function replaces the value of an
826			element at the specified position.
827
828			<br>
829			All iterators that are equal to
830			`pos` or come after are invalidated.
831
832			@par Example
833			@code
834			url u( "?id=42&id=69" );
835
836			u.params().set( u.params().begin(), "none" );
837
838			assert( u.encoded_query() == "id=none&id=69" );
839			@endcode
840
841			@par Complexity
842			Linear in `this->url().encoded_query().size()`.
843
844			@par Exception Safety
845			Strong guarantee.
846			Calls to allocate may throw.
847
848			@return An iterator to the element.
849
850			@param pos An iterator to the element.
851
852			@param value The value to assign. The
853			empty string still counts as a value.
854			That is, `has_value` for the element
855			is true.
856			*/
857			iterator
858			set(
859			iterator pos,
860			core::string_view value);
861
862			/** Set a value
863
864			This function performs one of two
865			actions depending on the value of
866			`this->contains( key, ic )`.
867
868			@li If key is contained in the view
869			then one of the matching elements has
870			its value changed to the specified value.
871			The remaining elements with a matching
872			key are erased. Otherwise,
873
874			@li If `key` is not contained in the
875			view, then the function apppends the
876			param `{ key, value }`.
877
878			<br>
879			All iterators are invalidated.
880
881			@par Example
882			@code
883			url u( "?id=42&id=69" );
884
885			u.params().set( "id", "none" );
886
887			assert( u.params().count( "id" ) == 1 );
888			@endcode
889
890			@par Postconditions
891			@code
892			this->count( key, ic ) == 1 && this->find( key, ic )->value == value
893			@endcode
894
895			@par Complexity
896			Linear in `this->url().encoded_query().size()`.
897
898			@par Exception Safety
899			Strong guarantee.
900			Calls to allocate may throw.
901
902			@return An iterator to the appended
903			or modified element.
904
905			@param key The key to match.
906			By default, a case-sensitive
907			comparison is used.
908
909			@param value The value to assign. The
910			empty string still counts as a value.
911			That is, `has_value` for the element
912			is true.
913
914			@param ic An optional parameter. If
915			the value @ref ignore_case is passed
916			here, the comparison is
917			case-insensitive.
918			*/
919			iterator
920			set(
921			core::string_view key,
922			core::string_view value,
923			ignore_case_param ic = {});
924
925			//--------------------------------------------
926
927			private:
928			template<class FwdIt>
929			void
930			assign(FwdIt first, FwdIt last,
931			std::forward_iterator_tag);
932
933			// Doxygen cannot render ` = delete`
934			template<class FwdIt>
935			void
936			assign(FwdIt first, FwdIt last,
937			std::input_iterator_tag) = delete;
938
939			template<class FwdIt>
940			iterator
941			insert(
942			iterator before,
943			FwdIt first,
944			FwdIt last,
945			std::forward_iterator_tag);
946
947			// Doxygen cannot render ` = delete`
948			template<class FwdIt>
949			iterator
950			insert(
951			iterator before,
952			FwdIt first,
953			FwdIt last,
954			std::input_iterator_tag) = delete;
955			};
956
957			} // urls
958			} // boost
959
960			// This is in <boost/url/url_base.hpp>
961			//
962			// #include <boost/url/impl/params_ref.hpp>
963
964			#endif
965