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