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