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