EIC code displayed by LXR |
|
|
|
|||
File indexing completed on 2025-09-13 08:52:46
0001 // 0002 // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com) 0003 // 0004 // Distributed under the Boost Software License, Version 1.0. (See accompanying 0005 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 0006 // 0007 // Official repository: https://github.com/boostorg/url 0008 // 0009 0010 #ifndef BOOST_URL_AUTHORITY_VIEW_HPP 0011 #define BOOST_URL_AUTHORITY_VIEW_HPP 0012 0013 #include <boost/url/detail/config.hpp> 0014 #include <boost/url/host_type.hpp> 0015 #include <boost/url/ipv4_address.hpp> 0016 #include <boost/url/ipv6_address.hpp> 0017 #include <boost/url/pct_string_view.hpp> 0018 #include <boost/url/detail/except.hpp> 0019 #include <boost/url/detail/url_impl.hpp> 0020 #include <boost/assert.hpp> 0021 #include <cstddef> 0022 #include <iosfwd> 0023 #include <utility> 0024 0025 namespace boost { 0026 namespace urls { 0027 0028 /** A non-owning reference to a valid authority 0029 0030 Objects of this type represent valid authority 0031 strings constructed from a parsed, external 0032 character buffer whose storage is managed 0033 by the caller. That is, it acts like a 0034 `core::string_view` in terms of ownership. 0035 The caller is responsible for ensuring 0036 that the lifetime of the underlying 0037 character buffer extends until it is no 0038 longer referenced. 0039 0040 @par Example 1 0041 Construction from a string parses the input 0042 as an <em>authority</em> and throws an 0043 exception on error. Upon success, the 0044 constructed object points to the passed 0045 character buffer; ownership is not 0046 transferred. 0047 @code 0048 authority_view a( "user:pass@www.example.com:8080" ); 0049 @endcode 0050 0051 @par Example 2 0052 The parsing function @ref parse_authority returns 0053 a `boost::system::result` containing either a valid 0054 @ref authority_view upon succcess, otherwise it 0055 contain an error. The error can be converted to 0056 an exception by the caller if desired: 0057 @code 0058 system::result< authority_view > rv = parse_authority( "user:pass@www.example.com:8080" ); 0059 @endcode 0060 0061 @par BNF 0062 @code 0063 authority = [ userinfo "@" ] host [ ":" port ] 0064 0065 userinfo = user [ ":" [ password ] ] 0066 0067 user = *( unreserved / pct-encoded / sub-delims ) 0068 password = *( unreserved / pct-encoded / sub-delims / ":" ) 0069 0070 host = IP-literal / IPv4address / reg-name 0071 0072 port = *DIGIT 0073 @endcode 0074 0075 @par Specification 0076 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2" 0077 >3.2. Authority (rfc3986)</a> 0078 0079 @see 0080 @ref parse_authority. 0081 */ 0082 class BOOST_URL_DECL 0083 authority_view 0084 : private detail::parts_base 0085 { 0086 detail::url_impl u_; 0087 0088 #ifndef BOOST_URL_DOCS 0089 // VFALCO docca emits this erroneously 0090 friend struct detail::url_impl; 0091 #endif 0092 0093 explicit 0094 authority_view( 0095 detail::url_impl const& u) noexcept; 0096 0097 public: 0098 //-------------------------------------------- 0099 // 0100 // Special Members 0101 // 0102 //-------------------------------------------- 0103 0104 /** Destructor 0105 */ 0106 virtual 0107 ~authority_view(); 0108 0109 /** Constructor 0110 0111 Default constructed authorities 0112 refer to a string with zero length, 0113 which is always valid. This matches 0114 the grammar for a zero-length host. 0115 0116 @par Exception Safety 0117 Throws nothing. 0118 0119 @par Specification 0120 */ 0121 authority_view() noexcept; 0122 0123 /** Construct from a string. 0124 0125 This function attempts to construct 0126 an authority from the string `s`, 0127 which must be a valid ['authority] or 0128 else an exception is thrown. Upon 0129 successful construction, the view 0130 refers to the characters in the 0131 buffer pointed to by `s`. 0132 Ownership is not transferred; The 0133 caller is responsible for ensuring 0134 that the lifetime of the buffer 0135 extends until the view is destroyed. 0136 0137 @param s The string to parse 0138 0139 @par BNF 0140 @code 0141 authority = [ userinfo "@" ] host [ ":" port ] 0142 0143 userinfo = user [ ":" [ password ] ] 0144 0145 user = *( unreserved / pct-encoded / sub-delims ) 0146 password = *( unreserved / pct-encoded / sub-delims / ":" ) 0147 0148 host = IP-literal / IPv4address / reg-name 0149 0150 port = *DIGIT 0151 @endcode 0152 0153 @par Specification 0154 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2" 0155 >3.2. Authority (rfc3986)</a> 0156 0157 @see 0158 @ref parse_authority. 0159 */ 0160 explicit 0161 authority_view(core::string_view s); 0162 0163 /** Constructor 0164 */ 0165 authority_view( 0166 authority_view const&) noexcept; 0167 0168 /** Assignment 0169 0170 This function assigns the contents of 0171 `other` to this object. 0172 0173 @param other The object to assign 0174 @return A reference to this object 0175 0176 @par Exception Safety 0177 Throws nothing. 0178 */ 0179 authority_view& 0180 operator=( 0181 authority_view const& other) noexcept; 0182 0183 //-------------------------------------------- 0184 // 0185 // Observers 0186 // 0187 //-------------------------------------------- 0188 0189 /** Return the number of characters in the authority 0190 0191 This function returns the number of 0192 characters in the authority. 0193 0194 @return The number of characters in the authority 0195 0196 @par Example 0197 @code 0198 assert( authority_view( "user:pass@www.example.com:8080" ).size() == 30 ); 0199 @endcode 0200 0201 @par Exception Safety 0202 Throws nothing. 0203 */ 0204 std::size_t 0205 size() const noexcept 0206 { 0207 return u_.offset(id_end); 0208 } 0209 0210 /** Return true if the authority is empty 0211 0212 An empty authority has an empty host, 0213 no userinfo, and no port. 0214 0215 @return `true` if the authority is empty 0216 0217 @par Example 0218 @code 0219 assert( authority_view( "" ).empty() ); 0220 @endcode 0221 0222 @par Exception Safety 0223 Throws nothing. 0224 */ 0225 bool 0226 empty() const noexcept 0227 { 0228 return size() == 0; 0229 } 0230 0231 /** Return a pointer to the first character 0232 0233 This function returns a pointer to the 0234 beginning of the view, which is not 0235 guaranteed to be null-terminated. 0236 0237 @return A pointer to the first character 0238 0239 @par Exception Safety 0240 Throws nothing. 0241 */ 0242 char const* 0243 data() const noexcept 0244 { 0245 return u_.cs_; 0246 } 0247 0248 /** Return the complete authority 0249 0250 This function returns the authority 0251 as a percent-encoded string. 0252 0253 @return The complete authority 0254 0255 @par Example 0256 @code 0257 assert( parse_authority( "www.example.com" ).value().buffer() == "www.example.com" ); 0258 @endcode 0259 0260 @par BNF 0261 @code 0262 authority = [ userinfo "@" ] host [ ":" port ] 0263 @endcode 0264 0265 @par Exception Safety 0266 Throws nothing. 0267 0268 @par Specification 0269 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2" 0270 >3.2. Authority (rfc3986)</a> 0271 */ 0272 core::string_view 0273 buffer() const noexcept 0274 { 0275 return core::string_view(data(), size()); 0276 } 0277 0278 //-------------------------------------------- 0279 // 0280 // Userinfo 0281 // 0282 //-------------------------------------------- 0283 0284 /** Return true if a userinfo is present 0285 0286 This function returns true if this 0287 contains a userinfo. 0288 0289 @return `true` if a userinfo is present 0290 0291 @par Example 0292 @code 0293 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_userinfo() ); 0294 @endcode 0295 0296 @par Complexity 0297 Constant. 0298 0299 @par Exception Safety 0300 Throws nothing. 0301 0302 @par BNF 0303 @code 0304 userinfo = user [ ":" [ password ] ] 0305 0306 authority = [ userinfo "@" ] host [ ":" port ] 0307 @endcode 0308 0309 @par Specification 0310 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1" 0311 >3.2.1. User Information (rfc3986)</a> 0312 0313 @see 0314 @ref has_password, 0315 @ref encoded_password, 0316 @ref encoded_user, 0317 @ref encoded_userinfo, 0318 @ref password, 0319 @ref user, 0320 @ref userinfo. 0321 0322 */ 0323 bool 0324 has_userinfo() const noexcept; 0325 0326 /** Return the userinfo 0327 0328 If present, this function returns a 0329 string representing the userinfo (which 0330 may be empty). 0331 Otherwise it returns an empty string. 0332 Any percent-escapes in the string are 0333 decoded first. 0334 0335 @param token A string token to receive the result. 0336 @return The userinfo 0337 0338 @par Example 0339 @code 0340 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).userinfo() == "jane-doe:pass" ); 0341 @endcode 0342 0343 @par Complexity 0344 Linear in `this->userinfo().size()`. 0345 0346 @par Exception Safety 0347 Calls to allocate may throw. 0348 0349 @par BNF 0350 @code 0351 userinfo = user [ ":" [ password ] ] 0352 0353 authority = [ userinfo "@" ] host [ ":" port ] 0354 @endcode 0355 0356 @par Specification 0357 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1" 0358 >3.2.1. User Information (rfc3986)</a> 0359 0360 @see 0361 @ref has_password, 0362 @ref has_userinfo, 0363 @ref encoded_password, 0364 @ref encoded_user, 0365 @ref encoded_userinfo, 0366 @ref password, 0367 @ref user. 0368 */ 0369 template<BOOST_URL_STRTOK_TPARAM> 0370 BOOST_URL_STRTOK_RETURN 0371 userinfo( 0372 BOOST_URL_STRTOK_ARG(token)) const 0373 { 0374 encoding_opts opt; 0375 opt.space_as_plus = false; 0376 return encoded_userinfo().decode( 0377 opt, std::move(token)); 0378 } 0379 0380 /** Return the userinfo 0381 0382 If present, this function returns a 0383 string representing the userinfo (which 0384 may be empty). 0385 Otherwise it returns an empty string. 0386 The returned string may contain 0387 percent escapes. 0388 0389 @return The userinfo 0390 0391 @par Example 0392 @code 0393 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_userinfo() == "jane%2Ddoe:pass" ); 0394 @endcode 0395 0396 @par Complexity 0397 Constant. 0398 0399 @par Exception Safety 0400 Throws nothing 0401 0402 @par BNF 0403 @code 0404 userinfo = user [ ":" [ password ] ] 0405 0406 authority = [ userinfo "@" ] host [ ":" port ] 0407 @endcode 0408 0409 @par Specification 0410 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1" 0411 >3.2.1. User Information (rfc3986)</a> 0412 0413 @see 0414 @ref has_password, 0415 @ref has_userinfo, 0416 @ref encoded_password, 0417 @ref encoded_user, 0418 @ref password, 0419 @ref user, 0420 @ref userinfo. 0421 */ 0422 pct_string_view 0423 encoded_userinfo() const noexcept; 0424 0425 //-------------------------------------------- 0426 0427 /** Return the user 0428 0429 If present, this function returns a 0430 string representing the user (which 0431 may be empty). 0432 Otherwise it returns an empty string. 0433 Any percent-escapes in the string are 0434 decoded first. 0435 0436 @param token A string token to receive the result. 0437 @return The user 0438 0439 @par Example 0440 @code 0441 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).user() == "jane-doe" ); 0442 @endcode 0443 0444 @par Complexity 0445 Linear in `this->user().size()`. 0446 0447 @par Exception Safety 0448 Calls to allocate may throw. 0449 0450 @par BNF 0451 @code 0452 userinfo = user [ ":" [ password ] ] 0453 0454 user = *( unreserved / pct-encoded / sub-delims ) 0455 password = *( unreserved / pct-encoded / sub-delims / ":" ) 0456 @endcode 0457 0458 @par Specification 0459 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1" 0460 >3.2.1. User Information (rfc3986)</a> 0461 0462 @see 0463 @ref has_password, 0464 @ref has_userinfo, 0465 @ref encoded_password, 0466 @ref encoded_user, 0467 @ref encoded_userinfo, 0468 @ref password, 0469 @ref userinfo. 0470 */ 0471 template<BOOST_URL_STRTOK_TPARAM> 0472 BOOST_URL_STRTOK_RETURN 0473 user( 0474 BOOST_URL_STRTOK_ARG(token)) const 0475 { 0476 encoding_opts opt; 0477 opt.space_as_plus = false; 0478 return encoded_user().decode( 0479 opt, std::move(token)); 0480 } 0481 0482 /** Return the user 0483 0484 If present, this function returns a 0485 string representing the user (which 0486 may be empty). 0487 Otherwise it returns an empty string. 0488 The returned string may contain 0489 percent escapes. 0490 0491 @return The user 0492 0493 @par Example 0494 @code 0495 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_user() == "jane%2Ddoe" ); 0496 @endcode 0497 0498 @par Complexity 0499 Constant. 0500 0501 @par Exception Safety 0502 Throws nothing. 0503 0504 @par BNF 0505 @code 0506 userinfo = user [ ":" [ password ] ] 0507 0508 user = *( unreserved / pct-encoded / sub-delims ) 0509 password = *( unreserved / pct-encoded / sub-delims / ":" ) 0510 @endcode 0511 0512 @par Specification 0513 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1" 0514 >3.2.1. User Information (rfc3986)</a> 0515 0516 @see 0517 @ref has_password, 0518 @ref has_userinfo, 0519 @ref encoded_password, 0520 @ref encoded_userinfo, 0521 @ref password, 0522 @ref user, 0523 @ref userinfo. 0524 */ 0525 pct_string_view 0526 encoded_user() const noexcept; 0527 0528 /** Return true if a password is present 0529 0530 This function returns true if the 0531 userinfo is present and contains 0532 a password. 0533 0534 @return `true` if a password is present 0535 0536 @par Example 0537 @code 0538 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_password() ); 0539 @endcode 0540 0541 @par Complexity 0542 Constant. 0543 0544 @par Exception Safety 0545 Throws nothing. 0546 0547 @par BNF 0548 @code 0549 userinfo = user [ ":" [ password ] ] 0550 0551 user = *( unreserved / pct-encoded / sub-delims ) 0552 password = *( unreserved / pct-encoded / sub-delims / ":" ) 0553 @endcode 0554 0555 @par Specification 0556 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1" 0557 >3.2.1. User Information (rfc3986)</a> 0558 0559 @see 0560 @ref has_userinfo, 0561 @ref encoded_password, 0562 @ref encoded_user, 0563 @ref encoded_userinfo, 0564 @ref password, 0565 @ref user, 0566 @ref userinfo. 0567 */ 0568 bool 0569 has_password() const noexcept; 0570 0571 /** Return the password 0572 0573 If present, this function returns a 0574 string representing the password (which 0575 may be an empty string). 0576 Otherwise it returns an empty string. 0577 Any percent-escapes in the string are 0578 decoded first. 0579 0580 @param token A string token to receive the result. 0581 @return The password 0582 0583 @par Example 0584 @code 0585 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).password() == "pass" ); 0586 @endcode 0587 0588 @par Complexity 0589 Linear in `this->password().size()`. 0590 0591 @par Exception Safety 0592 Calls to allocate may throw. 0593 0594 @par BNF 0595 @code 0596 userinfo = user [ ":" [ password ] ] 0597 0598 user = *( unreserved / pct-encoded / sub-delims ) 0599 password = *( unreserved / pct-encoded / sub-delims / ":" ) 0600 @endcode 0601 0602 @par Specification 0603 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1" 0604 >3.2.1. User Information (rfc3986)</a> 0605 0606 @see 0607 @ref has_password, 0608 @ref has_userinfo, 0609 @ref encoded_password, 0610 @ref encoded_user, 0611 @ref encoded_userinfo, 0612 @ref user, 0613 @ref userinfo. 0614 */ 0615 template<BOOST_URL_STRTOK_TPARAM> 0616 BOOST_URL_STRTOK_RETURN 0617 password( 0618 BOOST_URL_STRTOK_ARG(token)) const 0619 { 0620 encoding_opts opt; 0621 opt.space_as_plus = false; 0622 return encoded_password().decode( 0623 opt, std::move(token)); 0624 } 0625 0626 /** Return the password 0627 0628 This function returns the password portion 0629 of the userinfo as a percent-encoded string. 0630 0631 @return The password 0632 0633 @par Example 0634 @code 0635 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_password() == "pass" ); 0636 @endcode 0637 0638 @par Complexity 0639 Constant. 0640 0641 @par Exception Safety 0642 Throws nothing. 0643 0644 @par BNF 0645 @code 0646 userinfo = user [ ":" [ password ] ] 0647 0648 user = *( unreserved / pct-encoded / sub-delims ) 0649 password = *( unreserved / pct-encoded / sub-delims / ":" ) 0650 @endcode 0651 0652 @par Specification 0653 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1" 0654 >3.2.1. User Information (rfc3986)</a> 0655 0656 @see 0657 @ref has_password, 0658 @ref has_userinfo, 0659 @ref encoded_user, 0660 @ref encoded_userinfo, 0661 @ref password, 0662 @ref user, 0663 @ref userinfo. 0664 */ 0665 pct_string_view 0666 encoded_password() const noexcept; 0667 0668 //-------------------------------------------- 0669 // 0670 // Host 0671 // 0672 //-------------------------------------------- 0673 0674 /** Return the host type 0675 0676 This function returns one of the 0677 following constants representing the 0678 type of host present. 0679 0680 @li @ref host_type::ipv4 0681 @li @ref host_type::ipv6 0682 @li @ref host_type::ipvfuture 0683 @li @ref host_type::name 0684 0685 @return The host type 0686 0687 @par Example 0688 @code 0689 assert( url_view( "https://192.168.0.1/local.htm" ).host_type() == host_type::ipv4 ); 0690 @endcode 0691 0692 @par Complexity 0693 Constant. 0694 0695 @par Exception Safety 0696 Throws nothing. 0697 0698 @par Specification 0699 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2" 0700 >3.2.2. Host (rfc3986)</a> 0701 */ 0702 urls::host_type 0703 host_type() const noexcept 0704 { 0705 return u_.host_type_; 0706 } 0707 0708 /** Return the host 0709 0710 This function returns the host portion 0711 of the authority as a string, or the 0712 empty string if there is no authority. 0713 Any percent-escapes in the string are 0714 decoded first. 0715 0716 @param token A string token to receive the result. 0717 @return The host 0718 0719 @par Example 0720 @code 0721 assert( url_view( "https://www%2droot.example.com/" ).host() == "www-root.example.com" ); 0722 @endcode 0723 0724 @par Complexity 0725 Linear in `this->host().size()`. 0726 0727 @par Exception Safety 0728 Calls to allocate may throw. 0729 0730 @par BNF 0731 @code 0732 host = IP-literal / IPv4address / reg-name 0733 0734 IP-literal = "[" ( IPv6address / IPvFuture ) "]" 0735 0736 reg-name = *( unreserved / pct-encoded / "-" / ".") 0737 @endcode 0738 0739 @par Specification 0740 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2" 0741 >3.2.2. Host (rfc3986)</a> 0742 */ 0743 template<BOOST_URL_STRTOK_TPARAM> 0744 BOOST_URL_STRTOK_RETURN 0745 host( 0746 BOOST_URL_STRTOK_ARG(token)) const 0747 { 0748 encoding_opts opt; 0749 opt.space_as_plus = false; 0750 return encoded_host().decode( 0751 opt, std::move(token)); 0752 } 0753 0754 /** Return the host 0755 0756 This function returns the host portion 0757 of the authority as a string, or the 0758 empty string if there is no authority. 0759 The returned string may contain 0760 percent escapes. 0761 0762 @return The host 0763 0764 @par Example 0765 @code 0766 assert( url_view( "https://www%2droot.example.com/" ).encoded_host() == "www%2droot.example.com" ); 0767 @endcode 0768 0769 @par Complexity 0770 Constant. 0771 0772 @par Exception Safety 0773 Throws nothing. 0774 0775 @par BNF 0776 @code 0777 host = IP-literal / IPv4address / reg-name 0778 0779 IP-literal = "[" ( IPv6address / IPvFuture ) "]" 0780 0781 reg-name = *( unreserved / pct-encoded / "-" / ".") 0782 @endcode 0783 0784 @par Specification 0785 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2" 0786 >3.2.2. Host (rfc3986)</a> 0787 */ 0788 pct_string_view 0789 encoded_host() const noexcept; 0790 0791 /** Return the host 0792 0793 The value returned by this function 0794 depends on the type of host returned 0795 from the function @ref host_type. 0796 0797 @li If the type is @ref host_type::ipv4, 0798 then the IPv4 address string is returned. 0799 0800 @li If the type is @ref host_type::ipv6, 0801 then the IPv6 address string is returned, 0802 without any enclosing brackets. 0803 0804 @li If the type is @ref host_type::ipvfuture, 0805 then the IPvFuture address string is returned, 0806 without any enclosing brackets. 0807 0808 @li If the type is @ref host_type::name, 0809 then the host name string is returned. 0810 Any percent-escapes in the string are 0811 decoded first. 0812 0813 @li If the type is @ref host_type::none, 0814 then an empty string is returned. 0815 0816 @param token A string token to receive the result. 0817 @return The host address 0818 0819 @par Example 0820 @code 0821 assert( url_view( "https://[1::6:c0a8:1]/" ).host_address() == "1::6:c0a8:1" ); 0822 @endcode 0823 0824 @par Complexity 0825 Linear in `this->host_address().size()`. 0826 0827 @par Exception Safety 0828 Calls to allocate may throw. 0829 0830 @par BNF 0831 @code 0832 host = IP-literal / IPv4address / reg-name 0833 0834 IP-literal = "[" ( IPv6address / IPvFuture ) "]" 0835 0836 reg-name = *( unreserved / pct-encoded / "-" / ".") 0837 @endcode 0838 0839 @par Specification 0840 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2" 0841 >3.2.2. Host (rfc3986)</a> 0842 */ 0843 template<BOOST_URL_STRTOK_TPARAM> 0844 BOOST_URL_STRTOK_RETURN 0845 host_address( 0846 BOOST_URL_STRTOK_ARG(token)) const 0847 { 0848 encoding_opts opt; 0849 opt.space_as_plus = false; 0850 return encoded_host_address().decode( 0851 opt, std::move(token)); 0852 } 0853 0854 /** Return the host 0855 0856 The value returned by this function 0857 depends on the type of host returned 0858 from the function @ref host_type. 0859 0860 @li If the type is @ref host_type::ipv4, 0861 then the IPv4 address string is returned. 0862 0863 @li If the type is @ref host_type::ipv6, 0864 then the IPv6 address string is returned, 0865 without any enclosing brackets. 0866 0867 @li If the type is @ref host_type::ipvfuture, 0868 then the IPvFuture address string is returned, 0869 without any enclosing brackets. 0870 0871 @li If the type is @ref host_type::name, 0872 then the host name string is returned. 0873 Any percent-escapes in the string are 0874 decoded first. 0875 0876 @li If the type is @ref host_type::none, 0877 then an empty string is returned. 0878 The returned string may contain 0879 percent escapes. 0880 0881 @return The host address 0882 0883 @par Example 0884 @code 0885 assert( url_view( "https://www%2droot.example.com/" ).encoded_host_address() == "www%2droot.example.com" ); 0886 @endcode 0887 0888 @par Complexity 0889 Constant. 0890 0891 @par Exception Safety 0892 Throws nothing. 0893 0894 @par BNF 0895 @code 0896 host = IP-literal / IPv4address / reg-name 0897 0898 IP-literal = "[" ( IPv6address / IPvFuture ) "]" 0899 0900 reg-name = *( unreserved / pct-encoded / "-" / ".") 0901 @endcode 0902 0903 @par Specification 0904 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2" 0905 >3.2.2. Host (rfc3986)</a> 0906 */ 0907 pct_string_view 0908 encoded_host_address() const noexcept; 0909 0910 /** Return the host IPv4 address 0911 0912 If the host type is @ref host_type::ipv4, 0913 this function returns the address as 0914 a value of type @ref ipv4_address. 0915 Otherwise, if the host type is not an IPv4 0916 address, it returns a default-constructed 0917 value which is equal to the unspecified 0918 address "0.0.0.0". 0919 0920 @return The host IPv4 address 0921 0922 @par Example 0923 @code 0924 assert( url_view( "http://127.0.0.1/index.htm?user=win95" ).host_ipv4_address() == ipv4_address( "127.0.0.1" ) ); 0925 @endcode 0926 0927 @par Complexity 0928 Constant. 0929 0930 @par Exception Safety 0931 Throws nothing. 0932 0933 @par BNF 0934 @code 0935 IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet 0936 0937 dec-octet = DIGIT ; 0-9 0938 / %x31-39 DIGIT ; 10-99 0939 / "1" 2DIGIT ; 100-199 0940 / "2" %x30-34 DIGIT ; 200-249 0941 / "25" %x30-35 ; 250-255 0942 @endcode 0943 0944 @par Specification 0945 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2" 0946 >3.2.2. Host (rfc3986)</a> 0947 */ 0948 ipv4_address 0949 host_ipv4_address() const noexcept; 0950 0951 /** Return the host IPv6 address 0952 0953 If the host type is @ref host_type::ipv6, 0954 this function returns the address as 0955 a value of type @ref ipv6_address. 0956 Otherwise, if the host type is not an IPv6 0957 address, it returns a default-constructed 0958 value which is equal to the unspecified 0959 address "0:0:0:0:0:0:0:0". 0960 0961 @return The host IPv6 address 0962 0963 @par Example 0964 @code 0965 assert( url_view( "ftp://[::1]/" ).host_ipv6_address() == ipv6_address( "::1" ) ); 0966 @endcode 0967 0968 @par Complexity 0969 Constant. 0970 0971 @par Exception Safety 0972 Throws nothing. 0973 0974 @par BNF 0975 @code 0976 IPv6address = 6( h16 ":" ) ls32 0977 / "::" 5( h16 ":" ) ls32 0978 / [ h16 ] "::" 4( h16 ":" ) ls32 0979 / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32 0980 / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32 0981 / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32 0982 / [ *4( h16 ":" ) h16 ] "::" ls32 0983 / [ *5( h16 ":" ) h16 ] "::" h16 0984 / [ *6( h16 ":" ) h16 ] "::" 0985 0986 ls32 = ( h16 ":" h16 ) / IPv4address 0987 ; least-significant 32 bits of address 0988 0989 h16 = 1*4HEXDIG 0990 ; 16 bits of address represented in hexadecimal 0991 @endcode 0992 0993 @par Specification 0994 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2" 0995 >3.2.2. Host (rfc3986)</a> 0996 */ 0997 ipv6_address 0998 host_ipv6_address() const noexcept; 0999 1000 /** Return the host IPvFuture address 1001 1002 If the host type is @ref host_type::ipvfuture, 1003 this function returns the address as 1004 a string. 1005 Otherwise, if the host type is not an 1006 IPvFuture address, it returns an 1007 empty string. 1008 1009 @return The host IPvFuture address 1010 1011 @par Example 1012 @code 1013 assert( url_view( "http://[v1fe.d:9]/index.htm" ).host_ipvfuture() == "v1fe.d:9" ); 1014 @endcode 1015 1016 @par Complexity 1017 Constant. 1018 1019 @par Exception Safety 1020 Throws nothing. 1021 1022 @par BNF 1023 @code 1024 IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" ) 1025 @endcode 1026 1027 @par Specification 1028 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2" 1029 >3.2.2. Host (rfc3986)</a> 1030 */ 1031 core::string_view 1032 host_ipvfuture() const noexcept; 1033 1034 /** Return the host name 1035 1036 If the host type is @ref host_type::name, 1037 this function returns the name as 1038 a string. 1039 Otherwise, if the host type is not an 1040 name, it returns an empty string. 1041 Any percent-escapes in the string are 1042 decoded first. 1043 1044 @param token A string token to receive the result 1045 @return The host name 1046 1047 @par Example 1048 @code 1049 assert( url_view( "https://www%2droot.example.com/" ).host_name() == "www-root.example.com" ); 1050 @endcode 1051 1052 @par Complexity 1053 Linear in `this->host_name().size()`. 1054 1055 @par Exception Safety 1056 Calls to allocate may throw. 1057 1058 @par BNF 1059 @code 1060 host = IP-literal / IPv4address / reg-name 1061 1062 IP-literal = "[" ( IPv6address / IPvFuture ) "]" 1063 1064 reg-name = *( unreserved / pct-encoded / "-" / ".") 1065 @endcode 1066 1067 @par Specification 1068 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2" 1069 >3.2.2. Host (rfc3986)</a> 1070 */ 1071 template<BOOST_URL_STRTOK_TPARAM> 1072 BOOST_URL_STRTOK_RETURN 1073 host_name( 1074 BOOST_URL_STRTOK_ARG(token)) const 1075 { 1076 encoding_opts opt; 1077 opt.space_as_plus = false; 1078 return encoded_host_name().decode( 1079 opt, std::move(token)); 1080 } 1081 1082 /** Return the host name 1083 1084 If the host type is @ref host_type::name, 1085 this function returns the name as 1086 a string. 1087 Otherwise, if the host type is not an 1088 name, it returns an empty string. 1089 The returned string may contain 1090 percent escapes. 1091 1092 @return The host name 1093 1094 @par Example 1095 @code 1096 assert( url_view( "https://www%2droot.example.com/" ).encoded_host_name() == "www%2droot.example.com" ); 1097 @endcode 1098 1099 @par Complexity 1100 Constant. 1101 1102 @par Exception Safety 1103 Throws nothing. 1104 1105 @par BNF 1106 @code 1107 host = IP-literal / IPv4address / reg-name 1108 1109 IP-literal = "[" ( IPv6address / IPvFuture ) "]" 1110 1111 reg-name = *( unreserved / pct-encoded / "-" / ".") 1112 @endcode 1113 1114 @par Specification 1115 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2" 1116 >3.2.2. Host (rfc3986)</a> 1117 */ 1118 pct_string_view 1119 encoded_host_name() const noexcept; 1120 1121 //-------------------------------------------- 1122 // 1123 // Port 1124 // 1125 //-------------------------------------------- 1126 1127 /** Return true if a port is present 1128 1129 This function returns true if an 1130 authority is present and contains a port. 1131 1132 @return `true` if a port is present, otherwise `false` 1133 1134 @par Example 1135 @code 1136 assert( url_view( "wss://www.example.com:443" ).has_port() ); 1137 @endcode 1138 1139 @par Complexity 1140 Constant. 1141 1142 @par Exception Safety 1143 Throws nothing. 1144 1145 @par BNF 1146 @code 1147 authority = [ userinfo "@" ] host [ ":" port ] 1148 1149 port = *DIGIT 1150 @endcode 1151 1152 @par Specification 1153 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3" 1154 >3.2.3. Port (rfc3986)</a> 1155 1156 @see 1157 @ref encoded_host_and_port, 1158 @ref port, 1159 @ref port_number. 1160 */ 1161 bool 1162 has_port() const noexcept; 1163 1164 /** Return the port 1165 1166 If present, this function returns a 1167 string representing the port (which 1168 may be empty). 1169 Otherwise it returns an empty string. 1170 1171 @return The port as a string 1172 1173 @par Example 1174 @code 1175 assert( url_view( "http://localhost.com:8080" ).port() == "8080" ); 1176 @endcode 1177 1178 @par Complexity 1179 Constant. 1180 1181 @par Exception Safety 1182 Throws nothing. 1183 1184 @par BNF 1185 @code 1186 port = *DIGIT 1187 @endcode 1188 1189 @par Specification 1190 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3" 1191 >3.2.3. Port (rfc3986)</a> 1192 1193 @see 1194 @ref encoded_host_and_port, 1195 @ref has_port, 1196 @ref port_number. 1197 */ 1198 core::string_view 1199 port() const noexcept; 1200 1201 /** Return the port 1202 1203 If a port is present and the numerical 1204 value is representable, it is returned 1205 as an unsigned integer. Otherwise, the 1206 number zero is returned. 1207 1208 @return The port number 1209 1210 @par Example 1211 @code 1212 assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 ); 1213 @endcode 1214 1215 @par Complexity 1216 Constant. 1217 1218 @par Exception Safety 1219 Throws nothing. 1220 1221 @par BNF 1222 @code 1223 port = *DIGIT 1224 @endcode 1225 1226 @par Specification 1227 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3" 1228 >3.2.3. Port (rfc3986)</a> 1229 1230 @see 1231 @ref encoded_host_and_port, 1232 @ref has_port, 1233 @ref port. 1234 */ 1235 std::uint16_t 1236 port_number() const noexcept; 1237 1238 /** Return the host and port 1239 1240 If an authority is present, this 1241 function returns the host and optional 1242 port as a string, which may be empty. 1243 Otherwise it returns an empty string. 1244 The returned string may contain 1245 percent escapes. 1246 1247 @par Example 1248 @code 1249 assert( url_view( "http://www.example.com:8080/index.htm" ).encoded_host_and_port() == "www.example.com:8080" ); 1250 @endcode 1251 1252 @par Complexity 1253 Constant. 1254 1255 @par Exception Safety 1256 Throws nothing. 1257 1258 @par BNF 1259 @code 1260 authority = [ userinfo "@" ] host [ ":" port ] 1261 @endcode 1262 1263 @par Specification 1264 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2" 1265 >3.2.2. Host (rfc3986)</a> 1266 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3" 1267 >3.2.3. Port (rfc3986)</a> 1268 1269 @see 1270 @ref has_port, 1271 @ref port, 1272 @ref port_number. 1273 1274 @return The host and port 1275 */ 1276 pct_string_view 1277 encoded_host_and_port() const noexcept; 1278 1279 //-------------------------------------------- 1280 // 1281 // Comparison 1282 // 1283 //-------------------------------------------- 1284 1285 /** Return the result of comparing this with another authority 1286 1287 This function compares two authorities 1288 according to Syntax-Based comparison 1289 algorithm. 1290 1291 @par Exception Safety 1292 Throws nothing. 1293 1294 @param other The authority to compare 1295 1296 @return `-1` if `*this < other`, `0` if 1297 `this == other`, and 1 if `this > other`. 1298 1299 @par Specification 1300 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2" 1301 >6.2.2 Syntax-Based Normalization (rfc3986)</a> 1302 */ 1303 int 1304 compare(authority_view const& other) const noexcept; 1305 1306 /** Return the result of comparing two authorities 1307 The authorities are compared component 1308 by component as if they were first 1309 normalized. 1310 1311 @par Complexity 1312 Linear in `min( a0.size(), a1.size() )` 1313 1314 @par Exception Safety 1315 Throws nothing 1316 1317 @param a0 The first authority to compare 1318 @param a1 The second authority to compare 1319 @return `true` if `a0 == a1`, otherwise `false` 1320 */ 1321 friend 1322 bool 1323 operator==( 1324 authority_view const& a0, 1325 authority_view const& a1) noexcept 1326 { 1327 return a0.compare(a1) == 0; 1328 } 1329 1330 /** Return the result of comparing two authorities 1331 The authorities are compared component 1332 by component as if they were first 1333 normalized. 1334 1335 @par Complexity 1336 Linear in `min( a0.size(), a1.size() )` 1337 1338 @par Exception Safety 1339 Throws nothing 1340 1341 @param a0 The first authority to compare 1342 @param a1 The second authority to compare 1343 @return `true` if `a0 != a1`, otherwise `false` 1344 */ 1345 friend 1346 bool 1347 operator!=( 1348 authority_view const& a0, 1349 authority_view const& a1) noexcept 1350 { 1351 return ! (a0 == a1); 1352 } 1353 1354 /** Return the result of comparing two authorities 1355 The authorities are compared component 1356 by component as if they were first 1357 normalized. 1358 1359 @par Complexity 1360 Linear in `min( a0.size(), a1.size() )` 1361 1362 @par Exception Safety 1363 Throws nothing 1364 1365 @param a0 The first authority to compare 1366 @param a1 The second authority to compare 1367 @return `true` if `a0 < a1`, otherwise `false` 1368 */ 1369 friend 1370 bool 1371 operator<( 1372 authority_view const& a0, 1373 authority_view const& a1) noexcept 1374 { 1375 return a0.compare(a1) < 0; 1376 } 1377 1378 /** Return the result of comparing two authorities 1379 The authorities are compared component 1380 by component as if they were first 1381 normalized. 1382 1383 @par Complexity 1384 Linear in `min( a0.size(), a1.size() )` 1385 1386 @par Exception Safety 1387 Throws nothing 1388 1389 @param a0 The first authority to compare 1390 @param a1 The second authority to compare 1391 @return `true` if `a0 <= a1`, otherwise `false` 1392 */ 1393 friend 1394 bool 1395 operator<=( 1396 authority_view const& a0, 1397 authority_view const& a1) noexcept 1398 { 1399 return a0.compare(a1) <= 0; 1400 } 1401 1402 /** Return the result of comparing two authorities 1403 The authorities are compared component 1404 by component as if they were first 1405 normalized. 1406 1407 @par Complexity 1408 Linear in `min( a0.size(), a1.size() )` 1409 1410 @par Exception Safety 1411 Throws nothing 1412 1413 @param a0 The first authority to compare 1414 @param a1 The second authority to compare 1415 @return `true` if `a0 > a1`, otherwise `false` 1416 */ 1417 friend 1418 bool 1419 operator>( 1420 authority_view const& a0, 1421 authority_view const& a1) noexcept 1422 { 1423 return a0.compare(a1) > 0; 1424 } 1425 1426 /** Return the result of comparing two authorities 1427 The authorities are compared component 1428 by component as if they were first 1429 normalized. 1430 1431 @par Complexity 1432 Linear in `min( a0.size(), a1.size() )` 1433 1434 @par Exception Safety 1435 Throws nothing 1436 1437 @param a0 The first authority to compare 1438 @param a1 The second authority to compare 1439 @return `true` if `a0 >= a1`, otherwise `false` 1440 */ 1441 friend 1442 bool 1443 operator>=( 1444 authority_view const& a0, 1445 authority_view const& a1) noexcept 1446 { 1447 return a0.compare(a1) >= 0; 1448 } 1449 1450 //-------------------------------------------- 1451 1452 /** Format the encoded authority to the output stream 1453 1454 This hidden friend function serializes the encoded URL 1455 to the output stream. 1456 1457 @par Example 1458 @code 1459 authority_view a( "www.example.com" ); 1460 1461 std::cout << a << std::endl; 1462 @endcode 1463 1464 @return A reference to the output stream, for chaining 1465 1466 @param os The output stream to write to 1467 1468 @param a The URL to write 1469 */ 1470 friend 1471 std::ostream& 1472 operator<<( 1473 std::ostream& os, 1474 authority_view const& a) 1475 { 1476 return os << a.buffer(); 1477 } 1478 }; 1479 1480 /** Format the encoded authority to the output stream 1481 1482 This function serializes the encoded URL 1483 to the output stream. 1484 1485 @par Example 1486 @code 1487 authority_view a( "www.example.com" ); 1488 1489 std::cout << a << std::endl; 1490 @endcode 1491 1492 @return A reference to the output stream, for chaining 1493 1494 @param os The output stream to write to 1495 1496 @param a The URL to write 1497 */ 1498 std::ostream& 1499 operator<<( 1500 std::ostream& os, 1501 authority_view const& a); 1502 1503 //------------------------------------------------ 1504 1505 /** Parse an authority 1506 1507 This function parses a string according to 1508 the authority grammar below, and returns an 1509 @ref authority_view referencing the string. 1510 Ownership of the string is not transferred; 1511 the caller is responsible for ensuring that 1512 the lifetime of the string extends until the 1513 view is no longer being accessed. 1514 1515 @par BNF 1516 @code 1517 authority = [ userinfo "@" ] host [ ":" port ] 1518 1519 userinfo = user [ ":" [ password ] ] 1520 1521 user = *( unreserved / pct-encoded / sub-delims ) 1522 password = *( unreserved / pct-encoded / sub-delims / ":" ) 1523 1524 host = IP-literal / IPv4address / reg-name 1525 1526 port = *DIGIT 1527 @endcode 1528 1529 @par Exception Safety 1530 Throws nothing. 1531 1532 @return A view to the parsed authority 1533 1534 @param s The string to parse 1535 1536 @par Specification 1537 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2" 1538 >3.2. Authority (rfc3986)</a> 1539 1540 @see 1541 @ref authority_view. 1542 */ 1543 BOOST_URL_DECL 1544 system::result<authority_view> 1545 parse_authority( 1546 core::string_view s) noexcept; 1547 1548 //------------------------------------------------ 1549 1550 } // urls 1551 } // boost 1552 1553 #endif
| [ Source navigation ] | [ Diff markup ] | [ Identifier search ] | [ general search ] |
|
This page was automatically generated by the 2.3.7 LXR engine. The LXR team |
|