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

libs/url/include/boost/url/segments_encoded_ref.hpp

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