GCC Code Coverage Report

Directory: libs/url/
File: include/boost/url/authority_view.hpp
Date: 2025-04-22 15:26:26
Exec Total Coverage
Lines: 32 32 100.0%
Functions: 10 10 100.0%
Branches: 4 8 50.0%
Line Branch Exec Source
1 //
2 // Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
3 //
4 // Distributed under the Boost Software License, Version 1.0. (See accompanying
5 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6 //
7 // Official repository: https://github.com/boostorg/url
8 //
9
10 #ifndef BOOST_URL_AUTHORITY_VIEW_HPP
11 #define BOOST_URL_AUTHORITY_VIEW_HPP
12
13 #include <boost/url/detail/config.hpp>
14 #include <boost/url/host_type.hpp>
15 #include <boost/url/ipv4_address.hpp>
16 #include <boost/url/ipv6_address.hpp>
17 #include <boost/url/pct_string_view.hpp>
18 #include <boost/url/detail/except.hpp>
19 #include <boost/url/detail/url_impl.hpp>
20 #include <boost/assert.hpp>
21 #include <cstddef>
22 #include <iosfwd>
23 #include <utility>
24
25 namespace boost {
26 namespace urls {
27
28 /** A non-owning reference to a valid authority
29
30 Objects of this type represent valid authority
31 strings constructed from a parsed, external
32 character buffer whose storage is managed
33 by the caller. That is, it acts like a
34 `core::string_view` in terms of ownership.
35 The caller is responsible for ensuring
36 that the lifetime of the underlying
37 character buffer extends until it is no
38 longer referenced.
39
40 @par Example 1
41 Construction from a string parses the input
42 as an <em>authority</em> and throws an
43 exception on error. Upon success, the
44 constructed object points to the passed
45 character buffer; ownership is not
46 transferred.
47 @code
48 authority_view a( "user:pass@www.example.com:8080" );
49 @endcode
50
51 @par Example 2
52 The parsing function @ref parse_authority returns
53 a `boost::system::result` containing either a valid
54 @ref authority_view upon succcess, otherwise it
55 contain an error. The error can be converted to
56 an exception by the caller if desired:
57 @code
58 system::result< authority_view > rv = parse_authority( "user:pass@www.example.com:8080" );
59 @endcode
60
61 @par BNF
62 @code
63 authority = [ userinfo "@" ] host [ ":" port ]
64
65 userinfo = user [ ":" [ password ] ]
66
67 user = *( unreserved / pct-encoded / sub-delims )
68 password = *( unreserved / pct-encoded / sub-delims / ":" )
69
70 host = IP-literal / IPv4address / reg-name
71
72 port = *DIGIT
73 @endcode
74
75 @par Specification
76 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2"
77 >3.2. Authority (rfc3986)</a>
78
79 @see
80 @ref parse_authority.
81 */
82 class BOOST_URL_DECL
83 authority_view
84 : private detail::parts_base
85 {
86 detail::url_impl u_;
87
88 #ifndef BOOST_URL_DOCS
89 // VFALCO docca emits this erroneously
90 friend struct detail::url_impl;
91 #endif
92
93 explicit
94 authority_view(
95 detail::url_impl const& u) noexcept;
96
97 public:
98 //--------------------------------------------
99 //
100 // Special Members
101 //
102 //--------------------------------------------
103
104 /** Destructor
105 */
106 virtual
107 ~authority_view();
108
109 /** Constructor
110
111 Default constructed authorities
112 refer to a string with zero length,
113 which is always valid. This matches
114 the grammar for a zero-length host.
115
116 @par Exception Safety
117 Throws nothing.
118
119 @par Specification
120 */
121 authority_view() noexcept;
122
123 /** Construct from a string.
124
125 This function attempts to construct
126 an authority from the string `s`,
127 which must be a valid ['authority] or
128 else an exception is thrown. Upon
129 successful construction, the view
130 refers to the characters in the
131 buffer pointed to by `s`.
132 Ownership is not transferred; The
133 caller is responsible for ensuring
134 that the lifetime of the buffer
135 extends until the view is destroyed.
136
137 @param s The string to parse
138
139 @par BNF
140 @code
141 authority = [ userinfo "@" ] host [ ":" port ]
142
143 userinfo = user [ ":" [ password ] ]
144
145 user = *( unreserved / pct-encoded / sub-delims )
146 password = *( unreserved / pct-encoded / sub-delims / ":" )
147
148 host = IP-literal / IPv4address / reg-name
149
150 port = *DIGIT
151 @endcode
152
153 @par Specification
154 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2"
155 >3.2. Authority (rfc3986)</a>
156
157 @see
158 @ref parse_authority.
159 */
160 explicit
161 authority_view(core::string_view s);
162
163 /** Constructor
164 */
165 authority_view(
166 authority_view const&) noexcept;
167
168 /** Assignment
169
170 This function assigns the contents of
171 `other` to this object.
172
173 @param other The object to assign
174 @return A reference to this object
175
176 @par Exception Safety
177 Throws nothing.
178 */
179 authority_view&
180 operator=(
181 authority_view const& other) noexcept;
182
183 //--------------------------------------------
184 //
185 // Observers
186 //
187 //--------------------------------------------
188
189 /** Return the number of characters in the authority
190
191 This function returns the number of
192 characters in the authority.
193
194 @return The number of characters in the authority
195
196 @par Example
197 @code
198 assert( authority_view( "user:pass@www.example.com:8080" ).size() == 30 );
199 @endcode
200
201 @par Exception Safety
202 Throws nothing.
203 */
204 std::size_t
205 24 size() const noexcept
206 {
207 24 return u_.offset(id_end);
208 }
209
210 /** Return true if the authority is empty
211
212 An empty authority has an empty host,
213 no userinfo, and no port.
214
215 @return `true` if the authority is empty
216
217 @par Example
218 @code
219 assert( authority_view( "" ).empty() );
220 @endcode
221
222 @par Exception Safety
223 Throws nothing.
224 */
225 bool
226 3 empty() const noexcept
227 {
228 3 return size() == 0;
229 }
230
231 /** Return a pointer to the first character
232
233 This function returns a pointer to the
234 beginning of the view, which is not
235 guaranteed to be null-terminated.
236
237 @return A pointer to the first character
238
239 @par Exception Safety
240 Throws nothing.
241 */
242 char const*
243 20 data() const noexcept
244 {
245 20 return u_.cs_;
246 }
247
248 /** Return the complete authority
249
250 This function returns the authority
251 as a percent-encoded string.
252
253 @return The complete authority
254
255 @par Example
256 @code
257 assert( parse_authority( "www.example.com" ).value().buffer() == "www.example.com" );
258 @endcode
259
260 @par BNF
261 @code
262 authority = [ userinfo "@" ] host [ ":" port ]
263 @endcode
264
265 @par Exception Safety
266 Throws nothing.
267
268 @par Specification
269 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2"
270 >3.2. Authority (rfc3986)</a>
271 */
272 core::string_view
273 18 buffer() const noexcept
274 {
275 18 return core::string_view(data(), size());
276 }
277
278 //--------------------------------------------
279 //
280 // Userinfo
281 //
282 //--------------------------------------------
283
284 /** Return true if a userinfo is present
285
286 This function returns true if this
287 contains a userinfo.
288
289 @return `true` if a userinfo is present
290
291 @par Example
292 @code
293 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_userinfo() );
294 @endcode
295
296 @par Complexity
297 Constant.
298
299 @par Exception Safety
300 Throws nothing.
301
302 @par BNF
303 @code
304 userinfo = user [ ":" [ password ] ]
305
306 authority = [ userinfo "@" ] host [ ":" port ]
307 @endcode
308
309 @par Specification
310 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
311 >3.2.1. User Information (rfc3986)</a>
312
313 @see
314 @ref has_password,
315 @ref encoded_password,
316 @ref encoded_user,
317 @ref encoded_userinfo,
318 @ref password,
319 @ref user,
320 @ref userinfo.
321
322 */
323 bool
324 has_userinfo() const noexcept;
325
326 /** Return the userinfo
327
328 If present, this function returns a
329 string representing the userinfo (which
330 may be empty).
331 Otherwise it returns an empty string.
332 Any percent-escapes in the string are
333 decoded first.
334
335 @param token A string token to receive the result.
336 @return The userinfo
337
338 @par Example
339 @code
340 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).userinfo() == "jane-doe:pass" );
341 @endcode
342
343 @par Complexity
344 Linear in `this->userinfo().size()`.
345
346 @par Exception Safety
347 Calls to allocate may throw.
348
349 @par BNF
350 @code
351 userinfo = user [ ":" [ password ] ]
352
353 authority = [ userinfo "@" ] host [ ":" port ]
354 @endcode
355
356 @par Specification
357 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
358 >3.2.1. User Information (rfc3986)</a>
359
360 @see
361 @ref has_password,
362 @ref has_userinfo,
363 @ref encoded_password,
364 @ref encoded_user,
365 @ref encoded_userinfo,
366 @ref password,
367 @ref user.
368 */
369 template<BOOST_URL_STRTOK_TPARAM>
370 BOOST_URL_STRTOK_RETURN
371 23 userinfo(
372 BOOST_URL_STRTOK_ARG(token)) const
373 {
374 23 encoding_opts opt;
375 23 opt.space_as_plus = false;
376 46 return encoded_userinfo().decode(
377
1/2
✓ Branch 2 taken 23 times.
✗ Branch 3 not taken.
 46 opt, std::move(token));
378 }
379
380 /** Return the userinfo
381
382 If present, this function returns a
383 string representing the userinfo (which
384 may be empty).
385 Otherwise it returns an empty string.
386 The returned string may contain
387 percent escapes.
388
389 @return The userinfo
390
391 @par Example
392 @code
393 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_userinfo() == "jane%2Ddoe:pass" );
394 @endcode
395
396 @par Complexity
397 Constant.
398
399 @par Exception Safety
400 Throws nothing
401
402 @par BNF
403 @code
404 userinfo = user [ ":" [ password ] ]
405
406 authority = [ userinfo "@" ] host [ ":" port ]
407 @endcode
408
409 @par Specification
410 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
411 >3.2.1. User Information (rfc3986)</a>
412
413 @see
414 @ref has_password,
415 @ref has_userinfo,
416 @ref encoded_password,
417 @ref encoded_user,
418 @ref password,
419 @ref user,
420 @ref userinfo.
421 */
422 pct_string_view
423 encoded_userinfo() const noexcept;
424
425 //--------------------------------------------
426
427 /** Return the user
428
429 If present, this function returns a
430 string representing the user (which
431 may be empty).
432 Otherwise it returns an empty string.
433 Any percent-escapes in the string are
434 decoded first.
435
436 @param token A string token to receive the result.
437 @return The user
438
439 @par Example
440 @code
441 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).user() == "jane-doe" );
442 @endcode
443
444 @par Complexity
445 Linear in `this->user().size()`.
446
447 @par Exception Safety
448 Calls to allocate may throw.
449
450 @par BNF
451 @code
452 userinfo = user [ ":" [ password ] ]
453
454 user = *( unreserved / pct-encoded / sub-delims )
455 password = *( unreserved / pct-encoded / sub-delims / ":" )
456 @endcode
457
458 @par Specification
459 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
460 >3.2.1. User Information (rfc3986)</a>
461
462 @see
463 @ref has_password,
464 @ref has_userinfo,
465 @ref encoded_password,
466 @ref encoded_user,
467 @ref encoded_userinfo,
468 @ref password,
469 @ref userinfo.
470 */
471 template<BOOST_URL_STRTOK_TPARAM>
472 BOOST_URL_STRTOK_RETURN
473 12 user(
474 BOOST_URL_STRTOK_ARG(token)) const
475 {
476 12 encoding_opts opt;
477 12 opt.space_as_plus = false;
478 24 return encoded_user().decode(
479
1/2
✓ Branch 2 taken 12 times.
✗ Branch 3 not taken.
 24 opt, std::move(token));
480 }
481
482 /** Return the user
483
484 If present, this function returns a
485 string representing the user (which
486 may be empty).
487 Otherwise it returns an empty string.
488 The returned string may contain
489 percent escapes.
490
491 @return The user
492
493 @par Example
494 @code
495 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_user() == "jane%2Ddoe" );
496 @endcode
497
498 @par Complexity
499 Constant.
500
501 @par Exception Safety
502 Throws nothing.
503
504 @par BNF
505 @code
506 userinfo = user [ ":" [ password ] ]
507
508 user = *( unreserved / pct-encoded / sub-delims )
509 password = *( unreserved / pct-encoded / sub-delims / ":" )
510 @endcode
511
512 @par Specification
513 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
514 >3.2.1. User Information (rfc3986)</a>
515
516 @see
517 @ref has_password,
518 @ref has_userinfo,
519 @ref encoded_password,
520 @ref encoded_userinfo,
521 @ref password,
522 @ref user,
523 @ref userinfo.
524 */
525 pct_string_view
526 encoded_user() const noexcept;
527
528 /** Return true if a password is present
529
530 This function returns true if the
531 userinfo is present and contains
532 a password.
533
534 @return `true` if a password is present
535
536 @par Example
537 @code
538 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_password() );
539 @endcode
540
541 @par Complexity
542 Constant.
543
544 @par Exception Safety
545 Throws nothing.
546
547 @par BNF
548 @code
549 userinfo = user [ ":" [ password ] ]
550
551 user = *( unreserved / pct-encoded / sub-delims )
552 password = *( unreserved / pct-encoded / sub-delims / ":" )
553 @endcode
554
555 @par Specification
556 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
557 >3.2.1. User Information (rfc3986)</a>
558
559 @see
560 @ref has_userinfo,
561 @ref encoded_password,
562 @ref encoded_user,
563 @ref encoded_userinfo,
564 @ref password,
565 @ref user,
566 @ref userinfo.
567 */
568 bool
569 has_password() const noexcept;
570
571 /** Return the password
572
573 If present, this function returns a
574 string representing the password (which
575 may be an empty string).
576 Otherwise it returns an empty string.
577 Any percent-escapes in the string are
578 decoded first.
579
580 @param token A string token to receive the result.
581 @return The password
582
583 @par Example
584 @code
585 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).password() == "pass" );
586 @endcode
587
588 @par Complexity
589 Linear in `this->password().size()`.
590
591 @par Exception Safety
592 Calls to allocate may throw.
593
594 @par BNF
595 @code
596 userinfo = user [ ":" [ password ] ]
597
598 user = *( unreserved / pct-encoded / sub-delims )
599 password = *( unreserved / pct-encoded / sub-delims / ":" )
600 @endcode
601
602 @par Specification
603 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
604 >3.2.1. User Information (rfc3986)</a>
605
606 @see
607 @ref has_password,
608 @ref has_userinfo,
609 @ref encoded_password,
610 @ref encoded_user,
611 @ref encoded_userinfo,
612 @ref user,
613 @ref userinfo.
614 */
615 template<BOOST_URL_STRTOK_TPARAM>
616 BOOST_URL_STRTOK_RETURN
617 12 password(
618 BOOST_URL_STRTOK_ARG(token)) const
619 {
620 12 encoding_opts opt;
621 12 opt.space_as_plus = false;
622 24 return encoded_password().decode(
623
1/2
✓ Branch 2 taken 12 times.
✗ Branch 3 not taken.
 24 opt, std::move(token));
624 }
625
626 /** Return the password
627
628 This function returns the password portion
629 of the userinfo as a percent-encoded string.
630
631 @return The password
632
633 @par Example
634 @code
635 assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_password() == "pass" );
636 @endcode
637
638 @par Complexity
639 Constant.
640
641 @par Exception Safety
642 Throws nothing.
643
644 @par BNF
645 @code
646 userinfo = user [ ":" [ password ] ]
647
648 user = *( unreserved / pct-encoded / sub-delims )
649 password = *( unreserved / pct-encoded / sub-delims / ":" )
650 @endcode
651
652 @par Specification
653 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1"
654 >3.2.1. User Information (rfc3986)</a>
655
656 @see
657 @ref has_password,
658 @ref has_userinfo,
659 @ref encoded_user,
660 @ref encoded_userinfo,
661 @ref password,
662 @ref user,
663 @ref userinfo.
664 */
665 pct_string_view
666 encoded_password() const noexcept;
667
668 //--------------------------------------------
669 //
670 // Host
671 //
672 //--------------------------------------------
673
674 /** Return the host type
675
676 This function returns one of the
677 following constants representing the
678 type of host present.
679
680 @li @ref host_type::ipv4
681 @li @ref host_type::ipv6
682 @li @ref host_type::ipvfuture
683 @li @ref host_type::name
684
685 @return The host type
686
687 @par Example
688 @code
689 assert( url_view( "https://192.168.0.1/local.htm" ).host_type() == host_type::ipv4 );
690 @endcode
691
692 @par Complexity
693 Constant.
694
695 @par Exception Safety
696 Throws nothing.
697
698 @par Specification
699 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
700 >3.2.2. Host (rfc3986)</a>
701 */
702 urls::host_type
703 8 host_type() const noexcept
704 {
705 8 return u_.host_type_;
706 }
707
708 /** Return the host
709
710 This function returns the host portion
711 of the authority as a string, or the
712 empty string if there is no authority.
713 Any percent-escapes in the string are
714 decoded first.
715
716 @param token A string token to receive the result.
717 @return The host
718
719 @par Example
720 @code
721 assert( url_view( "https://www%2droot.example.com/" ).host() == "www-root.example.com" );
722 @endcode
723
724 @par Complexity
725 Linear in `this->host().size()`.
726
727 @par Exception Safety
728 Calls to allocate may throw.
729
730 @par BNF
731 @code
732 host = IP-literal / IPv4address / reg-name
733
734 IP-literal = "[" ( IPv6address / IPvFuture ) "]"
735
736 reg-name = *( unreserved / pct-encoded / "-" / ".")
737 @endcode
738
739 @par Specification
740 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
741 >3.2.2. Host (rfc3986)</a>
742 */
743 template<BOOST_URL_STRTOK_TPARAM>
744 BOOST_URL_STRTOK_RETURN
745 4 host(
746 BOOST_URL_STRTOK_ARG(token)) const
747 {
748 4 encoding_opts opt;
749 4 opt.space_as_plus = false;
750 8 return encoded_host().decode(
751
1/2
✓ Branch 2 taken 4 times.
✗ Branch 3 not taken.
 8 opt, std::move(token));
752 }
753
754 /** Return the host
755
756 This function returns the host portion
757 of the authority as a string, or the
758 empty string if there is no authority.
759 The returned string may contain
760 percent escapes.
761
762 @return The host
763
764 @par Example
765 @code
766 assert( url_view( "https://www%2droot.example.com/" ).encoded_host() == "www%2droot.example.com" );
767 @endcode
768
769 @par Complexity
770 Constant.
771
772 @par Exception Safety
773 Throws nothing.
774
775 @par BNF
776 @code
777 host = IP-literal / IPv4address / reg-name
778
779 IP-literal = "[" ( IPv6address / IPvFuture ) "]"
780
781 reg-name = *( unreserved / pct-encoded / "-" / ".")
782 @endcode
783
784 @par Specification
785 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
786 >3.2.2. Host (rfc3986)</a>
787 */
788 pct_string_view
789 encoded_host() const noexcept;
790
791 /** Return the host
792
793 The value returned by this function
794 depends on the type of host returned
795 from the function @ref host_type.
796
797 @li If the type is @ref host_type::ipv4,
798 then the IPv4 address string is returned.
799
800 @li If the type is @ref host_type::ipv6,
801 then the IPv6 address string is returned,
802 without any enclosing brackets.
803
804 @li If the type is @ref host_type::ipvfuture,
805 then the IPvFuture address string is returned,
806 without any enclosing brackets.
807
808 @li If the type is @ref host_type::name,
809 then the host name string is returned.
810 Any percent-escapes in the string are
811 decoded first.
812
813 @li If the type is @ref host_type::none,
814 then an empty string is returned.
815
816 @param token A string token to receive the result.
817 @return The host address
818
819 @par Example
820 @code
821 assert( url_view( "https://[1::6:c0a8:1]/" ).host_address() == "1::6:c0a8:1" );
822 @endcode
823
824 @par Complexity
825 Linear in `this->host_address().size()`.
826
827 @par Exception Safety
828 Calls to allocate may throw.
829
830 @par BNF
831 @code
832 host = IP-literal / IPv4address / reg-name
833
834 IP-literal = "[" ( IPv6address / IPvFuture ) "]"
835
836 reg-name = *( unreserved / pct-encoded / "-" / ".")
837 @endcode
838
839 @par Specification
840 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
841 >3.2.2. Host (rfc3986)</a>
842 */
843 template<BOOST_URL_STRTOK_TPARAM>
844 BOOST_URL_STRTOK_RETURN
845 host_address(
846 BOOST_URL_STRTOK_ARG(token)) const
847 {
848 encoding_opts opt;
849 opt.space_as_plus = false;
850 return encoded_host_address().decode(
851 opt, std::move(token));
852 }
853
854 /** Return the host
855
856 The value returned by this function
857 depends on the type of host returned
858 from the function @ref host_type.
859
860 @li If the type is @ref host_type::ipv4,
861 then the IPv4 address string is returned.
862
863 @li If the type is @ref host_type::ipv6,
864 then the IPv6 address string is returned,
865 without any enclosing brackets.
866
867 @li If the type is @ref host_type::ipvfuture,
868 then the IPvFuture address string is returned,
869 without any enclosing brackets.
870
871 @li If the type is @ref host_type::name,
872 then the host name string is returned.
873 Any percent-escapes in the string are
874 decoded first.
875
876 @li If the type is @ref host_type::none,
877 then an empty string is returned.
878 The returned string may contain
879 percent escapes.
880
881 @return The host address
882
883 @par Example
884 @code
885 assert( url_view( "https://www%2droot.example.com/" ).encoded_host_address() == "www%2droot.example.com" );
886 @endcode
887
888 @par Complexity
889 Constant.
890
891 @par Exception Safety
892 Throws nothing.
893
894 @par BNF
895 @code
896 host = IP-literal / IPv4address / reg-name
897
898 IP-literal = "[" ( IPv6address / IPvFuture ) "]"
899
900 reg-name = *( unreserved / pct-encoded / "-" / ".")
901 @endcode
902
903 @par Specification
904 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
905 >3.2.2. Host (rfc3986)</a>
906 */
907 pct_string_view
908 encoded_host_address() const noexcept;
909
910 /** Return the host IPv4 address
911
912 If the host type is @ref host_type::ipv4,
913 this function returns the address as
914 a value of type @ref ipv4_address.
915 Otherwise, if the host type is not an IPv4
916 address, it returns a default-constructed
917 value which is equal to the unspecified
918 address "0.0.0.0".
919
920 @return The host IPv4 address
921
922 @par Example
923 @code
924 assert( url_view( "http://127.0.0.1/index.htm?user=win95" ).host_ipv4_address() == ipv4_address( "127.0.0.1" ) );
925 @endcode
926
927 @par Complexity
928 Constant.
929
930 @par Exception Safety
931 Throws nothing.
932
933 @par BNF
934 @code
935 IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
936
937 dec-octet = DIGIT ; 0-9
938 / %x31-39 DIGIT ; 10-99
939 / "1" 2DIGIT ; 100-199
940 / "2" %x30-34 DIGIT ; 200-249
941 / "25" %x30-35 ; 250-255
942 @endcode
943
944 @par Specification
945 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
946 >3.2.2. Host (rfc3986)</a>
947 */
948 ipv4_address
949 host_ipv4_address() const noexcept;
950
951 /** Return the host IPv6 address
952
953 If the host type is @ref host_type::ipv6,
954 this function returns the address as
955 a value of type @ref ipv6_address.
956 Otherwise, if the host type is not an IPv6
957 address, it returns a default-constructed
958 value which is equal to the unspecified
959 address "0:0:0:0:0:0:0:0".
960
961 @return The host IPv6 address
962
963 @par Example
964 @code
965 assert( url_view( "ftp://[::1]/" ).host_ipv6_address() == ipv6_address( "::1" ) );
966 @endcode
967
968 @par Complexity
969 Constant.
970
971 @par Exception Safety
972 Throws nothing.
973
974 @par BNF
975 @code
976 IPv6address = 6( h16 ":" ) ls32
977 / "::" 5( h16 ":" ) ls32
978 / [ h16 ] "::" 4( h16 ":" ) ls32
979 / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
980 / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
981 / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32
982 / [ *4( h16 ":" ) h16 ] "::" ls32
983 / [ *5( h16 ":" ) h16 ] "::" h16
984 / [ *6( h16 ":" ) h16 ] "::"
985
986 ls32 = ( h16 ":" h16 ) / IPv4address
987 ; least-significant 32 bits of address
988
989 h16 = 1*4HEXDIG
990 ; 16 bits of address represented in hexadecimal
991 @endcode
992
993 @par Specification
994 @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2"
995 >3.2.2. Host (rfc3986)</a>
996 */
997 ipv6_address
998 host_ipv6_address() const noexcept;
999
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 1 operator<<(
1473 std::ostream& os,
1474 authority_view const& a)
1475 {
1476 1 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
1554