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