Index/include / boost / url / authority_view.hpp

include/boost/url/authority_view.hpp

100.0% Lines (43/43) 100.0% Functions (15/15)
include/boost/url/authority_view.hpp
Prev Index Next
Line TLA Hits Source Code
1 //
2 // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
3 // Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)
4 //
5 // Distributed under the Boost Software License, Version 1.0. (See accompanying
6 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7 //
8 // Official repository: https://github.com/boostorg/url
9 //
10
11 #ifndef BOOST_URL_AUTHORITY_VIEW_HPP
12 #define BOOST_URL_AUTHORITY_VIEW_HPP
13
14 #include <boost/url/detail/config.hpp>
15 #include <boost/url/host_type.hpp>
16 #include <boost/url/ipv4_address.hpp>
17 #include <boost/url/ipv6_address.hpp>
18 #include <boost/url/pct_string_view.hpp>
19 #include <boost/url/detail/except.hpp>
20 #include <boost/url/detail/url_impl.hpp>
21 #include <boost/assert.hpp>
22 #include <cstddef>
23 #include <iosfwd>
24 #include <utility>
25
26 namespace boost {
27 namespace urls {
28
29 class url_base;
30
31 namespace implementation_defined {
32 struct authority_rule_t;
33 struct uri_rule_t;
34 struct relative_ref_rule_t;
35 struct absolute_uri_rule_t;
36 } // implementation_defined
37
38 /** A non-owning reference to a valid authority
39
40 Objects of this type represent valid authority
41 strings constructed from a parsed, external
42 character buffer whose storage is managed
43 by the caller. That is, it acts like a
44 `core::string_view` in terms of ownership.
45 The caller is responsible for ensuring
46 that the lifetime of the underlying
47 character buffer extends until it is no
48 longer referenced.
49
50 @par Example 1
51 Construction from a string parses the input
52 as an <em>authority</em> and throws an
53 exception on error. Upon success, the
54 constructed object points to the passed
55 character buffer; ownership is not
56 transferred.
57 @code
58 authority_view a( "user:pass@www.example.com:8080" );
59 @endcode
60
61 @par Example 2
62 The parsing function @ref parse_authority returns
63 a `boost::system::result` containing either a valid
64 @ref authority_view upon success, otherwise it
65 contains an error. The error can be converted to
66 an exception by the caller if desired:
67 @code
68 system::result< authority_view > rv = parse_authority( "user:pass@www.example.com:8080" );
69 @endcode
70
71 @par BNF
72 @code
73 authority = [ userinfo "@" ] host [ ":" port ]
74
75 userinfo = user [ ":" [ password ] ]
76
77 user = *( unreserved / pct-encoded / sub-delims )
78 password = *( unreserved / pct-encoded / sub-delims / ":" )
79
80 host = IP-literal / IPv4address / reg-name
81
82 port = *DIGIT
83 @endcode
84
85 @par Specification
86 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2"
87 >3.2. Authority (rfc3986)</a>
88
89 @see
90 @ref parse_authority.
91 */
92 class BOOST_SYMBOL_VISIBLE
93 authority_view
94 : private detail::parts_base
95 {
96 detail::url_impl u_;
97
98 friend struct detail::url_impl;
99 friend struct implementation_defined::authority_rule_t;
100 friend struct implementation_defined::uri_rule_t;
101 friend struct implementation_defined::relative_ref_rule_t;
102 friend struct implementation_defined::absolute_uri_rule_t;
103 friend class url_view_base;
104 friend class url_base;
105
106 BOOST_URL_CXX14_CONSTEXPR
107 explicit
108 2534 authority_view(
109 detail::url_impl const& u) noexcept
110 2534 : u_(u)
111 {
112 2534 }
113
114 public:
115 //--------------------------------------------
116 //
117 // Special Members
118 //
119 //--------------------------------------------
120
121 /** Destructor
122 */
123 BOOST_URL_CXX20_CONSTEXPR
124 virtual
125 12418 ~authority_view()
126 12418 {
127 // Empty body instead of = default because
128 // some GCC versions reject a defaulted
129 // virtual constexpr destructor in constexpr
130 // evaluation ("used before its definition").
131 12418 }
132
133 /** Constructor
134
135 Default constructed authorities
136 refer to a string with zero length,
137 which is always valid. This matches
138 the grammar for a zero-length host.
139
140 @par Exception Safety
141 Throws nothing.
142
143 @par Specification
144 */
145 BOOST_URL_CXX14_CONSTEXPR
146 3811 authority_view() noexcept
147 3811 : u_(from::authority)
148 {
149 3811 }
150
151 /** Construct from a string.
152
153 This function attempts to construct
154 an authority from the string `s`,
155 which must be a valid authority or
156 else an exception is thrown. Upon
157 successful construction, the view
158 refers to the characters in the
159 buffer pointed to by `s`.
160 Ownership is not transferred; the
161 caller is responsible for ensuring
162 that the lifetime of the buffer
163 extends until the view is destroyed.
164
165 @param s The string to parse
166
167 @par BNF
168 @code
169 authority = [ userinfo "@" ] host [ ":" port ]
170
171 userinfo = user [ ":" [ password ] ]
172
173 user = *( unreserved / pct-encoded / sub-delims )
174 password = *( unreserved / pct-encoded / sub-delims / ":" )
175
176 host = IP-literal / IPv4address / reg-name
177
178 port = *DIGIT
179 @endcode
180
181 @par Specification
182 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2"
183 >3.2. Authority (rfc3986)</a>
184
185 @see
186 @ref parse_authority.
187 */
188 BOOST_URL_CXX20_CONSTEXPR
189 explicit
190 authority_view(core::string_view s);
191
192 /** Constructor
193 */
194 BOOST_URL_CXX14_CONSTEXPR
195 6073 authority_view(
196 authority_view const&) noexcept = default;
197
198 /** Assignment
199
200 This function assigns the contents of
201 `other` to this object.
202
203 @param other The object to assign
204 @return A reference to this object
205
206 @par Exception Safety
207 Throws nothing.
208 */
209 BOOST_URL_CXX20_CONSTEXPR
210 authority_view&
211 1858 operator=(
212 authority_view const& other) noexcept = default;
213
214 //--------------------------------------------
215 //
216 // Observers
217 //
218 //--------------------------------------------
219
220 /** Return the number of characters in the authority
221
222 This function returns the number of
223 characters in the authority.
224
225 @return The number of characters in the authority
226
227 @par Example
228 @code
229 assert( authority_view( "user:pass@www.example.com:8080" ).size() == 30 );
230 @endcode
231
232 @par Exception Safety
233 Throws nothing.
234 */
235 std::size_t
236 40 size() const noexcept
237 {
238 40 return u_.offset(id_end);
239 }
240
241 /** Return true if the authority is empty
242
243 An empty authority has an empty host,
244 no userinfo, and no port.
245
246 @return `true` if the authority is empty
247
248 @par Example
249 @code
250 assert( authority_view( "" ).empty() );
251 @endcode
252
253 @par Exception Safety
254 Throws nothing.
255 */
256 bool
257 3 empty() const noexcept
258 {
259 3 return size() == 0;
260 }
261
262 /** Return a pointer to the first character
263
264 This function returns a pointer to the
265 beginning of the view, which is not
266 guaranteed to be null-terminated.
267
268 @return A pointer to the first character
269
270 @par Exception Safety
271 Throws nothing.
272 */
273 char const*
274 36 data() const noexcept
275 {
276 36 return u_.cs_;
277 }
278
279 /** Return the complete authority
280
281 This function returns the authority
282 as a percent-encoded string.
283
284 @return The complete authority
285
286 @par Example
287 @code
288 assert( parse_authority( "www.example.com" ).value().buffer() == "www.example.com" );
289 @endcode
290
291 @par BNF
292 @code
293 authority = [ userinfo "@" ] host [ ":" port ]
294 @endcode
295
296 @par Exception Safety
297 Throws nothing.
298
299 @par Specification
300 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2"
301 >3.2. Authority (rfc3986)</a>
302 */
303 core::string_view
304 34 buffer() const noexcept
305 {
306 34 return core::string_view(data(), size());
307 }
308
309 //--------------------------------------------
310 //
311 // Userinfo
312 //
313 //--------------------------------------------
314
315 /** Return true if a userinfo is present
316
317 This function returns true if this
318 contains a userinfo.
319
320 @return `true` if a userinfo is present
321
322 @par Example
323 @code
324 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_userinfo() );
325 @endcode
326
327 @par Complexity
328 Constant.
329
330 @par Exception Safety
331 Throws nothing.
332
333 @par BNF
334 @code
335 userinfo = user [ ":" [ password ] ]
336
337 authority = [ userinfo "@" ] host [ ":" port ]
338 @endcode
339
340 @par Specification
341 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
342 >3.2.1. User Information (rfc3986)</a>
343
344 @see
345 @ref has_password,
346 @ref encoded_password,
347 @ref encoded_user,
348 @ref encoded_userinfo,
349 @ref password,
350 @ref user,
351 @ref userinfo.
352
353 */
354 BOOST_URL_CXX20_CONSTEXPR
355 bool
356 has_userinfo() const noexcept;
357
358 /** Return the userinfo
359
360 If present, this function returns a
361 string representing the userinfo (which
362 may be empty).
363 Otherwise it returns an empty string.
364 Any percent-escapes in the string are
365 decoded first.
366
367 @param token A string token to receive the result.
368 @return The userinfo
369
370 @par Example
371 @code
372 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).userinfo() == "jane-doe:pass" );
373 @endcode
374
375 @par Complexity
376 Linear in `this->userinfo().size()`.
377
378 @par Exception Safety
379 Calls to allocate may throw.
380
381 @par BNF
382 @code
383 userinfo = user [ ":" [ password ] ]
384
385 authority = [ userinfo "@" ] host [ ":" port ]
386 @endcode
387
388 @par Specification
389 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
390 >3.2.1. User Information (rfc3986)</a>
391
392 @see
393 @ref has_password,
394 @ref has_userinfo,
395 @ref encoded_password,
396 @ref encoded_user,
397 @ref encoded_userinfo,
398 @ref password,
399 @ref user.
400 */
401 template<BOOST_URL_STRTOK_TPARAM>
402 BOOST_URL_STRTOK_RETURN
403 24 userinfo(
404 BOOST_URL_STRTOK_ARG(token)) const
405 {
406 24 encoding_opts opt;
407 24 opt.space_as_plus = false;
408 48 return encoded_userinfo().decode(
409 48 opt, std::move(token));
410 }
411
412 /** Return the userinfo
413
414 If present, this function returns a
415 string representing the userinfo (which
416 may be empty).
417 Otherwise it returns an empty string.
418 The returned string may contain
419 percent escapes.
420
421 @return The userinfo
422
423 @par Example
424 @code
425 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_userinfo() == "jane%2Ddoe:pass" );
426 @endcode
427
428 @par Complexity
429 Constant.
430
431 @par Exception Safety
432 Throws nothing
433
434 @par BNF
435 @code
436 userinfo = user [ ":" [ password ] ]
437
438 authority = [ userinfo "@" ] host [ ":" port ]
439 @endcode
440
441 @par Specification
442 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
443 >3.2.1. User Information (rfc3986)</a>
444
445 @see
446 @ref has_password,
447 @ref has_userinfo,
448 @ref encoded_password,
449 @ref encoded_user,
450 @ref password,
451 @ref user,
452 @ref userinfo.
453 */
454 BOOST_URL_CXX20_CONSTEXPR
455 pct_string_view
456 encoded_userinfo() const noexcept;
457
458 //--------------------------------------------
459
460 /** Return the user
461
462 If present, this function returns a
463 string representing the user (which
464 may be empty).
465 Otherwise it returns an empty string.
466 Any percent-escapes in the string are
467 decoded first.
468
469 @param token A string token to receive the result.
470 @return The user
471
472 @par Example
473 @code
474 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).user() == "jane-doe" );
475 @endcode
476
477 @par Complexity
478 Linear in `this->user().size()`.
479
480 @par Exception Safety
481 Calls to allocate may throw.
482
483 @par BNF
484 @code
485 userinfo = user [ ":" [ password ] ]
486
487 user = *( unreserved / pct-encoded / sub-delims )
488 password = *( unreserved / pct-encoded / sub-delims / ":" )
489 @endcode
490
491 @par Specification
492 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
493 >3.2.1. User Information (rfc3986)</a>
494
495 @see
496 @ref has_password,
497 @ref has_userinfo,
498 @ref encoded_password,
499 @ref encoded_user,
500 @ref encoded_userinfo,
501 @ref password,
502 @ref userinfo.
503 */
504 template<BOOST_URL_STRTOK_TPARAM>
505 BOOST_URL_STRTOK_RETURN
506 13 user(
507 BOOST_URL_STRTOK_ARG(token)) const
508 {
509 13 encoding_opts opt;
510 13 opt.space_as_plus = false;
511 26 return encoded_user().decode(
512 26 opt, std::move(token));
513 }
514
515 /** Return the user
516
517 If present, this function returns a
518 string representing the user (which
519 may be empty).
520 Otherwise it returns an empty string.
521 The returned string may contain
522 percent escapes.
523
524 @return The user
525
526 @par Example
527 @code
528 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_user() == "jane%2Ddoe" );
529 @endcode
530
531 @par Complexity
532 Constant.
533
534 @par Exception Safety
535 Throws nothing.
536
537 @par BNF
538 @code
539 userinfo = user [ ":" [ password ] ]
540
541 user = *( unreserved / pct-encoded / sub-delims )
542 password = *( unreserved / pct-encoded / sub-delims / ":" )
543 @endcode
544
545 @par Specification
546 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
547 >3.2.1. User Information (rfc3986)</a>
548
549 @see
550 @ref has_password,
551 @ref has_userinfo,
552 @ref encoded_password,
553 @ref encoded_userinfo,
554 @ref password,
555 @ref user,
556 @ref userinfo.
557 */
558 BOOST_URL_CXX20_CONSTEXPR
559 pct_string_view
560 encoded_user() const noexcept;
561
562 /** Return true if a password is present
563
564 This function returns true if the
565 userinfo is present and contains
566 a password.
567
568 @return `true` if a password is present
569
570 @par Example
571 @code
572 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_password() );
573 @endcode
574
575 @par Complexity
576 Constant.
577
578 @par Exception Safety
579 Throws nothing.
580
581 @par BNF
582 @code
583 userinfo = user [ ":" [ password ] ]
584
585 user = *( unreserved / pct-encoded / sub-delims )
586 password = *( unreserved / pct-encoded / sub-delims / ":" )
587 @endcode
588
589 @par Specification
590 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
591 >3.2.1. User Information (rfc3986)</a>
592
593 @see
594 @ref has_userinfo,
595 @ref encoded_password,
596 @ref encoded_user,
597 @ref encoded_userinfo,
598 @ref password,
599 @ref user,
600 @ref userinfo.
601 */
602 BOOST_URL_CXX20_CONSTEXPR
603 bool
604 has_password() const noexcept;
605
606 /** Return the password
607
608 If present, this function returns a
609 string representing the password (which
610 may be an empty string).
611 Otherwise it returns an empty string.
612 Any percent-escapes in the string are
613 decoded first.
614
615 @param token A string token to receive the result.
616 @return The password
617
618 @par Example
619 @code
620 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).password() == "pass" );
621 @endcode
622
623 @par Complexity
624 Linear in `this->password().size()`.
625
626 @par Exception Safety
627 Calls to allocate may throw.
628
629 @par BNF
630 @code
631 userinfo = user [ ":" [ password ] ]
632
633 user = *( unreserved / pct-encoded / sub-delims )
634 password = *( unreserved / pct-encoded / sub-delims / ":" )
635 @endcode
636
637 @par Specification
638 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
639 >3.2.1. User Information (rfc3986)</a>
640
641 @see
642 @ref has_password,
643 @ref has_userinfo,
644 @ref encoded_password,
645 @ref encoded_user,
646 @ref encoded_userinfo,
647 @ref user,
648 @ref userinfo.
649 */
650 template<BOOST_URL_STRTOK_TPARAM>
651 BOOST_URL_STRTOK_RETURN
652 13 password(
653 BOOST_URL_STRTOK_ARG(token)) const
654 {
655 13 encoding_opts opt;
656 13 opt.space_as_plus = false;
657 26 return encoded_password().decode(
658 26 opt, std::move(token));
659 }
660
661 /** Return the password
662
663 This function returns the password portion
664 of the userinfo as a percent-encoded string.
665
666 @return The password
667
668 @par Example
669 @code
670 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_password() == "pass" );
671 @endcode
672
673 @par Complexity
674 Constant.
675
676 @par Exception Safety
677 Throws nothing.
678
679 @par BNF
680 @code
681 userinfo = user [ ":" [ password ] ]
682
683 user = *( unreserved / pct-encoded / sub-delims )
684 password = *( unreserved / pct-encoded / sub-delims / ":" )
685 @endcode
686
687 @par Specification
688 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
689 >3.2.1. User Information (rfc3986)</a>
690
691 @see
692 @ref has_password,
693 @ref has_userinfo,
694 @ref encoded_user,
695 @ref encoded_userinfo,
696 @ref password,
697 @ref user,
698 @ref userinfo.
699 */
700 BOOST_URL_CXX20_CONSTEXPR
701 pct_string_view
702 encoded_password() const noexcept;
703
704 //--------------------------------------------
705 //
706 // Host
707 //
708 //--------------------------------------------
709
710 /** Return the host type
711
712 This function returns one of the
713 following constants representing the
714 type of host present.
715
716 @li @ref host_type::ipv4
717 @li @ref host_type::ipv6
718 @li @ref host_type::ipvfuture
719 @li @ref host_type::name
720
721 @return The host type
722
723 @par Example
724 @code
725 assert( url_view( "https://192.168.0.1/local.htm" ).host_type() == host_type::ipv4 );
726 @endcode
727
728 @par Complexity
729 Constant.
730
731 @par Exception Safety
732 Throws nothing.
733
734 @par Specification
735 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
736 >3.2.2. Host (rfc3986)</a>
737 */
738 urls::host_type
739 8 host_type() const noexcept
740 {
741 8 return u_.host_type_;
742 }
743
744 /** Return the host
745
746 This function returns the host portion
747 of the authority as a string, or the
748 empty string if there is no authority.
749 Any percent-escapes in the string are
750 decoded first.
751
752 @param token A string token to receive the result.
753 @return The host
754
755 @par Example
756 @code
757 assert( url_view( "https://www%2droot.example.com/" ).host() == "www-root.example.com" );
758 @endcode
759
760 @par Complexity
761 Linear in `this->host().size()`.
762
763 @par Exception Safety
764 Calls to allocate may throw.
765
766 @par BNF
767 @code
768 host = IP-literal / IPv4address / reg-name
769
770 IP-literal = "[" ( IPv6address / IPvFuture ) "]"
771
772 reg-name = *( unreserved / pct-encoded / "-" / ".")
773 @endcode
774
775 @par Specification
776 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
777 >3.2.2. Host (rfc3986)</a>
778 */
779 template<BOOST_URL_STRTOK_TPARAM>
780 BOOST_URL_STRTOK_RETURN
781 7 host(
782 BOOST_URL_STRTOK_ARG(token)) const
783 {
784 7 encoding_opts opt;
785 7 opt.space_as_plus = false;
786 14 return encoded_host().decode(
787 14 opt, std::move(token));
788 }
789
790 /** Return the host
791
792 This function returns the host portion
793 of the authority as a string, or the
794 empty string if there is no authority.
795 The returned string may contain
796 percent escapes.
797
798 @return The host
799
800 @par Example
801 @code
802 assert( url_view( "https://www%2droot.example.com/" ).encoded_host() == "www%2droot.example.com" );
803 @endcode
804
805 @par Complexity
806 Constant.
807
808 @par Exception Safety
809 Throws nothing.
810
811 @par BNF
812 @code
813 host = IP-literal / IPv4address / reg-name
814
815 IP-literal = "[" ( IPv6address / IPvFuture ) "]"
816
817 reg-name = *( unreserved / pct-encoded / "-" / ".")
818 @endcode
819
820 @par Specification
821 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
822 >3.2.2. Host (rfc3986)</a>
823 */
824 BOOST_URL_CXX20_CONSTEXPR
825 pct_string_view
826 encoded_host() const noexcept;
827
828 /** Return the host
829
830 The value returned by this function
831 depends on the type of host returned
832 from the function @ref host_type.
833
834 @li If the type is @ref host_type::ipv4,
835 then the IPv4 address string is returned.
836
837 @li If the type is @ref host_type::ipv6,
838 then the IPv6 address string is returned,
839 without any enclosing brackets.
840
841 @li If the type is @ref host_type::ipvfuture,
842 then the IPvFuture address string is returned,
843 without any enclosing brackets.
844
845 @li If the type is @ref host_type::name,
846 then the host name string is returned.
847 Any percent-escapes in the string are
848 decoded first.
849
850 @li If the type is @ref host_type::none,
851 then an empty string is returned.
852
853 @param token A string token to receive the result.
854 @return The host address
855
856 @par Example
857 @code
858 assert( url_view( "https://[1::6:c0a8:1]/" ).host_address() == "1::6:c0a8:1" );
859 @endcode
860
861 @par Complexity
862 Linear in `this->host_address().size()`.
863
864 @par Exception Safety
865 Calls to allocate may throw.
866
867 @par BNF
868 @code
869 host = IP-literal / IPv4address / reg-name
870
871 IP-literal = "[" ( IPv6address / IPvFuture ) "]"
872
873 reg-name = *( unreserved / pct-encoded / "-" / ".")
874 @endcode
875
876 @par Specification
877 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
878 >3.2.2. Host (rfc3986)</a>
879 */
880 template<BOOST_URL_STRTOK_TPARAM>
881 BOOST_URL_STRTOK_RETURN
882 host_address(
883 BOOST_URL_STRTOK_ARG(token)) const
884 {
885 encoding_opts opt;
886 opt.space_as_plus = false;
887 return encoded_host_address().decode(
888 opt, std::move(token));
889 }
890
891 /** Return the host
892
893 The value returned by this function
894 depends on the type of host returned
895 from the function @ref host_type.
896
897 @li If the type is @ref host_type::ipv4,
898 then the IPv4 address string is returned.
899
900 @li If the type is @ref host_type::ipv6,
901 then the IPv6 address string is returned,
902 without any enclosing brackets.
903
904 @li If the type is @ref host_type::ipvfuture,
905 then the IPvFuture address string is returned,
906 without any enclosing brackets.
907
908 @li If the type is @ref host_type::name,
909 then the host name string is returned.
910 Any percent-escapes in the string are
911 decoded first.
912
913 @li If the type is @ref host_type::none,
914 then an empty string is returned.
915 The returned string may contain
916 percent escapes.
917
918 @return The host address
919
920 @par Example
921 @code
922 assert( url_view( "https://www%2droot.example.com/" ).encoded_host_address() == "www%2droot.example.com" );
923 @endcode
924
925 @par Complexity
926 Constant.
927
928 @par Exception Safety
929 Throws nothing.
930
931 @par BNF
932 @code
933 host = IP-literal / IPv4address / reg-name
934
935 IP-literal = "[" ( IPv6address / IPvFuture ) "]"
936
937 reg-name = *( unreserved / pct-encoded / "-" / ".")
938 @endcode
939
940 @par Specification
941 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
942 >3.2.2. Host (rfc3986)</a>
943 */
944 BOOST_URL_CXX20_CONSTEXPR
945 pct_string_view
946 encoded_host_address() const noexcept;
947
948 /** Return the host IPv4 address
949
950 If the host type is @ref host_type::ipv4,
951 this function returns the address as
952 a value of type @ref ipv4_address.
953 Otherwise, if the host type is not an IPv4
954 address, it returns a default-constructed
955 value which is equal to the unspecified
956 address "0.0.0.0".
957
958 @return The host IPv4 address
959
960 @par Example
961 @code
962 assert( url_view( "http://127.0.0.1/index.htm?user=win95" ).host_ipv4_address() == ipv4_address( "127.0.0.1" ) );
963 @endcode
964
965 @par Complexity
966 Constant.
967
968 @par Exception Safety
969 Throws nothing.
970
971 @par BNF
972 @code
973 IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
974
975 dec-octet = DIGIT ; 0-9
976 / %x31-39 DIGIT ; 10-99
977 / "1" 2DIGIT ; 100-199
978 / "2" %x30-34 DIGIT ; 200-249
979 / "25" %x30-35 ; 250-255
980 @endcode
981
982 @par Specification
983 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
984 >3.2.2. Host (rfc3986)</a>
985 */
986 BOOST_URL_CXX20_CONSTEXPR
987 ipv4_address
988 host_ipv4_address() const noexcept;
989
990 /** Return the host IPv6 address
991
992 If the host type is @ref host_type::ipv6,
993 this function returns the address as
994 a value of type @ref ipv6_address.
995 Otherwise, if the host type is not an IPv6
996 address, it returns a default-constructed
997 value which is equal to the unspecified
998 address "0:0:0:0:0:0:0:0".
999
1000 @return The host IPv6 address
1001
1002 @par Example
1003 @code
1004 assert( url_view( "ftp://[::1]/" ).host_ipv6_address() == ipv6_address( "::1" ) );
1005 @endcode
1006
1007 @par Complexity
1008 Constant.
1009
1010 @par Exception Safety
1011 Throws nothing.
1012
1013 @par BNF
1014 @code
1015 IPv6address = 6( h16 ":" ) ls32
1016 / "::" 5( h16 ":" ) ls32
1017 / [ h16 ] "::" 4( h16 ":" ) ls32
1018 / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
1019 / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
1020 / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32
1021 / [ *4( h16 ":" ) h16 ] "::" ls32
1022 / [ *5( h16 ":" ) h16 ] "::" h16
1023 / [ *6( h16 ":" ) h16 ] "::"
1024
1025 ls32 = ( h16 ":" h16 ) / IPv4address
1026 ; least-significant 32 bits of address
1027
1028 h16 = 1*4HEXDIG
1029 ; 16 bits of address represented in hexadecimal
1030 @endcode
1031
1032 @par Specification
1033 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
1034 >3.2.2. Host (rfc3986)</a>
1035 */
1036 BOOST_URL_CXX20_CONSTEXPR
1037 ipv6_address
1038 host_ipv6_address() const noexcept;
1039
1040 /** Return the host IPvFuture address
1041
1042 If the host type is @ref host_type::ipvfuture,
1043 this function returns the address as
1044 a string.
1045 Otherwise, if the host type is not an
1046 IPvFuture address, it returns an
1047 empty string.
1048
1049 @return The host IPvFuture address
1050
1051 @par Example
1052 @code
1053 assert( url_view( "http://[v1fe.d:9]/index.htm" ).host_ipvfuture() == "v1fe.d:9" );
1054 @endcode
1055
1056 @par Complexity
1057 Constant.
1058
1059 @par Exception Safety
1060 Throws nothing.
1061
1062 @par BNF
1063 @code
1064 IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
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 BOOST_URL_CXX20_CONSTEXPR
1072 core::string_view
1073 host_ipvfuture() const noexcept;
1074
1075 /** Return the host name
1076
1077 If the host type is @ref host_type::name,
1078 this function returns the name as
1079 a string.
1080 Otherwise, if the host type is not a
1081 name, it returns an empty string.
1082 Any percent-escapes in the string are
1083 decoded first.
1084
1085 @param token A string token to receive the result
1086 @return The host name
1087
1088 @par Example
1089 @code
1090 assert( url_view( "https://www%2droot.example.com/" ).host_name() == "www-root.example.com" );
1091 @endcode
1092
1093 @par Complexity
1094 Linear in `this->host_name().size()`.
1095
1096 @par Exception Safety
1097 Calls to allocate may throw.
1098
1099 @par BNF
1100 @code
1101 host = IP-literal / IPv4address / reg-name
1102
1103 IP-literal = "[" ( IPv6address / IPvFuture ) "]"
1104
1105 reg-name = *( unreserved / pct-encoded / "-" / ".")
1106 @endcode
1107
1108 @par Specification
1109 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
1110 >3.2.2. Host (rfc3986)</a>
1111 */
1112 template<BOOST_URL_STRTOK_TPARAM>
1113 BOOST_URL_STRTOK_RETURN
1114 host_name(
1115 BOOST_URL_STRTOK_ARG(token)) const
1116 {
1117 encoding_opts opt;
1118 opt.space_as_plus = false;
1119 return encoded_host_name().decode(
1120 opt, std::move(token));
1121 }
1122
1123 /** Return the host name
1124
1125 If the host type is @ref host_type::name,
1126 this function returns the name as
1127 a string.
1128 Otherwise, if the host type is not an
1129 name, it returns an empty string.
1130 The returned string may contain
1131 percent escapes.
1132
1133 @return The host name
1134
1135 @par Example
1136 @code
1137 assert( url_view( "https://www%2droot.example.com/" ).encoded_host_name() == "www%2droot.example.com" );
1138 @endcode
1139
1140 @par Complexity
1141 Constant.
1142
1143 @par Exception Safety
1144 Throws nothing.
1145
1146 @par BNF
1147 @code
1148 host = IP-literal / IPv4address / reg-name
1149
1150 IP-literal = "[" ( IPv6address / IPvFuture ) "]"
1151
1152 reg-name = *( unreserved / pct-encoded / "-" / ".")
1153 @endcode
1154
1155 @par Specification
1156 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
1157 >3.2.2. Host (rfc3986)</a>
1158 */
1159 BOOST_URL_CXX20_CONSTEXPR
1160 pct_string_view
1161 encoded_host_name() const noexcept;
1162
1163 //--------------------------------------------
1164 //
1165 // Port
1166 //
1167 //--------------------------------------------
1168
1169 /** Return true if a port is present
1170
1171 This function returns true if an
1172 authority is present and contains a port.
1173
1174 @return `true` if a port is present, otherwise `false`
1175
1176 @par Example
1177 @code
1178 assert( url_view( "wss://www.example.com:443" ).has_port() );
1179 @endcode
1180
1181 @par Complexity
1182 Constant.
1183
1184 @par Exception Safety
1185 Throws nothing.
1186
1187 @par BNF
1188 @code
1189 authority = [ userinfo "@" ] host [ ":" port ]
1190
1191 port = *DIGIT
1192 @endcode
1193
1194 @par Specification
1195 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3"
1196 >3.2.3. Port (rfc3986)</a>
1197
1198 @see
1199 @ref encoded_host_and_port,
1200 @ref port,
1201 @ref port_number.
1202 */
1203 BOOST_URL_CXX20_CONSTEXPR
1204 bool
1205 has_port() const noexcept;
1206
1207 /** Return the port
1208
1209 If present, this function returns a
1210 string representing the port (which
1211 may be empty).
1212 Otherwise it returns an empty string.
1213
1214 @return The port as a string
1215
1216 @par Example
1217 @code
1218 assert( url_view( "http://localhost.com:8080" ).port() == "8080" );
1219 @endcode
1220
1221 @par Complexity
1222 Constant.
1223
1224 @par Exception Safety
1225 Throws nothing.
1226
1227 @par BNF
1228 @code
1229 port = *DIGIT
1230 @endcode
1231
1232 @par Specification
1233 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3"
1234 >3.2.3. Port (rfc3986)</a>
1235
1236 @see
1237 @ref encoded_host_and_port,
1238 @ref has_port,
1239 @ref port_number.
1240 */
1241 BOOST_URL_CXX20_CONSTEXPR
1242 core::string_view
1243 port() const noexcept;
1244
1245 /** Return the port
1246
1247 If a port is present and the numerical
1248 value is representable, it is returned
1249 as an unsigned integer. Otherwise, the
1250 number zero is returned.
1251
1252 @return The port number
1253
1254 @par Example
1255 @code
1256 assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 );
1257 @endcode
1258
1259 @par Complexity
1260 Constant.
1261
1262 @par Exception Safety
1263 Throws nothing.
1264
1265 @par BNF
1266 @code
1267 port = *DIGIT
1268 @endcode
1269
1270 @par Specification
1271 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3"
1272 >3.2.3. Port (rfc3986)</a>
1273
1274 @see
1275 @ref encoded_host_and_port,
1276 @ref has_port,
1277 @ref port.
1278 */
1279 BOOST_URL_CXX20_CONSTEXPR
1280 std::uint16_t
1281 port_number() const noexcept;
1282
1283 /** Return the host and port
1284
1285 If an authority is present, this
1286 function returns the host and optional
1287 port as a string, which may be empty.
1288 Otherwise it returns an empty string.
1289 The returned string may contain
1290 percent escapes.
1291
1292 @par Example
1293 @code
1294 assert( url_view( "http://www.example.com:8080/index.htm" ).encoded_host_and_port() == "www.example.com:8080" );
1295 @endcode
1296
1297 @par Complexity
1298 Constant.
1299
1300 @par Exception Safety
1301 Throws nothing.
1302
1303 @par BNF
1304 @code
1305 authority = [ userinfo "@" ] host [ ":" port ]
1306 @endcode
1307
1308 @par Specification
1309 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
1310 >3.2.2. Host (rfc3986)</a>
1311 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3"
1312 >3.2.3. Port (rfc3986)</a>
1313
1314 @see
1315 @ref has_port,
1316 @ref port,
1317 @ref port_number.
1318
1319 @return The host and port
1320 */
1321 BOOST_URL_CXX20_CONSTEXPR
1322 pct_string_view
1323 encoded_host_and_port() const noexcept;
1324
1325 //--------------------------------------------
1326 //
1327 // Comparison
1328 //
1329 //--------------------------------------------
1330
1331 /** Return the result of comparing this with another authority
1332
1333 This function compares two authorities
1334 according to Syntax-Based comparison
1335 algorithm.
1336
1337 @par Exception Safety
1338 Throws nothing.
1339
1340 @param other The authority to compare
1341
1342 @return `-1` if `*this < other`, `0` if
1343 `this == other`, and 1 if `this > other`.
1344
1345 @par Specification
1346 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2"
1347 >6.2.2 Syntax-Based Normalization (rfc3986)</a>
1348 */
1349 int
1350 compare(authority_view const& other) const noexcept;
1351
1352 /** Return the result of comparing two authorities.
1353 The authorities are compared component
1354 by component as if they were first
1355 normalized.
1356
1357 @par Complexity
1358 Linear in `min( a0.size(), a1.size() )`
1359
1360 @par Exception Safety
1361 Throws nothing
1362
1363 @param a0 The first authority to compare
1364 @param a1 The second authority to compare
1365 @return `true` if `a0 == a1`, otherwise `false`
1366 */
1367 friend
1368 bool
1369 operator==(
1370 authority_view const& a0,
1371 authority_view const& a1) noexcept
1372 {
1373 return a0.compare(a1) == 0;
1374 }
1375
1376 /** Return the result of comparing two authorities.
1377 The authorities are compared component
1378 by component as if they were first
1379 normalized.
1380
1381 @par Complexity
1382 Linear in `min( a0.size(), a1.size() )`
1383
1384 @par Exception Safety
1385 Throws nothing
1386
1387 @param a0 The first authority to compare
1388 @param a1 The second authority to compare
1389 @return `true` if `a0 != a1`, otherwise `false`
1390 */
1391 friend
1392 bool
1393 operator!=(
1394 authority_view const& a0,
1395 authority_view const& a1) noexcept
1396 {
1397 return ! (a0 == a1);
1398 }
1399
1400 /** Return the result of comparing two authorities.
1401 The authorities are compared component
1402 by component as if they were first
1403 normalized.
1404
1405 @par Complexity
1406 Linear in `min( a0.size(), a1.size() )`
1407
1408 @par Exception Safety
1409 Throws nothing
1410
1411 @param a0 The first authority to compare
1412 @param a1 The second authority to compare
1413 @return `true` if `a0 < a1`, otherwise `false`
1414 */
1415 friend
1416 bool
1417 operator<(
1418 authority_view const& a0,
1419 authority_view const& a1) noexcept
1420 {
1421 return a0.compare(a1) < 0;
1422 }
1423
1424 /** Return the result of comparing two authorities.
1425 The authorities are compared component
1426 by component as if they were first
1427 normalized.
1428
1429 @par Complexity
1430 Linear in `min( a0.size(), a1.size() )`
1431
1432 @par Exception Safety
1433 Throws nothing
1434
1435 @param a0 The first authority to compare
1436 @param a1 The second authority to compare
1437 @return `true` if `a0 <= a1`, otherwise `false`
1438 */
1439 friend
1440 bool
1441 operator<=(
1442 authority_view const& a0,
1443 authority_view const& a1) noexcept
1444 {
1445 return a0.compare(a1) <= 0;
1446 }
1447
1448 /** Return the result of comparing two authorities.
1449 The authorities are compared component
1450 by component as if they were first
1451 normalized.
1452
1453 @par Complexity
1454 Linear in `min( a0.size(), a1.size() )`
1455
1456 @par Exception Safety
1457 Throws nothing
1458
1459 @param a0 The first authority to compare
1460 @param a1 The second authority to compare
1461 @return `true` if `a0 > a1`, otherwise `false`
1462 */
1463 friend
1464 bool
1465 operator>(
1466 authority_view const& a0,
1467 authority_view const& a1) noexcept
1468 {
1469 return a0.compare(a1) > 0;
1470 }
1471
1472 /** Return the result of comparing two authorities.
1473 The authorities are compared component
1474 by component as if they were first
1475 normalized.
1476
1477 @par Complexity
1478 Linear in `min( a0.size(), a1.size() )`
1479
1480 @par Exception Safety
1481 Throws nothing
1482
1483 @param a0 The first authority to compare
1484 @param a1 The second authority to compare
1485 @return `true` if `a0 >= a1`, otherwise `false`
1486 */
1487 friend
1488 bool
1489 operator>=(
1490 authority_view const& a0,
1491 authority_view const& a1) noexcept
1492 {
1493 return a0.compare(a1) >= 0;
1494 }
1495
1496 //--------------------------------------------
1497
1498 /** Format the encoded authority to the output stream
1499
1500 This hidden friend function serializes the encoded URL
1501 to the output stream.
1502
1503 @par Example
1504 @code
1505 authority_view a( "www.example.com" );
1506
1507 std::cout << a << std::endl;
1508 @endcode
1509
1510 @return A reference to the output stream, for chaining
1511
1512 @param os The output stream to write to
1513
1514 @param a The URL to write
1515 */
1516 friend
1517 std::ostream&
1518 6 operator<<(
1519 std::ostream& os,
1520 authority_view const& a)
1521 {
1522 6 return os << a.buffer();
1523 }
1524 };
1525
1526 /** Format the encoded authority to the output stream
1527
1528 This function serializes the encoded URL
1529 to the output stream.
1530
1531 @par Example
1532 @code
1533 authority_view a( "www.example.com" );
1534
1535 std::cout << a << std::endl;
1536 @endcode
1537
1538 @return A reference to the output stream, for chaining
1539
1540 @param os The output stream to write to
1541
1542 @param a The URL to write
1543 */
1544 std::ostream&
1545 operator<<(
1546 std::ostream& os,
1547 authority_view const& a);
1548
1549 //------------------------------------------------
1550
1551 /** Parse an authority
1552
1553 This function parses a string according to
1554 the authority grammar below, and returns an
1555 @ref authority_view referencing the string.
1556 Ownership of the string is not transferred;
1557 the caller is responsible for ensuring that
1558 the lifetime of the string extends until the
1559 view is no longer being accessed.
1560
1561 @par BNF
1562 @code
1563 authority = [ userinfo "@" ] host [ ":" port ]
1564
1565 userinfo = user [ ":" [ password ] ]
1566
1567 user = *( unreserved / pct-encoded / sub-delims )
1568 password = *( unreserved / pct-encoded / sub-delims / ":" )
1569
1570 host = IP-literal / IPv4address / reg-name
1571
1572 port = *DIGIT
1573 @endcode
1574
1575 @par Exception Safety
1576 Throws nothing.
1577
1578 @return A view to the parsed authority
1579
1580 @param s The string to parse
1581
1582 @par Specification
1583 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2"
1584 >3.2. Authority (rfc3986)</a>
1585
1586 @see
1587 @ref authority_view.
1588 */
1589 BOOST_URL_CXX20_CONSTEXPR
1590 system::result<authority_view>
1591 parse_authority(
1592 core::string_view s) noexcept;
1593
1594 } // urls
1595 } // boost
1596
1597 // When rfc/authority_rule.hpp is being processed,
1598 // it will include impl/authority_view.hpp itself
1599 // after declaring authority_rule.
1600 #if !defined(BOOST_URL_RFC_AUTHORITY_RULE_HPP)
1601 #include <boost/url/impl/authority_view.hpp>
1602 #endif
1603
1604 #endif
1605