Root/libs / url / include / boost / url / params_ref.hpp
Prev Index Next

libs/url/include/boost/url/params_ref.hpp

100.0% Lines (2/2) 100.0% Functions (1/1) -% Branches (0/0)
libs/url/include/boost/url/params_ref.hpp
Line Hits 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_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