GCC Code Coverage Report

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