Index/include / boost / url / segments_encoded_ref.hpp

include/boost/url/segments_encoded_ref.hpp

100.0% Lines (2/2) 100.0% Functions (1/1)
include/boost/url/segments_encoded_ref.hpp
Prev Index Next
Line TLA 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_SEGMENTS_ENCODED_REF_HPP
12 #define BOOST_URL_SEGMENTS_ENCODED_REF_HPP
13
14 #include <boost/url/detail/config.hpp>
15 #include <boost/url/segments_encoded_base.hpp>
16 #include <initializer_list>
17 #include <iterator>
18
19 namespace boost {
20 namespace urls {
21
22 #ifndef BOOST_URL_DOCS
23 class url_base;
24 class segments_encoded_view;
25 #endif
26
27 /** Mutable encoded path segment proxy
28
29 Exposes the percent-encoded segments of a
30 @ref url_base as a bidirectional range that
31 can modify the underlying URL. The proxy uses
32 the URL’s storage directly, so the url must
33 outlive any references.
34
35 @par Example
36 @code
37 url u( "/path/to/file.txt" );
38
39 segments_encoded_ref ps = u.encoded_segments();
40 @endcode
41
42 The strings returned when iterators are
43 dereferenced have type @ref pct_string_view
44 and may contain percent-escapes.
45
46 Reserved characters in inputs are
47 automatically escaped.
48 Escapes in inputs are preserved.
49
50 Exceptions are thrown on invalid inputs.
51
52 @par Iterator Invalidation
53 Changes to the underlying character buffer
54 can invalidate iterators which reference it.
55 Modifications made through the container
56 invalidate some or all iterators:
57 <br>
58
59 @li @ref push_back : Only `end()`.
60
61 @li @ref assign, @ref clear,
62 @ref operator= : All elements.
63
64 @li @ref erase : Erased elements and all
65 elements after (including `end()`).
66
67 @li @ref insert : All elements at or after
68 the insertion point (including `end()`).
69
70 @li @ref replace : Modified
71 elements and all elements
72 after (including `end()`).
73
74 @see
75 @ref segments_encoded_view,
76 @ref segments_view,
77 @ref segments_ref.
78 */
79 class BOOST_SYMBOL_VISIBLE segments_encoded_ref
80 : public segments_encoded_base
81 {
82 friend class url_base;
83
84 url_base* u_ = nullptr;
85
86 segments_encoded_ref(
87 url_base& u) noexcept;
88
89 public:
90 //--------------------------------------------
91 //
92 // Special Members
93 //
94 //--------------------------------------------
95
96 /** Constructor
97
98 After construction, both views
99 reference the same url. Ownership is not
100 transferred; the caller is responsible
101 for ensuring the lifetime of the url
102 extends until it is no longer
103 referenced.
104
105 @par Postconditions
106 @code
107 &this->url() == &other.url();
108 @endcode
109
110 @par Complexity
111 Constant.
112
113 @par Exception Safety
114 Throws nothing.
115
116 @param other The other view.
117 */
118 segments_encoded_ref(
119 segments_encoded_ref const& other) = default;
120
121 /** Assignment
122
123 The existing contents are replaced
124 by a copy of the other segments.
125
126 <br>
127 All iterators are invalidated.
128
129 @note
130 None of the character buffers referenced
131 by `other` may overlap the buffer of the
132 underlying url, or else the behavior
133 is undefined.
134
135 @par Effects
136 @code
137 this->assign( other.begin(), other.end() );
138 @endcode
139
140 @par Complexity
141 Linear in `other.buffer().size()`.
142
143 @par Exception Safety
144 Strong guarantee.
145 Calls to allocate may throw.
146
147 @param other The segments to assign.
148 @return A reference to this object.
149 */
150 segments_encoded_ref&
151 operator=(segments_encoded_ref const& other);
152
153 /// @copydoc operator=(segments_encoded_ref const&)
154 segments_encoded_ref&
155 operator=(segments_encoded_view const& other);
156
157 /** Assignment
158
159 The existing contents are replaced
160 by a copy of the contents of the
161 initializer list.
162 Reserved characters in the list are
163 automatically escaped.
164 Escapes in the list are preserved.
165
166 <br>
167 All iterators are invalidated.
168
169 @par Example
170 @code
171 url u;
172
173 u.encoded_segments() = {"path", "to", "file.txt"};
174 @endcode
175
176 @par Preconditions
177 None of the character buffers referenced
178 by the list may overlap the character buffer
179 of the underlying url, or else the behavior
180 is undefined.
181
182 @par Effects
183 @code
184 this->assign( init.begin(), init.end() );
185 @endcode
186
187 @par Complexity
188 Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.
189
190 @par Exception Safety
191 Strong guarantee.
192 Calls to allocate may throw.
193 Exceptions thrown on invalid input.
194
195 @throw system_error
196 The list contains an invalid percent-encoding.
197
198 @param init The list of segments to assign.
199 @return A reference to this.
200 */
201 segments_encoded_ref&
202 operator=(std::initializer_list<
203 pct_string_view> init);
204
205 /** Conversion
206
207 @see
208 @ref segments_encoded_view.
209
210 @return A view of the segments.
211 */
212 operator
213 segments_encoded_view() const noexcept;
214
215 //--------------------------------------------
216 //
217 // Observers
218 //
219 //--------------------------------------------
220
221 /** Return the referenced url
222
223 This function returns the url referenced
224 by the view.
225
226 @par Example
227 @code
228 url u( "/path/to/file.txt" );
229
230 assert( &u.encoded_segments().url() == &u );
231 @endcode
232
233 @par Exception Safety
234 Throws nothing.
235
236 @return A reference to the url.
237 */
238 url_base&
239 9 url() const noexcept
240 {
241 9 return *u_;
242 }
243
244 //--------------------------------------------
245 //
246 // Modifiers
247 //
248 //--------------------------------------------
249
250 /** Clear the contents of the container
251
252 <br>
253 All iterators are invalidated.
254
255 @par Effects
256 @code
257 this->url().set_encoded_path( "" );
258 @endcode
259
260 @par Postconditions
261 @code
262 this->empty() == true
263 @endcode
264
265 @par Complexity
266 Linear in `this->url().encoded_query().size() + this->url().encoded_fragment().size()`.
267
268 @par Exception Safety
269 Throws nothing.
270 */
271 void
272 clear() noexcept;
273
274 /** Assign segments
275
276 The existing contents are replaced
277 by a copy of the contents of the
278 initializer list.
279 Reserved characters in the list are
280 automatically escaped.
281 Escapes in the list are preserved.
282
283 <br>
284 All iterators are invalidated.
285
286 @note
287 None of the character buffers referenced
288 by the list may overlap the character
289 buffer of the underlying url, or else
290 the behavior is undefined.
291
292 @par Example
293 @code
294 url u;
295
296 u.segments().assign( {"path", "to", "file.txt"} );
297 @endcode
298
299 @par Complexity
300 Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.
301
302 @par Exception Safety
303 Strong guarantee.
304 Calls to allocate may throw.
305 Exceptions thrown on invalid input.
306
307 @throw system_error
308 The list contains an invalid percent-encoding.
309
310 @param init The list of segments to assign.
311 */
312 void
313 assign(std::initializer_list<
314 pct_string_view> init);
315
316 /** Assign segments
317
318 The existing contents are replaced
319 by a copy of the contents of the range.
320 Reserved characters in the range are
321 automatically escaped.
322 Escapes in the range are preserved.
323
324 <br>
325 All iterators are invalidated.
326
327 @note
328 None of the character buffers referenced
329 by the range may overlap the character
330 buffer of the underlying url, or else
331 the behavior is undefined.
332
333 @par Mandates
334 @code
335 std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true
336 @endcode
337
338 @par Complexity
339 Linear in `std::distance( first, last ) + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.
340
341 @par Exception Safety
342 Strong guarantee.
343 Calls to allocate may throw.
344 Exceptions thrown on invalid input.
345
346 @throw system_error
347 The range contains an invalid percent-encoding.
348
349 @param first The first element in the range.
350 @param last One past the last element in the range.
351 */
352 template<class FwdIt>
353 void
354 assign(FwdIt first, FwdIt last);
355
356 //--------------------------------------------
357
358 /** Insert segments
359
360 This function inserts a segment
361 before the specified position.
362 Reserved characters in the segment are
363 automatically escaped.
364 Escapes in the segment are preserved.
365
366 <br>
367 All iterators that are equal to
368 `before` or come after are invalidated.
369
370 @par Complexity
371 Linear in `s.size() + this->url().encoded_resource().size()`.
372
373 @par Exception Safety
374 Strong guarantee.
375 Calls to allocate may throw.
376 Exceptions thrown on invalid input.
377
378 @throw system_error
379 The segment contains an invalid percent-encoding.
380
381 @return An iterator to the inserted
382 segment.
383
384 @param before An iterator before which
385 the segment is inserted. This may
386 be equal to `end()`.
387
388 @param s The segment to insert.
389 */
390 iterator
391 insert(
392 iterator before,
393 pct_string_view s);
394
395 /** Insert segments
396
397 This function inserts the segments
398 in an initializer list before the
399 specified position.
400 Reserved characters in the list are
401 automatically escaped.
402 Escapes in the list are preserved.
403
404 <br>
405 All iterators that are equal to
406 `before` or come after are invalidated.
407
408 @note
409 None of the character buffers referenced
410 by the list may overlap the character
411 buffer of the underlying url, or else
412 the behavior is undefined.
413
414 @par Example
415 @code
416 url u( "/file.txt" );
417
418 u.encoded_segments().insert( u.encoded_segments().begin(), { "path", "to" } );
419 @endcode
420
421 @par Complexity
422 Linear in `init.size() + this->url().encoded_resource().size()`.
423
424 @par Exception Safety
425 Strong guarantee.
426 Calls to allocate may throw.
427 Exceptions thrown on invalid input.
428
429 @throw system_error
430 The list contains an invalid percent-encoding.
431
432 @return An iterator to the first
433 element inserted, or `before` if
434 `init.size() == 0`.
435
436 @param before An iterator before which
437 the list is inserted. This may
438 be equal to `end()`.
439
440 @param init The list of segments to insert.
441 */
442 iterator
443 insert(
444 iterator before,
445 std::initializer_list<
446 pct_string_view> init);
447
448 /** Insert segments
449
450 This function inserts the segments in
451 a range before the specified position.
452 Reserved characters in the range are
453 automatically escaped.
454 Escapes in the range are preserved.
455
456 <br>
457 All iterators that are equal to
458 `before` or come after are invalidated.
459
460 @note
461 None of the character buffers referenced
462 by the range may overlap the character
463 buffer of the underlying url, or else
464 the behavior is undefined.
465
466 @par Mandates
467 @code
468 std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true
469 @endcode
470
471 @par Complexity
472 Linear in `std::distance( first, last ) + this->url().encoded_resource().size()`.
473
474 @par Exception Safety
475 Strong guarantee.
476 Calls to allocate may throw.
477 Exceptions thrown on invalid input.
478
479 @throw system_error
480 The range contains an invalid percent-encoding.
481
482 @return An iterator to the first
483 segment inserted, or `before` if
484 `init.empty()`.
485
486 @param before An iterator before which
487 the range is inserted. This may
488 be equal to `end()`.
489
490 @param first The first element in the range to insert.
491 @param last One past the last element in the range to insert.
492 */
493 template<class FwdIt>
494 iterator
495 insert(
496 iterator before,
497 FwdIt first,
498 FwdIt last);
499
500 //--------------------------------------------
501
502 /** Erase segments
503
504 This function removes a segment.
505
506 <br>
507 All iterators that are equal to
508 `pos` or come after are invalidated.
509
510 @par Complexity
511 Linear in `this->url().encoded_resource().size()`.
512
513 @par Exception Safety
514 Throws nothing.
515
516 @return An iterator to one past
517 the removed segment.
518
519 @param pos An iterator to the element.
520 */
521 iterator
522 erase(
523 iterator pos) noexcept;
524
525 /** Erase segments
526
527 This function removes a range of segments
528 from the container.
529
530 <br>
531 All iterators that are equal to
532 `first` or come after are invalidated.
533
534 @par Complexity
535 Linear in `this->url().encoded_resource().size()`.
536
537 @par Exception Safety
538 Throws nothing.
539
540 @param first The first element in the range to erase.
541 @param last One past the last element in the range to erase.
542 @return An iterator to one past the removed range.
543 */
544 iterator
545 erase(
546 iterator first,
547 iterator last) noexcept;
548
549 //--------------------------------------------
550
551 /** Replace segments
552
553 This function replaces the segment at
554 the specified position.
555 Reserved characters in the string are
556 automatically escaped.
557 Escapes in the string are preserved.
558
559 <br>
560 All iterators that are equal to
561 `pos` or come after are invalidated.
562
563 @par Complexity
564 Linear in `s.size() + this->url().encoded_resouce().size()`.
565
566 @par Exception Safety
567 Strong guarantee.
568 Calls to allocate may throw.
569
570 @return An iterator to the replaced segment.
571
572 @param pos An iterator to the segment.
573
574 @param s The string to assign.
575 */
576 iterator
577 replace(
578 iterator pos,
579 pct_string_view s);
580
581 /** Replace segments
582
583 This function replaces a range of
584 segments with one segment.
585 Reserved characters in the string are
586 automatically escaped.
587 Escapes in the string are preserved.
588
589 <br>
590 All iterators that are equal to
591 `from` or come after are invalidated.
592
593 @par Complexity
594 Linear in `s.size() + this->url().encoded_resouce().size()`.
595
596 @par Exception Safety
597 Strong guarantee.
598 Calls to allocate may throw.
599 Exceptions thrown on invalid input.
600
601 @throw system_error
602 The string contains an invalid percent-encoding.
603
604 @return An iterator to the new segment.
605
606 @param from The first element in the range of segments to replace.
607 @param to One past the last element in the range of segments to replace.
608
609 @param s The string to assign.
610 */
611 iterator
612 replace(
613 iterator from,
614 iterator to,
615 pct_string_view s);
616
617 /** Replace segments
618
619 This function replaces a range of
620 segments with a list of segments in
621 an initializer list.
622 Reserved characters in the list are
623 automatically escaped.
624 Escapes in the list are preserved.
625
626 <br>
627 All iterators that are equal to
628 `from` or come after are invalidated.
629
630 @par Preconditions
631 None of the character buffers referenced
632 by the list may overlap the character
633 buffer of the underlying url, or else
634 the behavior is undefined.
635
636 @par Complexity
637 Linear in `init.size() + this->url().encoded_resouce().size()`.
638
639 @par Exception Safety
640 Strong guarantee.
641 Calls to allocate may throw.
642 Exceptions thrown on invalid input.
643
644 @throw system_error
645 The list contains an invalid percent-encoding.
646
647 @return An iterator to the first
648 segment inserted, or one past `to` if
649 `init.size() == 0`.
650
651 @param from The first element in the range of segments to replace.
652 @param to One past the last element in the range of segments to replace.
653
654 @param init The list of segments to assign.
655 */
656 iterator
657 replace(
658 iterator from,
659 iterator to,
660 std::initializer_list<
661 pct_string_view> init);
662
663 /** Replace segments
664
665 This function replaces a range of
666 segments with annother range of segments.
667 Reserved characters in the new range are
668 automatically escaped.
669 Escapes in the new range are preserved.
670
671 <br>
672 All iterators that are equal to
673 `from` or come after are invalidated.
674
675 @par Preconditions
676 None of the character buffers referenced
677 by the new range may overlap the character
678 buffer of the underlying url, or else
679 the behavior is undefined.
680
681 @par Complexity
682 Linear in `std::distance( first, last ) + this->url().encoded_resouce().size()`.
683
684 @par Exception Safety
685 Strong guarantee.
686 Calls to allocate may throw.
687 Exceptions thrown on invalid input.
688
689 @throw system_error
690 The range contains an invalid percent-encoding.
691
692 @return An iterator to the first
693 segment inserted, or one past `to` if
694 `init.size() == 0`.
695
696 @param from The first element in the range of segments to replace.
697 @param to One past the last element in the range of segments to replace.
698 @param first The first element in the new range of segments.
699 @param last One past the last element in the new range of segments.
700 */
701 template<class FwdIt>
702 iterator
703 replace(
704 iterator from,
705 iterator to,
706 FwdIt first,
707 FwdIt last);
708
709 //--------------------------------------------
710
711 /** Append a segment
712
713 This function appends a segment to
714 the end of the path.
715 Reserved characters in the string are
716 automatically escaped.
717 Escapes in the string are preserved.
718
719 <br>
720 All end iterators are invalidated.
721
722 @par Postconditions
723 @code
724 this->back() == s
725 @endcode
726
727 @par Exception Safety
728 Strong guarantee.
729 Calls to allocate may throw.
730 Exceptions thrown on invalid input.
731
732 @throw system_error
733 The string contains an invalid percent-encoding.
734
735 @param s The segment to append.
736 */
737 void
738 push_back(
739 pct_string_view s);
740
741 /** Remove the last segment
742
743 This function removes the last segment
744 from the container.
745
746 <br>
747 Iterators to the last segment as well
748 as all end iterators are invalidated.
749
750 @par Preconditions
751 @code
752 !this->empty()
753 @endcode
754
755 @par Exception Safety
756 Throws nothing.
757 */
758 void
759 pop_back() noexcept;
760
761 private:
762 template<class FwdIt>
763 iterator
764 insert(
765 iterator before,
766 FwdIt first,
767 FwdIt last,
768 std::input_iterator_tag) = delete;
769
770 template<class FwdIt>
771 iterator
772 insert(
773 iterator before,
774 FwdIt first,
775 FwdIt last,
776 std::forward_iterator_tag);
777 };
778
779 } // urls
780 } // boost
781
782 // This is in <boost/url/url_base.hpp>
783 //
784 // #include <boost/url/impl/segments_encoded_ref.hpp>
785
786 //------------------------------------------------
787 //
788 // std::ranges::enable_borrowed_range
789 //
790 //------------------------------------------------
791
792 #ifdef BOOST_URL_HAS_CONCEPTS
793 #include <ranges>
794 namespace std::ranges {
795 template<>
796 inline constexpr bool
797 enable_borrowed_range<
798 boost::urls::segments_encoded_ref> = true;
799 } // std::ranges
800 #endif
801
802 #endif
803