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