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