GCC Code Coverage Report

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