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