EIC code displayed by LXR |
|
|
|
|||
Warning, file /include/boost/url/segments_ref.hpp was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).
0001 // 0002 // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com) 0003 // Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com) 0004 // 0005 // Distributed under the Boost Software License, Version 1.0. (See accompanying 0006 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 0007 // 0008 // Official repository: https://github.com/boostorg/url 0009 // 0010 0011 #ifndef BOOST_URL_SEGMENTS_REF_HPP 0012 #define BOOST_URL_SEGMENTS_REF_HPP 0013 0014 #include <boost/url/detail/config.hpp> 0015 #include <boost/url/segments_base.hpp> 0016 #include <initializer_list> 0017 #include <iterator> 0018 0019 namespace boost { 0020 namespace urls { 0021 0022 #ifndef BOOST_URL_DOCS 0023 class url_base; 0024 class segments_view; 0025 #endif 0026 0027 /** A view representing path segments in a URL 0028 0029 Objects of this type are used to interpret 0030 the path as a bidirectional view of segments, 0031 where each segment is a string with percent 0032 escapes automatically decoded. 0033 0034 The view does not retain ownership of the 0035 elements and instead references the original 0036 character buffer. The caller is responsible 0037 for ensuring that the lifetime of the buffer 0038 extends until it is no longer referenced. 0039 0040 The view is modifiable; calling non-const 0041 members causes changes to the referenced 0042 url. 0043 0044 @par Example 0045 @code 0046 url u( "/path/to/file.txt" ); 0047 0048 segments_ref ps = u.segments(); 0049 @endcode 0050 0051 Percent escapes in strings returned when 0052 dereferencing iterators are automatically 0053 decoded. 0054 Reserved characters in strings supplied 0055 to modifier functions are automatically 0056 percent-escaped. 0057 0058 @par Iterator Invalidation 0059 Changes to the underlying character buffer 0060 can invalidate iterators which reference it. 0061 Modifications made through the container 0062 invalidate some or all iterators: 0063 <br> 0064 0065 @li @ref push_back : Only `end()`. 0066 0067 @li @ref assign, @ref clear, 0068 @ref operator= : All elements. 0069 0070 @li @ref erase : Erased elements and all 0071 elements after (including `end()`). 0072 0073 @li @ref insert : All elements at or after 0074 the insertion point (including `end()`). 0075 0076 @li @ref replace : Modified 0077 elements and all elements 0078 after (including `end()`). 0079 0080 @see 0081 @ref segments_encoded_ref, 0082 @ref segments_encoded_view, 0083 @ref segments_view. 0084 */ 0085 class segments_ref 0086 : public segments_base 0087 { 0088 url_base* u_ = nullptr; 0089 0090 friend class url_base; 0091 friend class segments_encoded_ref; 0092 0093 segments_ref(url_base& u) noexcept; 0094 0095 public: 0096 //-------------------------------------------- 0097 // 0098 // Special Members 0099 // 0100 //-------------------------------------------- 0101 0102 /** Constructor 0103 0104 After construction, both views 0105 reference the same url. Ownership is not 0106 transferred; the caller is responsible 0107 for ensuring the lifetime of the url 0108 extends until it is no longer 0109 referenced. 0110 0111 @par Postconditions 0112 @code 0113 &this->url() == &other.url(); 0114 @endcode 0115 0116 @par Complexity 0117 Constant. 0118 0119 @par Exception Safety 0120 Throws nothing. 0121 0122 @param other The other view. 0123 */ 0124 segments_ref( 0125 segments_ref const& other) = default; 0126 0127 /** Assignment 0128 0129 The existing contents are replaced 0130 by a copy of the other segments. 0131 0132 <br> 0133 All iterators are invalidated. 0134 0135 @note 0136 None of the character buffers referenced 0137 by `other` may overlap the buffer of the 0138 underlying url, or else the behavior 0139 is undefined. 0140 0141 @par Effects 0142 @code 0143 this->assign( other.begin(), other.end() ); 0144 @endcode 0145 0146 @par Complexity 0147 Linear in `other.buffer().size()`. 0148 0149 @par Exception Safety 0150 Strong guarantee. 0151 Calls to allocate may throw. 0152 0153 @param other The segments to assign. 0154 @return A reference to this object. 0155 */ 0156 BOOST_URL_DECL 0157 segments_ref& 0158 operator=(segments_ref const& other); 0159 0160 /// @copydoc segments_ref::operator=(segments_ref const&) 0161 BOOST_URL_DECL 0162 segments_ref& 0163 operator=(segments_view const& other); 0164 0165 /** Assignment 0166 0167 The existing contents are replaced 0168 by a copy of the contents of the 0169 initializer list. 0170 Reserved characters in the list are 0171 automatically escaped. 0172 0173 <br> 0174 All iterators are invalidated. 0175 0176 @par Example 0177 @code 0178 url u; 0179 0180 u.segments() = { "path", "to", "file.txt" }; 0181 @endcode 0182 0183 @par Preconditions 0184 None of the character buffers referenced 0185 by the list may overlap the character 0186 buffer of the underlying url, or else 0187 the behavior is undefined. 0188 0189 @par Effects 0190 @code 0191 this->assign( init.begin(), init.end() ); 0192 @endcode 0193 0194 @par Complexity 0195 Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`. 0196 0197 @par Exception Safety 0198 Strong guarantee. 0199 Calls to allocate may throw. 0200 0201 @param init The list of segments to assign. 0202 @return A reference to this object. 0203 */ 0204 BOOST_URL_DECL 0205 segments_ref& 0206 operator=(std::initializer_list< 0207 core::string_view> init); 0208 0209 /** Conversion 0210 0211 @see 0212 @ref segments_view. 0213 0214 @return A view of the segments. 0215 */ 0216 BOOST_URL_DECL 0217 operator 0218 segments_view() const noexcept; 0219 0220 //-------------------------------------------- 0221 // 0222 // Observers 0223 // 0224 //-------------------------------------------- 0225 0226 /** Return the referenced url 0227 0228 This function returns the url referenced 0229 by the view. 0230 0231 @par Example 0232 @code 0233 url u( "/path/to/file.txt" ); 0234 0235 assert( &u.segments().url() == &u ); 0236 @endcode 0237 0238 @par Exception Safety 0239 Throws nothing. 0240 0241 @return A reference to the url. 0242 */ 0243 url_base& 0244 url() const noexcept 0245 { 0246 return *u_; 0247 } 0248 0249 //-------------------------------------------- 0250 // 0251 // Modifiers 0252 // 0253 //-------------------------------------------- 0254 0255 /** Clear the contents of the container 0256 0257 <br> 0258 All iterators are invalidated. 0259 0260 @par Effects 0261 @code 0262 this->url().set_encoded_path( "" ); 0263 @endcode 0264 0265 @par Postconditions 0266 @code 0267 this->empty() == true 0268 @endcode 0269 0270 @par Complexity 0271 Linear in `this->url().encoded_query().size() + this->url().encoded_fragment().size()`. 0272 0273 @par Exception Safety 0274 Throws nothing. 0275 */ 0276 void 0277 clear() noexcept; 0278 0279 /** Assign segments 0280 0281 The existing contents are replaced 0282 by a copy of the contents of the 0283 initializer list. 0284 Reserved characters in the list are 0285 automatically escaped. 0286 0287 <br> 0288 All iterators are invalidated. 0289 0290 @note 0291 None of the character buffers referenced 0292 by `init` may overlap the character buffer 0293 of the underlying url, or else the behavior 0294 is undefined. 0295 0296 @par Example 0297 @code 0298 url u; 0299 0300 u.segments().assign( { "path", "to", "file.txt" } ); 0301 @endcode 0302 0303 @par Complexity 0304 Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`. 0305 0306 @par Exception Safety 0307 Strong guarantee. 0308 Calls to allocate may throw. 0309 0310 @param init The list of segments to assign. 0311 */ 0312 BOOST_URL_DECL 0313 void 0314 assign(std::initializer_list< 0315 core::string_view> init); 0316 0317 /** Assign segments 0318 0319 The existing contents are replaced 0320 by a copy of the contents of the range. 0321 Reserved characters in the range are 0322 automatically escaped. 0323 0324 <br> 0325 All iterators are invalidated. 0326 0327 @note 0328 None of the character buffers referenced 0329 by the range may overlap the character 0330 buffer of the underlying url, or else 0331 the behavior is undefined. 0332 0333 @par Mandates 0334 @code 0335 std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::string_view >::value == true 0336 @endcode 0337 0338 @par Complexity 0339 Linear in `std::distance( first, last ) + this->url().encoded_query().size() + this->url().encoded_fragment().size()`. 0340 0341 @par Exception Safety 0342 Strong guarantee. 0343 Calls to allocate may throw. 0344 0345 @param first The beginning of the range of segments to assign. 0346 @param last The end of the range of segments to assign. 0347 */ 0348 template<class FwdIt> 0349 void 0350 assign(FwdIt first, FwdIt last); 0351 0352 //-------------------------------------------- 0353 0354 /** Insert segments 0355 0356 This function inserts a segment 0357 before the specified position. 0358 Reserved characters in the segment are 0359 automatically escaped. 0360 0361 <br> 0362 All iterators that are equal to 0363 `before` or come after are invalidated. 0364 0365 @par Complexity 0366 Linear in `s.size() + this->url().encoded_resource().size()`. 0367 0368 @par Exception Safety 0369 Strong guarantee. 0370 Calls to allocate may throw. 0371 0372 @return An iterator to the inserted 0373 segment. 0374 0375 @param before An iterator before which 0376 the segment is inserted. This may 0377 be equal to `end()`. 0378 0379 @param s The segment to insert. 0380 */ 0381 BOOST_URL_DECL 0382 iterator 0383 insert( 0384 iterator before, 0385 core::string_view s); 0386 0387 /** Insert segments 0388 0389 This function inserts the segments 0390 in an initializer list before the 0391 specified position. 0392 Reserved characters in the list are 0393 percent-escaped in the result. 0394 0395 <br> 0396 All iterators that are equal to 0397 `before` or come after are invalidated. 0398 0399 @note 0400 None of the character buffers referenced 0401 by the list may overlap the character 0402 buffer of the underlying url, or else 0403 the behavior is undefined. 0404 0405 @par Example 0406 @code 0407 url u( "/file.txt" ); 0408 0409 u.segments().insert( u.segments().begin(), { "path", "to" } ); 0410 @endcode 0411 0412 @par Complexity 0413 Linear in `init.size() + this->url().encoded_resource().size()`. 0414 0415 @par Exception Safety 0416 Strong guarantee. 0417 Calls to allocate may throw. 0418 0419 @return An iterator to the first 0420 element inserted, or `before` if 0421 `init.size() == 0`. 0422 0423 @param before An iterator before which 0424 the list is inserted. This may 0425 be equal to `end()`. 0426 0427 @param init The list of segments to insert. 0428 */ 0429 BOOST_URL_DECL 0430 iterator 0431 insert( 0432 iterator before, 0433 std::initializer_list<core::string_view> init); 0434 0435 /** Insert segments 0436 0437 This function inserts the segments in 0438 a range before the specified position. 0439 Reserved characters in the list are 0440 automatically escaped. 0441 0442 <br> 0443 All iterators that are equal to 0444 `before` or come after are invalidated. 0445 0446 @note 0447 None of the character buffers referenced 0448 by the range may overlap the character 0449 buffer of the underlying url, or else 0450 the behavior is undefined. 0451 0452 @par Mandates 0453 @code 0454 std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::string_view >::value == true 0455 @endcode 0456 0457 @par Complexity 0458 Linear in `std::distance( first, last ) + this->url().encoded_resource().size()`. 0459 0460 @par Exception Safety 0461 Strong guarantee. 0462 Calls to allocate may throw. 0463 0464 @return An iterator to the first 0465 segment inserted, or `before` if 0466 `init.empty()`. 0467 0468 @param before An iterator before which 0469 the range is inserted. This may 0470 be equal to `end()`. 0471 0472 @param first The beginning of the range of segments to insert. 0473 @param last The end of the range of segments to insert. 0474 */ 0475 template<class FwdIt> 0476 iterator 0477 insert( 0478 iterator before, 0479 FwdIt first, 0480 FwdIt last); 0481 0482 //-------------------------------------------- 0483 0484 /** Erase segments 0485 0486 This function removes a segment. 0487 0488 <br> 0489 All iterators that are equal to 0490 `pos` or come after are invalidated. 0491 0492 @par Complexity 0493 Linear in `this->url().encoded_resource().size()`. 0494 0495 @par Exception Safety 0496 Throws nothing. 0497 0498 @return An iterator to one past 0499 the removed segment. 0500 0501 @param pos An iterator to the segment. 0502 */ 0503 iterator 0504 erase( 0505 iterator pos) noexcept; 0506 0507 /** Erase segments 0508 0509 This function removes a range of segments. 0510 0511 <br> 0512 All iterators that are equal to 0513 `first` or come after are invalidated. 0514 0515 @par Complexity 0516 Linear in `this->url().encoded_resource().size()`. 0517 0518 @par Exception Safety 0519 Throws nothing. 0520 0521 @return An iterator to one past 0522 the removed range. 0523 0524 @param first The beginning of the range to remove. 0525 @param last The end of the range to remove. 0526 */ 0527 BOOST_URL_DECL 0528 iterator 0529 erase( 0530 iterator first, 0531 iterator last) noexcept; 0532 0533 //-------------------------------------------- 0534 0535 /** Replace segments 0536 0537 This function replaces the segment at 0538 the specified position. 0539 Reserved characters in the string are 0540 automatically escaped. 0541 0542 <br> 0543 All iterators that are equal to 0544 `pos` or come after are invalidated. 0545 0546 @par Complexity 0547 Linear in `s.size() + this->url().encoded_resouce().size()`. 0548 0549 @par Exception Safety 0550 Strong guarantee. 0551 Calls to allocate may throw. 0552 0553 @return An iterator to the replaced segment. 0554 0555 @param pos An iterator to the segment. 0556 0557 @param s The string to assign. 0558 */ 0559 BOOST_URL_DECL 0560 iterator 0561 replace( 0562 iterator pos, 0563 core::string_view s); 0564 0565 /** Replace segments 0566 0567 This function replaces a range of 0568 segments with one segment. 0569 Reserved characters in the string are 0570 automatically escaped. 0571 0572 <br> 0573 All iterators that are equal to 0574 `from` or come after are invalidated. 0575 0576 @par Complexity 0577 Linear in `s.size() + this->url().encoded_resouce().size()`. 0578 0579 @par Exception Safety 0580 Strong guarantee. 0581 Calls to allocate may throw. 0582 0583 @return An iterator to the new segment. 0584 0585 @param from The beginning of the range of segments to replace. 0586 @param to The end of the range of segments to replace. 0587 0588 @param s The string to assign. 0589 */ 0590 BOOST_URL_DECL 0591 iterator 0592 replace( 0593 iterator from, 0594 iterator to, 0595 core::string_view s); 0596 0597 /** Replace segments 0598 0599 This function replaces a range of 0600 segments with a list of segments in 0601 an initializer list. 0602 Reserved characters in the list are 0603 automatically escaped. 0604 0605 <br> 0606 All iterators that are equal to 0607 `from` or come after are invalidated. 0608 0609 @par Preconditions 0610 None of the character buffers referenced 0611 by the list may overlap the character 0612 buffer of the underlying url, or else 0613 the behavior is undefined. 0614 0615 @par Complexity 0616 Linear in `init.size() + this->url().encoded_resouce().size()`. 0617 0618 @par Exception Safety 0619 Strong guarantee. 0620 Calls to allocate may throw. 0621 0622 @return An iterator to the first 0623 segment inserted, or one past `to` if 0624 `init.size() == 0`. 0625 0626 @param from The beginning of the range of segments to replace. 0627 @param to The end of the range of segments to replace. 0628 0629 @param init The list of segments to assign. 0630 */ 0631 BOOST_URL_DECL 0632 iterator 0633 replace( 0634 iterator from, 0635 iterator to, 0636 std::initializer_list< 0637 core::string_view> init); 0638 0639 /** Replace segments 0640 0641 This function replaces a range of 0642 segments with annother range of segments. 0643 Reserved characters in the new range are 0644 automatically escaped. 0645 0646 <br> 0647 All iterators that are equal to 0648 `from` or come after are invalidated. 0649 0650 @par Preconditions 0651 None of the character buffers referenced 0652 by the new range may overlap the character 0653 buffer of the underlying url, or else 0654 the behavior is undefined. 0655 0656 @par Complexity 0657 Linear in `std::distance( first, last ) + this->url().encoded_resouce().size()`. 0658 0659 @par Exception Safety 0660 Strong guarantee. 0661 Calls to allocate may throw. 0662 0663 @return An iterator to the first 0664 segment inserted, or one past `to` if 0665 `init.size() == 0`. 0666 0667 @param from The beginning of the range of segments to replace. 0668 @param to The end of the range of segments to replace. 0669 @param first The beginning of the range of segments to assign. 0670 @param last The end of the range of segments to assign. 0671 */ 0672 template<class FwdIt> 0673 iterator 0674 replace( 0675 iterator from, 0676 iterator to, 0677 FwdIt first, 0678 FwdIt last); 0679 0680 /** Append a segment 0681 0682 This function appends a segment to 0683 the end of the path. 0684 Reserved characters in the string are 0685 automatically escaped. 0686 0687 <br> 0688 All end iterators are invalidated. 0689 0690 @par Postconditions 0691 @code 0692 this->back() == s 0693 @endcode 0694 0695 @par Exception Safety 0696 Strong guarantee. 0697 Calls to allocate may throw. 0698 0699 @param s The segment to append. 0700 */ 0701 void 0702 push_back( 0703 core::string_view s); 0704 0705 /** Remove the last segment 0706 0707 This function removes the last segment 0708 from the container. 0709 0710 <br> 0711 Iterators to the last segment as well 0712 as all end iterators are invalidated. 0713 0714 @par Preconditions 0715 @code 0716 not this->empty() 0717 @endcode 0718 0719 @par Exception Safety 0720 Throws nothing. 0721 */ 0722 void 0723 pop_back() noexcept; 0724 0725 private: 0726 template<class FwdIt> 0727 iterator 0728 insert( 0729 iterator before, 0730 FwdIt first, 0731 FwdIt last, 0732 std::input_iterator_tag) = delete; 0733 0734 template<class FwdIt> 0735 iterator 0736 insert( 0737 iterator before, 0738 FwdIt first, 0739 FwdIt last, 0740 std::forward_iterator_tag); 0741 }; 0742 0743 } // urls 0744 } // boost 0745 0746 // This include is at the bottom of 0747 // url_base.hpp because of a circular dependency 0748 // 0749 // #include <boost/url/impl/segments_ref.hpp> 0750 0751 #endif
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|