EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-01-18 09:53:29
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 */ 0155 /** @{ */ 0156 BOOST_URL_DECL 0157 segments_ref& 0158 operator=(segments_ref const& other); 0159 0160 BOOST_URL_DECL 0161 segments_ref& 0162 operator=(segments_view const& other); 0163 /** @} */ 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 */ 0203 BOOST_URL_DECL 0204 segments_ref& 0205 operator=(std::initializer_list< 0206 core::string_view> init); 0207 0208 /** Conversion 0209 0210 @see 0211 @ref segments_view. 0212 */ 0213 BOOST_URL_DECL 0214 operator 0215 segments_view() const noexcept; 0216 0217 //-------------------------------------------- 0218 // 0219 // Observers 0220 // 0221 //-------------------------------------------- 0222 0223 /** Return the referenced url 0224 0225 This function returns the url referenced 0226 by the view. 0227 0228 @par Example 0229 @code 0230 url u( "/path/to/file.txt" ); 0231 0232 assert( &u.segments().url() == &u ); 0233 @endcode 0234 0235 @par Exception Safety 0236 Throws nothing. 0237 */ 0238 url_base& 0239 url() const noexcept 0240 { 0241 return *u_; 0242 } 0243 0244 //-------------------------------------------- 0245 // 0246 // Modifiers 0247 // 0248 //-------------------------------------------- 0249 0250 /** Clear the contents of the container 0251 0252 <br> 0253 All iterators are invalidated. 0254 0255 @par Effects 0256 @code 0257 this->url().set_encoded_path( "" ); 0258 @endcode 0259 0260 @par Postconditions 0261 @code 0262 this->empty() == true 0263 @endcode 0264 0265 @par Complexity 0266 Linear in `this->url().encoded_query().size() + this->url().encoded_fragment().size()`. 0267 0268 @par Exception Safety 0269 Throws nothing. 0270 */ 0271 void 0272 clear() noexcept; 0273 0274 /** Assign segments 0275 0276 The existing contents are replaced 0277 by a copy of the contents of the 0278 initializer list. 0279 Reserved characters in the list are 0280 automatically escaped. 0281 0282 <br> 0283 All iterators are invalidated. 0284 0285 @note 0286 None of the character buffers referenced 0287 by `init` may overlap the character buffer 0288 of the underlying url, or else the behavior 0289 is undefined. 0290 0291 @par Example 0292 @code 0293 url u; 0294 0295 u.segments().assign( { "path", "to", "file.txt" } ); 0296 @endcode 0297 0298 @par Complexity 0299 Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`. 0300 0301 @par Exception Safety 0302 Strong guarantee. 0303 Calls to allocate may throw. 0304 0305 @param init The list of segments to assign. 0306 */ 0307 BOOST_URL_DECL 0308 void 0309 assign(std::initializer_list< 0310 core::string_view> init); 0311 0312 /** Assign segments 0313 0314 The existing contents are replaced 0315 by a copy of the contents of the range. 0316 Reserved characters in the range are 0317 automatically escaped. 0318 0319 <br> 0320 All iterators are invalidated. 0321 0322 @note 0323 None of the character buffers referenced 0324 by the range may overlap the character 0325 buffer of the underlying url, or else 0326 the behavior is undefined. 0327 0328 @par Mandates 0329 @code 0330 std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::string_view >::value == true 0331 @endcode 0332 0333 @par Complexity 0334 Linear in `std::distance( first, last ) + this->url().encoded_query().size() + this->url().encoded_fragment().size()`. 0335 0336 @par Exception Safety 0337 Strong guarantee. 0338 Calls to allocate may throw. 0339 0340 @param first, last The range of segments 0341 to assign. 0342 */ 0343 template<class FwdIt> 0344 void 0345 assign(FwdIt first, FwdIt last); 0346 0347 //-------------------------------------------- 0348 0349 /** Insert segments 0350 0351 This function inserts a segment 0352 before the specified position. 0353 Reserved characters in the segment are 0354 automatically escaped. 0355 0356 <br> 0357 All iterators that are equal to 0358 `before` or come after are invalidated. 0359 0360 @par Complexity 0361 Linear in `s.size() + this->url().encoded_resource().size()`. 0362 0363 @par Exception Safety 0364 Strong guarantee. 0365 Calls to allocate may throw. 0366 0367 @return An iterator to the inserted 0368 segment. 0369 0370 @param before An iterator before which 0371 the segment is inserted. This may 0372 be equal to `end()`. 0373 0374 @param s The segment to insert. 0375 */ 0376 BOOST_URL_DECL 0377 iterator 0378 insert( 0379 iterator before, 0380 core::string_view s); 0381 0382 /** Insert segments 0383 0384 This function inserts the segments 0385 in an initializer list before the 0386 specified position. 0387 Reserved characters in the list are 0388 percent-escaped in the result. 0389 0390 <br> 0391 All iterators that are equal to 0392 `before` or come after are invalidated. 0393 0394 @note 0395 None of the character buffers referenced 0396 by the list may overlap the character 0397 buffer of the underlying url, or else 0398 the behavior is undefined. 0399 0400 @par Example 0401 @code 0402 url u( "/file.txt" ); 0403 0404 u.segments().insert( u.segments().begin(), { "path", "to" } ); 0405 @endcode 0406 0407 @par Complexity 0408 Linear in `init.size() + this->url().encoded_resource().size()`. 0409 0410 @par Exception Safety 0411 Strong guarantee. 0412 Calls to allocate may throw. 0413 0414 @return An iterator to the first 0415 element inserted, or `before` if 0416 `init.size() == 0`. 0417 0418 @param before An iterator before which 0419 the list is inserted. This may 0420 be equal to `end()`. 0421 0422 @param init The list of segments to insert. 0423 */ 0424 BOOST_URL_DECL 0425 iterator 0426 insert( 0427 iterator before, 0428 std::initializer_list<core::string_view> init); 0429 0430 /** Insert segments 0431 0432 This function inserts the segments in 0433 a range before the specified position. 0434 Reserved characters in the list are 0435 automatically escaped. 0436 0437 <br> 0438 All iterators that are equal to 0439 `before` or come after are invalidated. 0440 0441 @note 0442 None of the character buffers referenced 0443 by the range may overlap the character 0444 buffer of the underlying url, or else 0445 the behavior is undefined. 0446 0447 @par Mandates 0448 @code 0449 std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::string_view >::value == true 0450 @endcode 0451 0452 @par Complexity 0453 Linear in `std::distance( first, last ) + this->url().encoded_resource().size()`. 0454 0455 @par Exception Safety 0456 Strong guarantee. 0457 Calls to allocate may throw. 0458 0459 @return An iterator to the first 0460 segment inserted, or `before` if 0461 `init.empty()`. 0462 0463 @param before An iterator before which 0464 the range is inserted. This may 0465 be equal to `end()`. 0466 0467 @param first, last The range of segments 0468 to insert. 0469 */ 0470 template<class FwdIt> 0471 iterator 0472 insert( 0473 iterator before, 0474 FwdIt first, 0475 FwdIt last); 0476 0477 //-------------------------------------------- 0478 0479 /** Erase segments 0480 0481 This function removes a segment. 0482 0483 <br> 0484 All iterators that are equal to 0485 `pos` or come after are invalidated. 0486 0487 @par Complexity 0488 Linear in `this->url().encoded_resource().size()`. 0489 0490 @par Exception Safety 0491 Throws nothing. 0492 0493 @return An iterator to one past 0494 the removed segment. 0495 0496 @param pos An iterator to the segment. 0497 */ 0498 iterator 0499 erase( 0500 iterator pos) noexcept; 0501 0502 /** Erase segments 0503 0504 This function removes a range of segments. 0505 0506 <br> 0507 All iterators that are equal to 0508 `first` or come after are invalidated. 0509 0510 @par Complexity 0511 Linear in `this->url().encoded_resource().size()`. 0512 0513 @par Exception Safety 0514 Throws nothing. 0515 0516 @return An iterator to one past 0517 the removed range. 0518 0519 @param first, last The range of 0520 segments to erase. 0521 */ 0522 BOOST_URL_DECL 0523 iterator 0524 erase( 0525 iterator first, 0526 iterator last) noexcept; 0527 0528 //-------------------------------------------- 0529 0530 /** Replace segments 0531 0532 This function replaces the segment at 0533 the specified position. 0534 Reserved characters in the string are 0535 automatically escaped. 0536 0537 <br> 0538 All iterators that are equal to 0539 `pos` or come after are invalidated. 0540 0541 @par Complexity 0542 Linear in `s.size() + this->url().encoded_resouce().size()`. 0543 0544 @par Exception Safety 0545 Strong guarantee. 0546 Calls to allocate may throw. 0547 0548 @return An iterator to the replaced segment. 0549 0550 @param pos An iterator to the segment. 0551 0552 @param s The string to assign. 0553 */ 0554 BOOST_URL_DECL 0555 iterator 0556 replace( 0557 iterator pos, 0558 core::string_view s); 0559 0560 /** Replace segments 0561 0562 This function replaces a range of 0563 segments with one segment. 0564 Reserved characters in the string are 0565 automatically escaped. 0566 0567 <br> 0568 All iterators that are equal to 0569 `from` or come after are invalidated. 0570 0571 @par Complexity 0572 Linear in `s.size() + this->url().encoded_resouce().size()`. 0573 0574 @par Exception Safety 0575 Strong guarantee. 0576 Calls to allocate may throw. 0577 0578 @return An iterator to the new segment. 0579 0580 @param from, to The range of segments to replace. 0581 0582 @param s The string to assign. 0583 */ 0584 BOOST_URL_DECL 0585 iterator 0586 replace( 0587 iterator from, 0588 iterator to, 0589 core::string_view s); 0590 0591 /** Replace segments 0592 0593 This function replaces a range of 0594 segments with a list of segments in 0595 an initializer list. 0596 Reserved characters in the list are 0597 automatically escaped. 0598 0599 <br> 0600 All iterators that are equal to 0601 `from` or come after are invalidated. 0602 0603 @par Preconditions 0604 None of the character buffers referenced 0605 by the list may overlap the character 0606 buffer of the underlying url, or else 0607 the behavior is undefined. 0608 0609 @par Complexity 0610 Linear in `init.size() + this->url().encoded_resouce().size()`. 0611 0612 @par Exception Safety 0613 Strong guarantee. 0614 Calls to allocate may throw. 0615 0616 @return An iterator to the first 0617 segment inserted, or one past `to` if 0618 `init.size() == 0`. 0619 0620 @param from, to The range of segments to replace. 0621 0622 @param init The list of segments to assign. 0623 */ 0624 BOOST_URL_DECL 0625 iterator 0626 replace( 0627 iterator from, 0628 iterator to, 0629 std::initializer_list< 0630 core::string_view> init); 0631 0632 /** Replace segments 0633 0634 This function replaces a range of 0635 segments with annother range of segments. 0636 Reserved characters in the new range are 0637 automatically escaped. 0638 0639 <br> 0640 All iterators that are equal to 0641 `from` or come after are invalidated. 0642 0643 @par Preconditions 0644 None of the character buffers referenced 0645 by the new range may overlap the character 0646 buffer of the underlying url, or else 0647 the behavior is undefined. 0648 0649 @par Complexity 0650 Linear in `std::distance( first, last ) + this->url().encoded_resouce().size()`. 0651 0652 @par Exception Safety 0653 Strong guarantee. 0654 Calls to allocate may throw. 0655 0656 @return An iterator to the first 0657 segment inserted, or one past `to` if 0658 `init.size() == 0`. 0659 0660 @param from, to The range of segments to replace. 0661 0662 @param first, last The range of segments to assign. 0663 */ 0664 template<class FwdIt> 0665 iterator 0666 replace( 0667 iterator from, 0668 iterator to, 0669 FwdIt first, 0670 FwdIt last); 0671 0672 /** Append a segment 0673 0674 This function appends a segment to 0675 the end of the path. 0676 Reserved characters in the string are 0677 automatically escaped. 0678 0679 <br> 0680 All end iterators are invalidated. 0681 0682 @par Postconditions 0683 @code 0684 this->back() == s 0685 @endcode 0686 0687 @par Exception Safety 0688 Strong guarantee. 0689 Calls to allocate may throw. 0690 0691 @param s The segment to append. 0692 */ 0693 void 0694 push_back( 0695 core::string_view s); 0696 0697 /** Remove the last segment 0698 0699 This function removes the last segment 0700 from the container. 0701 0702 <br> 0703 Iterators to the last segment as well 0704 as all end iterators are invalidated. 0705 0706 @par Preconditions 0707 @code 0708 not this->empty() 0709 @endcode 0710 0711 @par Exception Safety 0712 Throws nothing. 0713 */ 0714 void 0715 pop_back() noexcept; 0716 0717 private: 0718 template<class FwdIt> 0719 iterator 0720 insert( 0721 iterator before, 0722 FwdIt first, 0723 FwdIt last, 0724 std::input_iterator_tag) = delete; 0725 0726 template<class FwdIt> 0727 iterator 0728 insert( 0729 iterator before, 0730 FwdIt first, 0731 FwdIt last, 0732 std::forward_iterator_tag); 0733 }; 0734 0735 } // urls 0736 } // boost 0737 0738 // This include is at the bottom of 0739 // url_base.hpp because of a circular dependency 0740 // 0741 // #include <boost/url/impl/segments_ref.hpp> 0742 0743 #endif
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|