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_URL_VIEW_BASE_HPP
12 : #define BOOST_URL_URL_VIEW_BASE_HPP
13 :
14 : #include <boost/url/detail/config.hpp>
15 : #include <boost/url/authority_view.hpp>
16 : #include <boost/url/host_type.hpp>
17 : #include <boost/url/ipv4_address.hpp>
18 : #include <boost/url/ipv6_address.hpp>
19 : #include <boost/url/params_view.hpp>
20 : #include <boost/url/params_encoded_view.hpp>
21 : #include <boost/url/pct_string_view.hpp>
22 : #include <boost/url/scheme.hpp>
23 : #include <boost/url/segments_encoded_view.hpp>
24 : #include <boost/url/segments_view.hpp>
25 : #include <boost/url/detail/url_impl.hpp>
26 : #include <boost/url/grammar/string_token.hpp>
27 : #include <boost/assert.hpp>
28 : #include <cstddef>
29 : #include <cstdint>
30 : #include <iosfwd>
31 : #include <memory>
32 : #include <string>
33 : #include <utility>
34 :
35 : namespace boost {
36 : namespace urls {
37 :
38 : #ifndef BOOST_URL_DOCS
39 : namespace detail {
40 : struct pattern;
41 : }
42 : #endif
43 :
44 :
45 : /** Common functionality for containers
46 :
47 : This base class is used by the library
48 : to provide common member functions for
49 : containers. This cannot be instantiated
50 : directly; Instead, use one of the
51 : containers or functions:
52 :
53 : @par Containers
54 : @li @ref url
55 : @li @ref url_view
56 : @li @ref static_url
57 :
58 : @par Functions
59 : @li @ref parse_absolute_uri
60 : @li @ref parse_origin_form
61 : @li @ref parse_relative_ref
62 : @li @ref parse_uri
63 : @li @ref parse_uri_reference
64 : */
65 : class url_view_base
66 : : private detail::parts_base
67 : {
68 : detail::url_impl impl_;
69 : detail::url_impl const* external_impl_;
70 :
71 : friend class url;
72 : friend class url_base;
73 : friend class url_view;
74 : friend class static_url_base;
75 : friend class params_base;
76 : friend class params_encoded_base;
77 : friend class params_encoded_ref;
78 : friend class params_encoded_view;
79 : friend class params_ref;
80 : friend class params_view;
81 : friend class segments_base;
82 : friend class segments_encoded_base;
83 : friend class segments_encoded_ref;
84 : friend class segments_encoded_view;
85 : friend class segments_ref;
86 : friend class segments_view;
87 : friend struct detail::pattern;
88 :
89 : struct shared_impl;
90 :
91 : // Returns reference to the active implementation.
92 : // Uses external_impl_ if set, otherwise local impl_.
93 : BOOST_URL_CXX14_CONSTEXPR
94 : detail::url_impl const&
95 113283 : impl() const noexcept
96 : {
97 113283 : return external_impl_ ? *external_impl_ : impl_;
98 : }
99 :
100 : BOOST_URL_CXX14_CONSTEXPR
101 4179 : url_view_base() noexcept
102 4179 : : impl_(detail::url_impl::from::url)
103 4179 : , external_impl_(nullptr)
104 : {
105 4179 : }
106 :
107 : BOOST_URL_CXX14_CONSTEXPR
108 5379 : explicit url_view_base(
109 : detail::url_impl const& impl) noexcept
110 5379 : : impl_(impl)
111 5379 : , external_impl_(nullptr)
112 : {
113 5379 : }
114 :
115 : ~url_view_base() = default;
116 :
117 : BOOST_URL_CXX14_CONSTEXPR
118 : url_view_base(
119 : url_view_base const& o) noexcept = default;
120 :
121 : BOOST_URL_CXX14_CONSTEXPR
122 : url_view_base(
123 : url_view_base&& o) noexcept = default;
124 :
125 : url_view_base& operator=(
126 : url_view_base const&) = delete;
127 :
128 : protected:
129 : /** Calculate a hash of the url
130 :
131 : This function calculates a hash of the
132 : url as if it were always normalized.
133 :
134 : @par Complexity
135 : Linear in `this->size()`.
136 :
137 : @par Exception Safety
138 : Throws nothing.
139 :
140 : @param salt An initial value to add to
141 : the hash
142 :
143 : @return A hash value suitable for use
144 : in hash-based containers.
145 : */
146 : std::size_t
147 : digest(std::size_t salt = 0) const noexcept;
148 :
149 : public:
150 : //--------------------------------------------
151 : //
152 : // Observers
153 : //
154 : //--------------------------------------------
155 :
156 : /** Return the maximum number of characters possible
157 :
158 : This represents the largest number
159 : of characters that are theoretically
160 : possible to represent in a url,
161 : not including any null terminator.
162 : In practice the actual possible size
163 : may be lower than this number.
164 :
165 : @par Complexity
166 : Constant.
167 :
168 : @par Exception Safety
169 : Throws nothing.
170 :
171 : @return The maximum number of characters.
172 : */
173 : static
174 : constexpr
175 : std::size_t
176 8581 : max_size() noexcept
177 : {
178 8581 : return BOOST_URL_MAX_SIZE;
179 : }
180 :
181 : /** Return the number of characters in the url
182 :
183 : This function returns the number of
184 : characters in the url's encoded string,
185 : not including any null terminator,
186 : if present.
187 :
188 : @par Example
189 : @code
190 : assert( url_view( "file:///Program%20Files" ).size() == 23 );
191 : @endcode
192 :
193 : @par Complexity
194 : Constant.
195 :
196 : @par Exception Safety
197 : Throws nothing.
198 :
199 : @return The number of characters in the url.
200 : */
201 : std::size_t
202 41956 : size() const noexcept
203 : {
204 41956 : return impl().offset(id_end);
205 : }
206 :
207 : /** Return true if the url is empty
208 :
209 : The empty string matches the
210 : <em>relative-ref</em> grammar.
211 :
212 : @par Example
213 : @code
214 : assert( url_view( "" ).empty() );
215 : @endcode
216 :
217 : @par Complexity
218 : Constant.
219 :
220 : @par Exception Safety
221 : Throws nothing.
222 :
223 : @par BNF
224 : @code
225 : relative-ref = relative-part [ "?" query ] [ "#" fragment ]
226 :
227 : relative-part = "//" authority path-abempty
228 : / path-absolute
229 : / path-noscheme
230 : / path-empty
231 : @endcode
232 :
233 : @par Specification
234 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-4.2">4.2. Relative Reference (rfc3986)</a>
235 :
236 : @return `true` if the url is empty.
237 : */
238 : bool
239 12 : empty() const noexcept
240 : {
241 12 : return impl().offset(id_end) == 0;
242 : }
243 :
244 : /** Return a pointer to the url's character buffer
245 :
246 : This function returns a pointer to
247 : the first character of the url, which
248 : is not guaranteed to be null-terminated.
249 :
250 : @par Complexity
251 : Constant.
252 :
253 : @par Exception Safety
254 : Throws nothing.
255 :
256 : @return A pointer to the first character.
257 : */
258 : char const*
259 5000 : data() const noexcept
260 : {
261 5000 : return impl().cs_;
262 : }
263 :
264 : /** Return the url string
265 :
266 : This function returns the entire url,
267 : which may contain percent escapes.
268 :
269 : @par Example
270 : @code
271 : assert( url_view( "http://www.example.com" ).buffer() == "http://www.example.com" );
272 : @endcode
273 :
274 : @par Complexity
275 : Constant.
276 :
277 : @par Exception Safety
278 : Throws nothing.
279 :
280 : @return The url as a string.
281 : */
282 : core::string_view
283 1368 : buffer() const noexcept
284 : {
285 1368 : return core::string_view(
286 1368 : data(), size());
287 : }
288 :
289 : /** Return the URL as a core::string_view
290 :
291 : @par Complexity
292 : Constant.
293 :
294 : @par Exception Safety
295 : Throws nothing.
296 :
297 : @return A string view of the URL.
298 : */
299 250 : operator core::string_view() const noexcept
300 : {
301 250 : return buffer();
302 : }
303 :
304 : /** Return a shared, persistent copy of the url
305 :
306 : This function returns a read-only copy of
307 : the url, with shared lifetime. The returned
308 : value owns (persists) the underlying string.
309 : The algorithm used to create the value
310 : minimizes the number of individual memory
311 : allocations, making it more efficient than
312 : when using direct standard library functions.
313 :
314 : @par Example
315 : @code
316 : std::shared_ptr< url_view const > sp;
317 : {
318 : std::string s( "http://example.com" );
319 : url_view u( s ); // u references characters in s
320 :
321 : assert( u.data() == s.data() ); // same buffer
322 :
323 : sp = u.persist();
324 :
325 : assert( sp->data() != s.data() ); // different buffer
326 : assert( sp->buffer() == s); // same contents
327 :
328 : // s is destroyed and thus u
329 : // becomes invalid, but sp remains valid.
330 : }
331 : @endcode
332 :
333 : @par Complexity
334 : Linear in `this->size()`.
335 :
336 : @par Exception Safety
337 : Calls to allocate may throw.
338 :
339 : @return A shared pointer to a read-only url_view.
340 : */
341 : std::shared_ptr<
342 : url_view const> persist() const;
343 :
344 : //--------------------------------------------
345 : //
346 : // Scheme
347 : //
348 : //--------------------------------------------
349 :
350 : /** Return true a scheme is present
351 :
352 : This function returns true if this
353 : contains a scheme.
354 :
355 : @par Example
356 : @code
357 : assert( url_view( "http://www.example.com" ).has_scheme() );
358 : @endcode
359 :
360 : @par Complexity
361 : Constant.
362 :
363 : @par Exception Safety
364 : Throws nothing.
365 :
366 : @par BNF
367 : @code
368 : URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
369 :
370 : absolute-URI = scheme ":" hier-part [ "?" query ]
371 :
372 : scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
373 : @endcode
374 :
375 : @par Specification
376 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.1">3.1. Scheme (rfc3986)</a>
377 :
378 : @see
379 : @ref scheme,
380 : @ref scheme_id.
381 :
382 : @return `true` if the url contains a scheme.
383 : */
384 : bool
385 : has_scheme() const noexcept;
386 :
387 : /** Return the scheme
388 :
389 : This function returns the scheme if it
390 : exists, without a trailing colon (':').
391 : Otherwise it returns an empty string.
392 : Note that schemes are case-insensitive,
393 : and the canonical form is lowercased.
394 :
395 : @par Example
396 : @code
397 : assert( url_view( "http://www.example.com" ).scheme() == "http" );
398 : @endcode
399 :
400 : @par Exception Safety
401 : Throws nothing.
402 :
403 : @par BNF
404 : @code
405 : scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
406 :
407 : URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
408 :
409 : absolute-URI = scheme ":" hier-part [ "?" query ]
410 : @endcode
411 :
412 : @par Specification
413 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.1">3.1. Scheme (rfc3986)</a>
414 :
415 : @see
416 : @ref has_scheme,
417 : @ref scheme_id.
418 :
419 : @return The scheme as a string.
420 : */
421 : core::string_view
422 : scheme() const noexcept;
423 :
424 : /** Return the scheme
425 :
426 : This function returns a value which
427 : depends on the scheme in the url:
428 :
429 : @li If the scheme is a well-known
430 : scheme, corresponding value from
431 : the enumeration @ref urls::scheme
432 : is returned.
433 :
434 : @li If a scheme is present but is not
435 : a well-known scheme, the value
436 : returned is @ref urls::scheme::unknown.
437 :
438 : @li Otherwise, if the scheme is absent
439 : the value returned is
440 : @ref urls::scheme::none.
441 :
442 : @par Example
443 : @code
444 : assert( url_view( "wss://www.example.com/crypto.cgi" ).scheme_id() == scheme::wss );
445 : @endcode
446 :
447 : @par Complexity
448 : Constant.
449 :
450 : @par Exception Safety
451 : Throws nothing.
452 :
453 : @par BNF
454 : @code
455 : URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
456 :
457 : absolute-URI = scheme ":" hier-part [ "?" query ]
458 :
459 : scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
460 : @endcode
461 :
462 : @par Specification
463 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.1">3.1. Scheme (rfc3986)</a>
464 :
465 : @see
466 : @ref has_scheme,
467 : @ref scheme.
468 :
469 : @return The scheme as an enumeration value.
470 : */
471 : urls::scheme
472 : scheme_id() const noexcept;
473 :
474 : //--------------------------------------------
475 : //
476 : // Authority
477 : //
478 : //--------------------------------------------
479 :
480 : /** Return true if an authority is present
481 :
482 : This function returns true if the url
483 : contains an authority. The presence of
484 : an authority is denoted by a double
485 : slash ("//") at the beginning or after
486 : the scheme.
487 :
488 : @par Example
489 : @code
490 : assert( url_view( "http://www.example.com/index.htm" ).has_authority() );
491 : @endcode
492 :
493 : @par Complexity
494 : Constant.
495 :
496 : @par Exception Safety
497 : Throws nothing.
498 :
499 : @par BNF
500 : @code
501 : authority = [ userinfo "@" ] host [ ":" port ]
502 :
503 : URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
504 :
505 : absolute-URI = scheme ":" hier-part [ "?" query ]
506 :
507 : URI-reference = URI / relative-ref
508 :
509 : relative-ref = relative-part [ "?" query ] [ "#" fragment ]
510 :
511 : hier-part = "//" authority path-abempty
512 : ; (more...)
513 :
514 : relative-part = "//" authority path-abempty
515 : ; (more...)
516 :
517 : @endcode
518 :
519 : @par Specification
520 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2">3.2. Authority (rfc3986)</a>
521 :
522 : @see
523 : @ref authority,
524 : @ref encoded_authority.
525 :
526 : @return `true` if the url contains an authority.
527 : */
528 : bool
529 4988 : has_authority() const noexcept
530 : {
531 4988 : return impl().len(id_user) > 0;
532 : }
533 :
534 : /** Return the authority
535 :
536 : This function returns the authority as
537 : an @ref authority_view.
538 :
539 : @par Example
540 : @code
541 : authority_view a = url_view( "https://www.example.com:8080/index.htm" ).authority();
542 : @endcode
543 :
544 : @par Complexity
545 : Constant.
546 :
547 : @par Exception Safety
548 : Throws nothing.
549 :
550 : @par BNF
551 : @code
552 : authority = [ userinfo "@" ] host [ ":" port ]
553 : @endcode
554 :
555 : @par Specification
556 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2">3.2. Authority (rfc3986)</a>
557 :
558 : @see
559 : @ref encoded_authority,
560 : @ref has_authority.
561 :
562 : @return An authority_view representing the authority.
563 : */
564 : authority_view
565 : authority() const noexcept;
566 :
567 : /** Return the authority.
568 :
569 : If present, this function returns a
570 : string representing the authority (which
571 : may be empty).
572 : Otherwise it returns an empty string.
573 : The returned string may contain
574 : percent escapes.
575 :
576 : @par Example
577 : @code
578 : assert( url_view( "file://Network%20Drive/My%2DFiles" ).encoded_authority() == "Network%20Drive" );
579 : @endcode
580 :
581 : @par Complexity
582 : Constant.
583 :
584 : @par Exception Safety
585 : Throws nothing.
586 :
587 : @par BNF
588 : @code
589 : authority = [ userinfo "@" ] host [ ":" port ]
590 : @endcode
591 :
592 : @par Specification
593 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2">3.2. Authority (rfc3986)</a>
594 :
595 : @see
596 : @ref authority,
597 : @ref has_authority.
598 :
599 : @return The authority as a string.
600 : */
601 : pct_string_view
602 : encoded_authority() const noexcept;
603 :
604 : //--------------------------------------------
605 : //
606 : // Userinfo
607 : //
608 : //--------------------------------------------
609 :
610 : /** Return true if a userinfo is present
611 :
612 : This function returns true if this
613 : contains a userinfo.
614 :
615 : @par Example
616 : @code
617 : assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_userinfo() );
618 : @endcode
619 :
620 : @par Complexity
621 : Constant.
622 :
623 : @par Exception Safety
624 : Throws nothing.
625 :
626 : @par BNF
627 : @code
628 : userinfo = user [ ":" [ password ] ]
629 :
630 : authority = [ userinfo "@" ] host [ ":" port ]
631 : @endcode
632 :
633 : @par Specification
634 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">3.2.1. User Information (rfc3986)</a>
635 :
636 : @see
637 : @ref has_password,
638 : @ref encoded_password,
639 : @ref encoded_user,
640 : @ref encoded_userinfo,
641 : @ref password,
642 : @ref user,
643 : @ref userinfo.
644 :
645 : @return `true` if the userinfo is present.
646 : */
647 : bool
648 : has_userinfo() const noexcept;
649 :
650 : /** Return true if a password is present
651 :
652 : This function returns true if the
653 : userinfo is present and contains
654 : a password.
655 :
656 : @par Example
657 : @code
658 : assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_password() );
659 : @endcode
660 :
661 : @par Complexity
662 : Constant.
663 :
664 : @par Exception Safety
665 : Throws nothing.
666 :
667 : @par BNF
668 : @code
669 : userinfo = user [ ":" [ password ] ]
670 :
671 : user = *( unreserved / pct-encoded / sub-delims )
672 : password = *( unreserved / pct-encoded / sub-delims / ":" )
673 : @endcode
674 :
675 : @par Specification
676 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">3.2.1. User Information (rfc3986)</a>
677 :
678 : @see
679 : @ref has_userinfo,
680 : @ref encoded_password,
681 : @ref encoded_user,
682 : @ref encoded_userinfo,
683 : @ref password,
684 : @ref user,
685 : @ref userinfo.
686 :
687 : @return `true` if the userinfo contains a password.
688 : */
689 : bool
690 : has_password() const noexcept;
691 :
692 : /** Return the userinfo
693 :
694 : If present, this function returns a
695 : string representing the userinfo (which
696 : may be empty).
697 : Otherwise it returns an empty string.
698 : Any percent-escapes in the string are
699 : decoded first.
700 :
701 : @note
702 : This function uses the string token
703 : return type customization. Depending on
704 : the token passed, the return type and
705 : behavior of the function can be different.
706 : See @ref string_token::return_string
707 : for more information.
708 :
709 : @par Example
710 : @code
711 : assert( url_view( "http://jane%2Ddoe:pass@example.com" ).userinfo() == "jane-doe:pass" );
712 : @endcode
713 :
714 : @par Complexity
715 : Linear in `this->userinfo().size()`.
716 :
717 : @par Exception Safety
718 : Calls to allocate may throw.
719 :
720 : @return When called with no arguments,
721 : a value of type `std::string` is
722 : returned. Otherwise, the return type
723 : and meaning depends on the string token
724 : passed to the function.
725 :
726 : @par BNF
727 : @code
728 : userinfo = user [ ":" [ password ] ]
729 :
730 : authority = [ userinfo "@" ] host [ ":" port ]
731 : @endcode
732 :
733 : @par Specification
734 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">3.2.1. User Information (rfc3986)</a>
735 :
736 : @see
737 : @ref has_password,
738 : @ref has_userinfo,
739 : @ref encoded_password,
740 : @ref encoded_user,
741 : @ref encoded_userinfo,
742 : @ref password,
743 : @ref user.
744 :
745 : @param token The string token to use.
746 : @return The userinfo as a string.
747 : */
748 : template<BOOST_URL_STRTOK_TPARAM>
749 : BOOST_URL_STRTOK_RETURN
750 40 : userinfo(
751 : StringToken&& token = {}) const
752 : {
753 40 : encoding_opts opt;
754 40 : opt.space_as_plus = false;
755 80 : return encoded_userinfo().decode(
756 80 : opt, std::forward<StringToken>(token));
757 : }
758 :
759 : /** Return the userinfo
760 :
761 : If present, this function returns a
762 : string representing the userinfo (which
763 : may be empty).
764 : Otherwise it returns an empty string.
765 : The returned string may contain
766 : percent escapes.
767 :
768 : @par Example
769 : @code
770 : assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_userinfo() == "jane%2Ddoe:pass" );
771 : @endcode
772 :
773 : @par Complexity
774 : Constant.
775 :
776 : @par Exception Safety
777 : Throws nothing
778 :
779 : @par BNF
780 : @code
781 : userinfo = user [ ":" [ password ] ]
782 :
783 : authority = [ userinfo "@" ] host [ ":" port ]
784 : @endcode
785 :
786 : @par Specification
787 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">3.2.1. User Information (rfc3986)</a>
788 :
789 : @see
790 : @ref has_password,
791 : @ref has_userinfo,
792 : @ref encoded_password,
793 : @ref encoded_user,
794 : @ref password,
795 : @ref user,
796 : @ref userinfo.
797 :
798 : @return The userinfo as a string.
799 : */
800 : pct_string_view
801 : encoded_userinfo() const noexcept;
802 :
803 : //--------------------------------------------
804 :
805 : /** Return the user
806 :
807 : If present, this function returns a
808 : string representing the user (which
809 : may be empty).
810 : Otherwise it returns an empty string.
811 : Any percent-escapes in the string are
812 : decoded first.
813 :
814 : @par Example
815 : @code
816 : assert( url_view( "http://jane%2Ddoe:pass@example.com" ).user() == "jane-doe" );
817 : @endcode
818 :
819 : @par Complexity
820 : Linear in `this->user().size()`.
821 :
822 : @par Exception Safety
823 : Calls to allocate may throw.
824 :
825 : @par BNF
826 : @code
827 : userinfo = user [ ":" [ password ] ]
828 :
829 : user = *( unreserved / pct-encoded / sub-delims )
830 : password = *( unreserved / pct-encoded / sub-delims / ":" )
831 : @endcode
832 :
833 : @par Specification
834 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">3.2.1. User Information (rfc3986)</a>
835 :
836 : @see
837 : @ref has_password,
838 : @ref has_userinfo,
839 : @ref encoded_password,
840 : @ref encoded_user,
841 : @ref encoded_userinfo,
842 : @ref password,
843 : @ref userinfo.
844 :
845 : @param token The string token to use.
846 : @return The user as a string.
847 : */
848 : template<BOOST_URL_STRTOK_TPARAM>
849 : BOOST_URL_STRTOK_RETURN
850 58 : user(
851 : StringToken&& token = {}) const
852 : {
853 58 : encoding_opts opt;
854 58 : opt.space_as_plus = false;
855 116 : return encoded_user().decode(
856 116 : opt, std::forward<StringToken>(token));
857 : }
858 :
859 : /** Return the user
860 :
861 : If present, this function returns a
862 : string representing the user (which
863 : may be empty).
864 : Otherwise it returns an empty string.
865 : The returned string may contain
866 : percent escapes.
867 :
868 : @par Example
869 : @code
870 : assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_user() == "jane%2Ddoe" );
871 : @endcode
872 :
873 : @par Complexity
874 : Constant.
875 :
876 : @par Exception Safety
877 : Throws nothing.
878 :
879 : @par BNF
880 : @code
881 : userinfo = user [ ":" [ password ] ]
882 :
883 : user = *( unreserved / pct-encoded / sub-delims )
884 : password = *( unreserved / pct-encoded / sub-delims / ":" )
885 : @endcode
886 :
887 : @par Specification
888 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">3.2.1. User Information (rfc3986)</a>
889 :
890 : @see
891 : @ref has_password,
892 : @ref has_userinfo,
893 : @ref encoded_password,
894 : @ref encoded_userinfo,
895 : @ref password,
896 : @ref user,
897 : @ref userinfo.
898 :
899 : @return The user as a string.
900 : */
901 : pct_string_view
902 : encoded_user() const noexcept;
903 :
904 : /** Return the password
905 :
906 : If present, this function returns a
907 : string representing the password (which
908 : may be an empty string).
909 : Otherwise it returns an empty string.
910 : Any percent-escapes in the string are
911 : decoded first.
912 :
913 : @par Example
914 : @code
915 : assert( url_view( "http://jane%2Ddoe:pass@example.com" ).password() == "pass" );
916 : @endcode
917 :
918 : @par Complexity
919 : Linear in `this->password().size()`.
920 :
921 : @par Exception Safety
922 : Calls to allocate may throw.
923 :
924 : @par BNF
925 : @code
926 : userinfo = user [ ":" [ password ] ]
927 :
928 : user = *( unreserved / pct-encoded / sub-delims )
929 : password = *( unreserved / pct-encoded / sub-delims / ":" )
930 : @endcode
931 :
932 : @par Specification
933 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">3.2.1. User Information (rfc3986)</a>
934 :
935 : @see
936 : @ref has_password,
937 : @ref has_userinfo,
938 : @ref encoded_password,
939 : @ref encoded_user,
940 : @ref encoded_userinfo,
941 : @ref user,
942 : @ref userinfo.
943 :
944 : @param token The string token to use.
945 : @return The password as a string.
946 : */
947 : template<BOOST_URL_STRTOK_TPARAM>
948 : BOOST_URL_STRTOK_RETURN
949 28 : password(
950 : StringToken&& token = {}) const
951 : {
952 28 : encoding_opts opt;
953 28 : opt.space_as_plus = false;
954 56 : return encoded_password().decode(
955 56 : opt, std::forward<StringToken>(token));
956 : }
957 :
958 : /** Return the password
959 :
960 : This function returns the password portion
961 : of the userinfo as a percent-encoded string.
962 :
963 : @par Example
964 : @code
965 : assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_password() == "pass" );
966 : @endcode
967 :
968 : @par Complexity
969 : Constant.
970 :
971 : @par Exception Safety
972 : Throws nothing.
973 :
974 : @par BNF
975 : @code
976 : userinfo = user [ ":" [ password ] ]
977 :
978 : user = *( unreserved / pct-encoded / sub-delims )
979 : password = *( unreserved / pct-encoded / sub-delims / ":" )
980 : @endcode
981 :
982 : @par Specification
983 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1">3.2.1. User Information (rfc3986)</a>
984 :
985 : @see
986 : @ref has_password,
987 : @ref has_userinfo,
988 : @ref encoded_user,
989 : @ref encoded_userinfo,
990 : @ref password,
991 : @ref user,
992 : @ref userinfo.
993 :
994 : @return The password as a string.
995 : */
996 : pct_string_view
997 : encoded_password() const noexcept;
998 :
999 : //--------------------------------------------
1000 : //
1001 : // Host
1002 : //
1003 : //--------------------------------------------
1004 :
1005 : /** Return the host type
1006 :
1007 : This function returns one of the
1008 : following constants representing the
1009 : type of host present.
1010 :
1011 : @li @ref host_type::ipv4
1012 : @li @ref host_type::ipv6
1013 : @li @ref host_type::ipvfuture
1014 : @li @ref host_type::name
1015 : @li @ref host_type::none
1016 :
1017 : When @ref has_authority is false, the
1018 : host type is @ref host_type::none.
1019 :
1020 : @par Example
1021 : @code
1022 : assert( url_view( "https://192.168.0.1/local.htm" ).host_type() == host_type::ipv4 );
1023 : @endcode
1024 :
1025 : @par Complexity
1026 : Constant.
1027 :
1028 : @par Exception Safety
1029 : Throws nothing.
1030 :
1031 : @par Specification
1032 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">3.2.2. Host (rfc3986)</a>
1033 :
1034 : @return The type of host present.
1035 : */
1036 : urls::host_type
1037 456 : host_type() const noexcept
1038 : {
1039 456 : return impl().host_type_;
1040 : }
1041 :
1042 : /** Return the host
1043 :
1044 : This function returns the host portion
1045 : of the authority as a string, or the
1046 : empty string if there is no authority.
1047 : Any percent-escapes in the string are
1048 : decoded first.
1049 :
1050 : @par Example
1051 : @code
1052 : assert( url_view( "https://www%2droot.example.com/" ).host() == "www-root.example.com" );
1053 : @endcode
1054 :
1055 : @par Complexity
1056 : Linear in `this->host().size()`.
1057 :
1058 : @par Exception Safety
1059 : Calls to allocate may throw.
1060 :
1061 : @par BNF
1062 : @code
1063 : host = IP-literal / IPv4address / reg-name
1064 :
1065 : IP-literal = "[" ( IPv6address / IPvFuture ) "]"
1066 :
1067 : reg-name = *( unreserved / pct-encoded / "-" / ".")
1068 : @endcode
1069 :
1070 : @par Specification
1071 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">3.2.2. Host (rfc3986)</a>
1072 :
1073 : @param token A string token customization
1074 : @return The host address as a string.
1075 : */
1076 : template<BOOST_URL_STRTOK_TPARAM>
1077 : BOOST_URL_STRTOK_RETURN
1078 88 : host(
1079 : StringToken&& token = {}) const
1080 : {
1081 88 : encoding_opts opt;
1082 88 : opt.space_as_plus = false;
1083 176 : return encoded_host().decode(
1084 176 : opt, std::forward<StringToken>(token));
1085 : }
1086 :
1087 : /** Return the host
1088 :
1089 : This function returns the host portion
1090 : of the authority as a string, or the
1091 : empty string if there is no authority.
1092 : The returned string may contain
1093 : percent escapes.
1094 :
1095 : @par Example
1096 : @code
1097 : assert( url_view( "https://www%2droot.example.com/" ).encoded_host() == "www%2droot.example.com" );
1098 : @endcode
1099 :
1100 : @par Complexity
1101 : Constant.
1102 :
1103 : @par Exception Safety
1104 : Throws nothing.
1105 :
1106 : @par BNF
1107 : @code
1108 : host = IP-literal / IPv4address / reg-name
1109 :
1110 : IP-literal = "[" ( IPv6address / IPvFuture ) "]"
1111 :
1112 : reg-name = *( unreserved / pct-encoded / "-" / ".")
1113 : @endcode
1114 :
1115 : @par Specification
1116 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">3.2.2. Host (rfc3986)</a>
1117 :
1118 : @return The host address as a string.
1119 : */
1120 : pct_string_view
1121 : encoded_host() const noexcept;
1122 :
1123 : /** Return the host
1124 :
1125 : The value returned by this function
1126 : depends on the type of host returned
1127 : from the function @ref host_type.
1128 :
1129 : @li If the type is @ref host_type::ipv4,
1130 : then the IPv4 address string is returned.
1131 :
1132 : @li If the type is @ref host_type::ipv6,
1133 : then the IPv6 address string is returned,
1134 : without any enclosing brackets.
1135 :
1136 : @li If the type is @ref host_type::ipvfuture,
1137 : then the IPvFuture address string is returned,
1138 : without any enclosing brackets.
1139 :
1140 : @li If the type is @ref host_type::name,
1141 : then the host name string is returned.
1142 : Any percent-escapes in the string are
1143 : decoded first.
1144 :
1145 : @li If the type is @ref host_type::none,
1146 : then an empty string is returned.
1147 :
1148 : @par Example
1149 : @code
1150 : assert( url_view( "https://[1::6:c0a8:1]/" ).host_address() == "1::6:c0a8:1" );
1151 : @endcode
1152 :
1153 : @par Complexity
1154 : Linear in `this->host_address().size()`.
1155 :
1156 : @par Exception Safety
1157 : Calls to allocate may throw.
1158 :
1159 : @par BNF
1160 : @code
1161 : host = IP-literal / IPv4address / reg-name
1162 :
1163 : IP-literal = "[" ( IPv6address / IPvFuture ) "]"
1164 :
1165 : reg-name = *( unreserved / pct-encoded / "-" / ".")
1166 : @endcode
1167 :
1168 : @par Specification
1169 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">3.2.2. Host (rfc3986)</a>
1170 :
1171 : @param token A string token customization
1172 : @return The host address as a string.
1173 : */
1174 : template<BOOST_URL_STRTOK_TPARAM>
1175 : BOOST_URL_STRTOK_RETURN
1176 99 : host_address(
1177 : StringToken&& token = {}) const
1178 : {
1179 99 : encoding_opts opt;
1180 99 : opt.space_as_plus = false;
1181 198 : return encoded_host_address().decode(
1182 198 : opt, std::forward<StringToken>(token));
1183 : }
1184 :
1185 : /** Return the host
1186 :
1187 : The value returned by this function
1188 : depends on the type of host returned
1189 : from the function @ref host_type.
1190 :
1191 : @li If the type is @ref host_type::ipv4,
1192 : then the IPv4 address string is returned.
1193 :
1194 : @li If the type is @ref host_type::ipv6,
1195 : then the IPv6 address string is returned,
1196 : without any enclosing brackets.
1197 :
1198 : @li If the type is @ref host_type::ipvfuture,
1199 : then the IPvFuture address string is returned,
1200 : without any enclosing brackets.
1201 :
1202 : @li If the type is @ref host_type::name,
1203 : then the host name string is returned.
1204 : Any percent-escapes in the string are
1205 : decoded first.
1206 :
1207 : @li If the type is @ref host_type::none,
1208 : then an empty string is returned.
1209 : The returned string may contain
1210 : percent escapes.
1211 :
1212 : @par Example
1213 : @code
1214 : assert( url_view( "https://www%2droot.example.com/" ).encoded_host_address() == "www%2droot.example.com" );
1215 : @endcode
1216 :
1217 : @par Complexity
1218 : Constant.
1219 :
1220 : @par Exception Safety
1221 : Throws nothing.
1222 :
1223 : @par BNF
1224 : @code
1225 : host = IP-literal / IPv4address / reg-name
1226 :
1227 : IP-literal = "[" ( IPv6address / IPvFuture ) "]"
1228 :
1229 : reg-name = *( unreserved / pct-encoded / "-" / ".")
1230 : @endcode
1231 :
1232 : @par Specification
1233 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">3.2.2. Host (rfc3986)</a>
1234 :
1235 : @return The host address as a string.
1236 : */
1237 : pct_string_view
1238 : encoded_host_address() const noexcept;
1239 :
1240 : /** Return the host IPv4 address
1241 :
1242 : If the host type is @ref host_type::ipv4,
1243 : this function returns the address as
1244 : a value of type @ref ipv4_address.
1245 : Otherwise, if the host type is not an IPv4
1246 : address, it returns a default-constructed
1247 : value which is equal to the unspecified
1248 : address "0.0.0.0".
1249 :
1250 : @par Example
1251 : @code
1252 : assert( url_view( "http://127.0.0.1/index.htm?user=win95" ).host_ipv4_address() == ipv4_address( "127.0.0.1" ) );
1253 : @endcode
1254 :
1255 : @par Complexity
1256 : Constant.
1257 :
1258 : @par Exception Safety
1259 : Throws nothing.
1260 :
1261 : @par BNF
1262 : @code
1263 : IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet
1264 :
1265 : dec-octet = DIGIT ; 0-9
1266 : / %x31-39 DIGIT ; 10-99
1267 : / "1" 2DIGIT ; 100-199
1268 : / "2" %x30-34 DIGIT ; 200-249
1269 : / "25" %x30-35 ; 250-255
1270 : @endcode
1271 :
1272 : @par Specification
1273 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">3.2.2. Host (rfc3986)</a>
1274 :
1275 : @return The IPv4 address as a value of type @ref ipv4_address.
1276 : */
1277 : ipv4_address
1278 : host_ipv4_address() const noexcept;
1279 :
1280 : /** Return the host IPv6 address
1281 :
1282 : If the host type is @ref host_type::ipv6,
1283 : this function returns the address as
1284 : a value of type @ref ipv6_address.
1285 : Otherwise, if the host type is not an IPv6
1286 : address, it returns a default-constructed
1287 : value which is equal to the unspecified
1288 : address "0:0:0:0:0:0:0:0".
1289 :
1290 : @par Example
1291 : @code
1292 : assert( url_view( "ftp://[::1]/" ).host_ipv6_address() == ipv6_address( "::1" ) );
1293 : @endcode
1294 :
1295 : @par Complexity
1296 : Constant.
1297 :
1298 : @par Exception Safety
1299 : Throws nothing.
1300 :
1301 : @par BNF
1302 : @code
1303 : IPv6address = 6( h16 ":" ) ls32
1304 : / "::" 5( h16 ":" ) ls32
1305 : / [ h16 ] "::" 4( h16 ":" ) ls32
1306 : / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
1307 : / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
1308 : / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32
1309 : / [ *4( h16 ":" ) h16 ] "::" ls32
1310 : / [ *5( h16 ":" ) h16 ] "::" h16
1311 : / [ *6( h16 ":" ) h16 ] "::"
1312 :
1313 : ls32 = ( h16 ":" h16 ) / IPv4address
1314 : ; least-significant 32 bits of address
1315 :
1316 : h16 = 1*4HEXDIG
1317 : ; 16 bits of address represented in hexadecimal
1318 : @endcode
1319 :
1320 : @par Specification
1321 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">3.2.2. Host (rfc3986)</a>
1322 :
1323 : @return The IPv6 address as a value of type @ref ipv6_address.
1324 : */
1325 : ipv6_address
1326 : host_ipv6_address() const noexcept;
1327 :
1328 : /** Return the host IPvFuture address
1329 :
1330 : If the host type is @ref host_type::ipvfuture,
1331 : this function returns the address as
1332 : a string.
1333 : Otherwise, if the host type is not an
1334 : IPvFuture address, it returns an
1335 : empty string.
1336 :
1337 : @par Example
1338 : @code
1339 : assert( url_view( "http://[v1fe.d:9]/index.htm" ).host_ipvfuture() == "v1fe.d:9" );
1340 : @endcode
1341 :
1342 : @par Complexity
1343 : Constant.
1344 :
1345 : @par Exception Safety
1346 : Throws nothing.
1347 :
1348 : @par BNF
1349 : @code
1350 : IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )
1351 : @endcode
1352 :
1353 : @par Specification
1354 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">3.2.2. Host (rfc3986)</a>
1355 :
1356 : @return The IPvFuture address as a string.
1357 : */
1358 : core::string_view
1359 : host_ipvfuture() const noexcept;
1360 :
1361 : /** Return the host name
1362 :
1363 : If the host type is @ref host_type::name,
1364 : this function returns the name as
1365 : a string. Otherwise an empty string is returned.
1366 : Any percent-escapes in the string are
1367 : decoded first.
1368 :
1369 : @par Example
1370 : @code
1371 : assert( url_view( "https://www%2droot.example.com/" ).host_name() == "www-root.example.com" );
1372 : @endcode
1373 :
1374 : @par Complexity
1375 : Linear in `this->host_name().size()`.
1376 :
1377 : @par Exception Safety
1378 : Calls to allocate may throw.
1379 :
1380 : @par BNF
1381 : @code
1382 : host = IP-literal / IPv4address / reg-name
1383 :
1384 : IP-literal = "[" ( IPv6address / IPvFuture ) "]"
1385 :
1386 : reg-name = *( unreserved / pct-encoded / "-" / ".")
1387 : @endcode
1388 :
1389 : @par Specification
1390 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">3.2.2. Host (rfc3986)</a>
1391 :
1392 : @param token A string token customization.
1393 : @return The host name as a string.
1394 : */
1395 : template<BOOST_URL_STRTOK_TPARAM>
1396 : BOOST_URL_STRTOK_RETURN
1397 93 : host_name(
1398 : StringToken&& token = {}) const
1399 : {
1400 93 : encoding_opts opt;
1401 93 : opt.space_as_plus = false;
1402 186 : return encoded_host_name().decode(
1403 186 : opt, std::forward<StringToken>(token));
1404 : }
1405 :
1406 : /** Return the host name
1407 :
1408 : If the host type is @ref host_type::name,
1409 : this function returns the name as
1410 : a string.
1411 : Otherwise, if the host type is not an
1412 : name, it returns an empty string.
1413 : The returned string may contain
1414 : percent escapes.
1415 :
1416 : @par Example
1417 : @code
1418 : assert( url_view( "https://www%2droot.example.com/" ).encoded_host_name() == "www%2droot.example.com" );
1419 : @endcode
1420 :
1421 : @par Complexity
1422 : Constant.
1423 :
1424 : @par Exception Safety
1425 : Throws nothing.
1426 :
1427 : @par BNF
1428 : @code
1429 : host = IP-literal / IPv4address / reg-name
1430 :
1431 : IP-literal = "[" ( IPv6address / IPvFuture ) "]"
1432 :
1433 : reg-name = *( unreserved / pct-encoded / "-" / ".")
1434 : @endcode
1435 :
1436 : @par Specification
1437 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">3.2.2. Host (rfc3986)</a>
1438 :
1439 : @return The host name as a percent-encoded string.
1440 : */
1441 : pct_string_view
1442 : encoded_host_name() const noexcept;
1443 :
1444 : /** Return the IPv6 Zone ID
1445 :
1446 : If the host type is @ref host_type::ipv6,
1447 : this function returns the Zone ID as
1448 : a string. Otherwise an empty string is returned.
1449 : Any percent-escapes in the string are
1450 : decoded first.
1451 :
1452 : @par Example
1453 : @code
1454 : assert( url_view( "http://[fe80::1%25eth0]/" ).zone_id() == "eth0" );
1455 : @endcode
1456 :
1457 : @par Complexity
1458 : Linear in `this->encoded_zone_id().size()`.
1459 :
1460 : @par Exception Safety
1461 : Calls to allocate may throw.
1462 :
1463 : @par BNF
1464 : @code
1465 : host = IP-literal / IPv4address / reg-name
1466 :
1467 : IP-literal = "[" ( IPv6address / IPv6addrz / IPvFuture ) "]"
1468 :
1469 : ZoneID = 1*( unreserved / pct-encoded )
1470 :
1471 : IPv6addrz = IPv6address "%25" ZoneID
1472 : @endcode
1473 :
1474 : @par Specification
1475 : @li <a href="https://datatracker.ietf.org/doc/html/rfc6874">Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers</a>
1476 :
1477 : @param token A string token customization.
1478 : @return The Zone ID as a string.
1479 : */
1480 : template<BOOST_URL_STRTOK_TPARAM>
1481 : BOOST_URL_STRTOK_RETURN
1482 10 : zone_id(
1483 : StringToken&& token = {}) const
1484 : {
1485 10 : encoding_opts opt;
1486 10 : opt.space_as_plus = false;
1487 20 : return encoded_zone_id().decode(
1488 20 : opt, std::forward<StringToken>(token));
1489 : }
1490 :
1491 : /** Return the IPv6 Zone ID
1492 :
1493 : If the host type is @ref host_type::ipv6,
1494 : this function returns the Zone ID as
1495 : a string. Otherwise an empty string is returned.
1496 : The returned string may contain
1497 : percent escapes.
1498 :
1499 : @par Example
1500 : @code
1501 : assert( url_view( "http://[fe80::1%25eth0]/" ).encoded_zone_id() == "eth0" );
1502 : @endcode
1503 :
1504 : @par Complexity
1505 : Constant.
1506 :
1507 : @par Exception Safety
1508 : Throws nothing.
1509 :
1510 : @par BNF
1511 : @code
1512 : host = IP-literal / IPv4address / reg-name
1513 :
1514 : IP-literal = "[" ( IPv6address / IPv6addrz / IPvFuture ) "]"
1515 :
1516 : ZoneID = 1*( unreserved / pct-encoded )
1517 :
1518 : IPv6addrz = IPv6address "%25" ZoneID
1519 : @endcode
1520 :
1521 : @par Specification
1522 : @li <a href="https://datatracker.ietf.org/doc/html/rfc6874">Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers</a>
1523 :
1524 : @return The Zone ID as a percent-encoded string.
1525 : */
1526 : pct_string_view
1527 : encoded_zone_id() const noexcept;
1528 :
1529 : //--------------------------------------------
1530 : //
1531 : // Port
1532 : //
1533 : //--------------------------------------------
1534 :
1535 : /** Return true if a port is present
1536 :
1537 : This function returns true if an
1538 : authority is present and contains a port.
1539 :
1540 : @par Example
1541 : @code
1542 : assert( url_view( "wss://www.example.com:443" ).has_port() );
1543 : @endcode
1544 :
1545 : @par Complexity
1546 : Constant.
1547 :
1548 : @par Exception Safety
1549 : Throws nothing.
1550 :
1551 : @par BNF
1552 : @code
1553 : authority = [ userinfo "@" ] host [ ":" port ]
1554 :
1555 : port = *DIGIT
1556 : @endcode
1557 :
1558 : @par Specification
1559 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3">3.2.3. Port (rfc3986)</a>
1560 :
1561 : @see
1562 : @ref encoded_host_and_port,
1563 : @ref port,
1564 : @ref port_number.
1565 :
1566 : @return `true` if a port is present, `false` otherwise.
1567 : */
1568 : bool
1569 : has_port() const noexcept;
1570 :
1571 : /** Return the port
1572 :
1573 : If present, this function returns a
1574 : string representing the port (which
1575 : may be empty).
1576 : Otherwise it returns an empty string.
1577 :
1578 : @par Example
1579 : @code
1580 : assert( url_view( "http://localhost.com:8080" ).port() == "8080" );
1581 : @endcode
1582 :
1583 : @par Complexity
1584 : Constant.
1585 :
1586 : @par Exception Safety
1587 : Throws nothing.
1588 :
1589 : @par BNF
1590 : @code
1591 : port = *DIGIT
1592 : @endcode
1593 :
1594 : @par Specification
1595 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3">3.2.3. Port (rfc3986)</a>
1596 :
1597 : @see
1598 : @ref encoded_host_and_port,
1599 : @ref has_port,
1600 : @ref port_number.
1601 :
1602 : @return The port as a string.
1603 : */
1604 : core::string_view
1605 : port() const noexcept;
1606 :
1607 : /** Return the port
1608 :
1609 : If a port is present and the numerical
1610 : value is representable, it is returned
1611 : as an unsigned integer. Otherwise, the
1612 : number zero is returned.
1613 :
1614 : @par Example
1615 : @code
1616 : assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 );
1617 : @endcode
1618 :
1619 : @par Complexity
1620 : Constant.
1621 :
1622 : @par Exception Safety
1623 : Throws nothing.
1624 :
1625 : @par BNF
1626 : @code
1627 : port = *DIGIT
1628 : @endcode
1629 :
1630 : @par Specification
1631 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3">3.2.3. Port (rfc3986)</a>
1632 :
1633 : @see
1634 : @ref encoded_host_and_port,
1635 : @ref has_port,
1636 : @ref port.
1637 :
1638 : @return The port number as an unsigned integer.
1639 : */
1640 : std::uint16_t
1641 : port_number() const noexcept;
1642 :
1643 : //--------------------------------------------
1644 : //
1645 : // Path
1646 : //
1647 : //--------------------------------------------
1648 :
1649 : /** Return true if the path is absolute
1650 :
1651 : This function returns true if the path
1652 : begins with a forward slash ('/').
1653 :
1654 : @par Example
1655 : @code
1656 : assert( url_view( "/path/to/file.txt" ).is_path_absolute() );
1657 : @endcode
1658 :
1659 : @par Complexity
1660 : Constant.
1661 :
1662 : @par Exception Safety
1663 : Throws nothing.
1664 :
1665 : @par BNF
1666 : @code
1667 : path = path-abempty ; begins with "/" or is empty
1668 : / path-absolute ; begins with "/" but not "//"
1669 : / path-noscheme ; begins with a non-colon segment
1670 : / path-rootless ; begins with a segment
1671 : / path-empty ; zero characters
1672 :
1673 : path-abempty = *( "/" segment )
1674 : path-absolute = "/" [ segment-nz *( "/" segment ) ]
1675 : path-noscheme = segment-nz-nc *( "/" segment )
1676 : path-rootless = segment-nz *( "/" segment )
1677 : path-empty = 0<pchar>
1678 : @endcode
1679 :
1680 : @par Specification
1681 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3">3.3. Path (rfc3986)</a>
1682 :
1683 : @see
1684 : @ref encoded_path,
1685 : @ref encoded_segments.
1686 : @ref path,
1687 : @ref segments.
1688 :
1689 : @return `true` if the path is absolute, `false` otherwise.
1690 : */
1691 : bool
1692 1578 : is_path_absolute() const noexcept
1693 : {
1694 : return
1695 2725 : impl().len(id_path) > 0 &&
1696 2725 : impl().cs_[impl().offset(id_path)] == '/';
1697 : }
1698 :
1699 : /** Return the path
1700 :
1701 : This function returns the path as a
1702 : string. The path may be empty.
1703 : Any percent-escapes in the string are
1704 : decoded first.
1705 :
1706 : @par Example
1707 : @code
1708 : assert( url_view( "file:///Program%20Files/Games/config.ini" ).path() == "/Program Files/Games/config.ini" );
1709 : @endcode
1710 :
1711 : @par Complexity
1712 : Linear in `this->path().size()`.
1713 :
1714 : @par Exception Safety
1715 : Calls to allocate may throw.
1716 :
1717 : @par BNF
1718 : @code
1719 : path = path-abempty ; begins with "/" or is empty
1720 : / path-absolute ; begins with "/" but not "//"
1721 : / path-noscheme ; begins with a non-colon segment
1722 : / path-rootless ; begins with a segment
1723 : / path-empty ; zero characters
1724 :
1725 : path-abempty = *( "/" segment )
1726 : path-absolute = "/" [ segment-nz *( "/" segment ) ]
1727 : path-noscheme = segment-nz-nc *( "/" segment )
1728 : path-rootless = segment-nz *( "/" segment )
1729 : path-empty = 0<pchar>
1730 : @endcode
1731 :
1732 : @par Specification
1733 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3">3.3. Path (rfc3986)</a>
1734 :
1735 : @see
1736 : @ref is_path_absolute,
1737 : @ref encoded_path,
1738 : @ref encoded_segments.
1739 : @ref segments.
1740 :
1741 : @param token A string token to use for the result.
1742 : @return The path as a string.
1743 : */
1744 : template<BOOST_URL_STRTOK_TPARAM>
1745 : BOOST_URL_STRTOK_RETURN
1746 56 : path(
1747 : StringToken&& token = {}) const
1748 : {
1749 56 : encoding_opts opt;
1750 56 : opt.space_as_plus = false;
1751 112 : return encoded_path().decode(
1752 112 : opt, std::forward<StringToken>(token));
1753 : }
1754 :
1755 : /** Return the path
1756 :
1757 : This function returns the path as a
1758 : string. The path may be empty.
1759 : Any percent-escapes in the string are
1760 : decoded first.
1761 :
1762 : @par Example
1763 : @code
1764 : assert( url_view( "file:///Program%20Files/Games/config.ini" ).encoded_path() == "/Program%20Files/Games/config.ini" );
1765 : @endcode
1766 :
1767 : @par Complexity
1768 : Constant.
1769 :
1770 : @par Exception Safety
1771 : Throws nothing.
1772 :
1773 : @par BNF
1774 : @code
1775 : path = path-abempty ; begins with "/" or is empty
1776 : / path-absolute ; begins with "/" but not "//"
1777 : / path-noscheme ; begins with a non-colon segment
1778 : / path-rootless ; begins with a segment
1779 : / path-empty ; zero characters
1780 :
1781 : path-abempty = *( "/" segment )
1782 : path-absolute = "/" [ segment-nz *( "/" segment ) ]
1783 : path-noscheme = segment-nz-nc *( "/" segment )
1784 : path-rootless = segment-nz *( "/" segment )
1785 : path-empty = 0<pchar>
1786 : @endcode
1787 :
1788 : @par Specification
1789 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3">3.3. Path (rfc3986)</a>
1790 :
1791 : @see
1792 : @ref is_path_absolute,
1793 : @ref encoded_segments.
1794 : @ref path,
1795 : @ref segments.
1796 :
1797 : @return The path as a string.
1798 : */
1799 : pct_string_view
1800 : encoded_path() const noexcept;
1801 :
1802 : /** Return the path as a container of segments
1803 :
1804 : This function returns a bidirectional
1805 : view of strings over the path.
1806 : The returned view references the same
1807 : underlying character buffer; ownership
1808 : is not transferred.
1809 : Any percent-escapes in strings returned
1810 : when iterating the view are decoded first.
1811 :
1812 : @par Example
1813 : @code
1814 : segments_view sv = url_view( "/path/to/file.txt" ).segments();
1815 : @endcode
1816 :
1817 : @par Complexity
1818 : Constant.
1819 :
1820 : @par Exception Safety
1821 : Throws nothing.
1822 :
1823 : @par BNF
1824 : @code
1825 : path = [ "/" ] segment *( "/" segment )
1826 : @endcode
1827 :
1828 : @par Specification
1829 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3">3.3. Path (rfc3986)</a>
1830 :
1831 : @see
1832 : @ref is_path_absolute,
1833 : @ref encoded_path,
1834 : @ref encoded_segments.
1835 : @ref path,
1836 : @ref segments_view.
1837 :
1838 : @return A bidirectional view of segments.
1839 : */
1840 : segments_view
1841 : segments() const noexcept;
1842 :
1843 : /** Return the path as a container of segments
1844 :
1845 : This function returns a bidirectional
1846 : view of strings over the path.
1847 : The returned view references the same
1848 : underlying character buffer; ownership
1849 : is not transferred.
1850 : Strings returned when iterating the
1851 : range may contain percent escapes.
1852 :
1853 : @par Example
1854 : @code
1855 : segments_encoded_view sv = url_view( "/path/to/file.txt" ).encoded_segments();
1856 : @endcode
1857 :
1858 : @par Complexity
1859 : Constant.
1860 :
1861 : @par Exception Safety
1862 : Throws nothing.
1863 :
1864 : @par BNF
1865 : @code
1866 : path = path-abempty ; begins with "/" or is empty
1867 : / path-absolute ; begins with "/" but not "//"
1868 : / path-noscheme ; begins with a non-colon segment
1869 : / path-rootless ; begins with a segment
1870 : / path-empty ; zero characters
1871 :
1872 : path-abempty = *( "/" segment )
1873 : path-absolute = "/" [ segment-nz *( "/" segment ) ]
1874 : path-noscheme = segment-nz-nc *( "/" segment )
1875 : path-rootless = segment-nz *( "/" segment )
1876 : path-empty = 0<pchar>
1877 : @endcode
1878 :
1879 : @par Specification
1880 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3">3.3. Path (rfc3986)</a>
1881 :
1882 : @see
1883 : @ref is_path_absolute,
1884 : @ref encoded_path,
1885 : @ref path,
1886 : @ref segments,
1887 : @ref segments_encoded_view.
1888 :
1889 : @return A bidirectional view of encoded segments.
1890 : */
1891 : segments_encoded_view
1892 : encoded_segments() const noexcept;
1893 :
1894 : //--------------------------------------------
1895 : //
1896 : // Query
1897 : //
1898 : //--------------------------------------------
1899 :
1900 : /** Return true if a query is present
1901 :
1902 : This function returns true if this
1903 : contains a query. An empty query is
1904 : distinct from having no query.
1905 :
1906 : @par Example
1907 : @code
1908 : assert( url_view( "/sql?id=42&col=name&page-size=20" ).has_query() );
1909 : @endcode
1910 :
1911 : @par Complexity
1912 : Constant.
1913 :
1914 : @par Exception Safety
1915 : Throws nothing.
1916 :
1917 : @par BNF
1918 : @code
1919 : query = *( pchar / "/" / "?" )
1920 :
1921 : query-param = key [ "=" value ]
1922 : query-params = [ query-param ] *( "&" query-param )
1923 : @endcode
1924 :
1925 : @par Specification
1926 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4">3.4. Query (rfc3986)</a>
1927 : @li <a href="https://en.wikipedia.org/wiki/Query_string">Query string (Wikipedia)</a>
1928 :
1929 : @see
1930 : @ref encoded_params,
1931 : @ref encoded_query,
1932 : @ref params,
1933 : @ref query.
1934 :
1935 : @return `true` if a query is present.
1936 : */
1937 : bool
1938 : has_query() const noexcept;
1939 :
1940 : /** Return the query
1941 :
1942 : If this contains a query, it is returned
1943 : as a string (which may be empty).
1944 : Otherwise, an empty string is returned.
1945 : Any percent-escapes in the string are
1946 : decoded first.
1947 : <br>
1948 :
1949 : Literal plus signs remain unchanged by
1950 : default to match RFC 3986. To treat '+'
1951 : as a space, supply decoding options with
1952 : `space_as_plus = true` when calling this
1953 : function.
1954 :
1955 : @par Example
1956 : @code
1957 : assert( url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).query() == "id=42&name=jane-doe&page size=20" );
1958 : @endcode
1959 :
1960 : @par Complexity
1961 : Linear in `this->query().size()`.
1962 :
1963 : @par Exception Safety
1964 : Calls to allocate may throw.
1965 :
1966 : @par BNF
1967 : @code
1968 : query = *( pchar / "/" / "?" )
1969 :
1970 : query-param = key [ "=" value ]
1971 : query-params = [ query-param ] *( "&" query-param )
1972 : @endcode
1973 :
1974 : @par Specification
1975 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4">3.4. Query (rfc3986)</a>
1976 : @li <a href="https://en.wikipedia.org/wiki/Query_string">Query string (Wikipedia)</a>
1977 :
1978 : @see
1979 : @ref encoded_params,
1980 : @ref encoded_query,
1981 : @ref has_query,
1982 : @ref params.
1983 :
1984 : @param token A token to use for the returned string.
1985 : @return The query as a string.
1986 : */
1987 : template<BOOST_URL_STRTOK_TPARAM>
1988 : BOOST_URL_STRTOK_RETURN
1989 41 : query(
1990 : StringToken&& token = {}) const
1991 : {
1992 : // When interacting with the query as
1993 : // an intact string, we do not treat
1994 : // the plus sign as an encoded space.
1995 41 : encoding_opts opt;
1996 41 : opt.space_as_plus = false;
1997 82 : return encoded_query().decode(
1998 82 : opt, std::forward<StringToken>(token));
1999 : }
2000 :
2001 : /** Return the query
2002 :
2003 : If this contains a query, it is returned
2004 : as a string (which may be empty).
2005 : Otherwise, an empty string is returned.
2006 : The returned string may contain
2007 : percent escapes.
2008 :
2009 : @par Example
2010 : @code
2011 : assert( url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_query() == "id=42&name=jane%2Ddoe&page+size=20" );
2012 : @endcode
2013 :
2014 : @par Complexity
2015 : Constant.
2016 :
2017 : @par Exception Safety
2018 : Throws nothing.
2019 :
2020 : @par BNF
2021 : @code
2022 : query = *( pchar / "/" / "?" )
2023 :
2024 : query-param = key [ "=" value ]
2025 : query-params = [ query-param ] *( "&" query-param )
2026 : @endcode
2027 :
2028 : @par Specification
2029 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4">3.4. Query (rfc3986)</a>
2030 : @li <a href="https://en.wikipedia.org/wiki/Query_string">Query string (Wikipedia)</a>
2031 :
2032 : @see
2033 : @ref encoded_params,
2034 : @ref has_query,
2035 : @ref params,
2036 : @ref query.
2037 :
2038 : @return The query as a string.
2039 : */
2040 : pct_string_view
2041 : encoded_query() const noexcept;
2042 :
2043 : /** Return the query as a container of parameters
2044 :
2045 : This function returns a bidirectional
2046 : view of key/value pairs over the query.
2047 : The returned view references the same
2048 : underlying character buffer; ownership
2049 : is not transferred.
2050 : Any percent-escapes in strings returned
2051 : when iterating the view are decoded first.
2052 :
2053 : @par Example
2054 : @code
2055 : params_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).params();
2056 : @endcode
2057 :
2058 : @par Complexity
2059 : Constant.
2060 :
2061 : @par Exception Safety
2062 : Throws nothing.
2063 :
2064 : @par BNF
2065 : @code
2066 : query = *( pchar / "/" / "?" )
2067 :
2068 : query-param = key [ "=" value ]
2069 : query-params = [ query-param ] *( "&" query-param )
2070 : @endcode
2071 :
2072 : @par Specification
2073 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4">3.4. Query (rfc3986)</a>
2074 : @li <a href="https://en.wikipedia.org/wiki/Query_string">Query string (Wikipedia)</a>
2075 :
2076 : @see
2077 : @ref encoded_params,
2078 : @ref encoded_query,
2079 : @ref has_query,
2080 : @ref query.
2081 :
2082 : @return A bidirectional view of key/value pairs.
2083 : */
2084 : params_view
2085 : params() const noexcept;
2086 :
2087 : params_view
2088 : params(encoding_opts opt) const noexcept;
2089 :
2090 : /** Return the query as a container of parameters
2091 :
2092 : This function returns a bidirectional
2093 : view of key/value pairs over the query.
2094 : The returned view references the same
2095 : underlying character buffer; ownership
2096 : is not transferred.
2097 : Strings returned when iterating the
2098 : range may contain percent escapes.
2099 :
2100 : @par Example
2101 : @code
2102 : params_encoded_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();
2103 : @endcode
2104 :
2105 : @par Complexity
2106 : Constant.
2107 :
2108 : @par Exception Safety
2109 : Throws nothing.
2110 :
2111 : @par BNF
2112 : @code
2113 : query = *( pchar / "/" / "?" )
2114 : query-param = key [ "=" value ]
2115 : query-params = [ query-param ] *( "&" query-param )
2116 : @endcode
2117 :
2118 : @par Specification
2119 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4">3.4. Query (rfc3986)</a>
2120 : @li <a href="https://en.wikipedia.org/wiki/Query_string">Query string (Wikipedia)</a>
2121 :
2122 : @see
2123 : @ref encoded_query,
2124 : @ref has_query,
2125 : @ref params,
2126 : @ref query.
2127 :
2128 : @return A bidirectional view of key/value pairs.
2129 : */
2130 : params_encoded_view
2131 : encoded_params() const noexcept;
2132 :
2133 : //--------------------------------------------
2134 : //
2135 : // Fragment
2136 : //
2137 : //--------------------------------------------
2138 :
2139 : /** Return true if a fragment is present
2140 :
2141 : This function returns true if the url
2142 : contains a fragment.
2143 : An empty fragment is distinct from
2144 : no fragment.
2145 :
2146 : @par Example
2147 : @code
2148 : assert( url_view( "http://www.example.com/index.htm#anchor" ).has_fragment() );
2149 : @endcode
2150 :
2151 : @par Complexity
2152 : Constant.
2153 :
2154 : @par Exception Safety
2155 : Throws nothing.
2156 :
2157 : @par BNF
2158 : @code
2159 : URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
2160 :
2161 : relative-ref = relative-part [ "?" query ] [ "#" fragment ]
2162 : @endcode
2163 :
2164 : @par Specification
2165 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.5">3.5. Fragment (rfc3986)</a>
2166 :
2167 : @see
2168 : @ref encoded_fragment,
2169 : @ref fragment.
2170 :
2171 : @return `true` if the url contains a fragment.
2172 : */
2173 : bool
2174 : has_fragment() const noexcept;
2175 :
2176 : /** Return the fragment
2177 :
2178 : This function calculates the fragment
2179 : of the url, with percent escapes decoded
2180 : and without the leading pound sign ('#')
2181 : whose presence indicates that the url
2182 : contains a fragment.
2183 :
2184 : <br>
2185 :
2186 : This function accepts an optional
2187 : <em>StringToken</em> parameter which
2188 : controls the return type and behavior
2189 : of the function:
2190 :
2191 : @li When called with no arguments,
2192 : the return type of the function is
2193 : `std::string`. Otherwise
2194 :
2195 : @li When called with a string token,
2196 : the behavior and return type of the
2197 : function depends on the type of string
2198 : token being passed.
2199 :
2200 : @par Example
2201 : @code
2202 : assert( url_view( "http://www.example.com/index.htm#a%2D1" ).fragment() == "a-1" );
2203 : @endcode
2204 :
2205 : @par Complexity
2206 : Linear in `this->fragment().size()`.
2207 :
2208 : @par Exception Safety
2209 : Calls to allocate may throw.
2210 : String tokens may throw exceptions.
2211 :
2212 : @param token An optional string token to
2213 : use. If this parameter is omitted, the
2214 : function returns a new `std::string`.
2215 :
2216 : @return The fragment portion of the url.
2217 :
2218 : @par BNF
2219 : @code
2220 : fragment = *( pchar / "/" / "?" )
2221 :
2222 : fragment-part = [ "#" fragment ]
2223 : @endcode
2224 :
2225 : @par Specification
2226 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.5">3.5. Fragment (rfc3986)</a>
2227 :
2228 : @see
2229 : @ref encoded_fragment,
2230 : @ref has_fragment.
2231 :
2232 : */
2233 : template<BOOST_URL_STRTOK_TPARAM>
2234 : BOOST_URL_STRTOK_RETURN
2235 37 : fragment(
2236 : StringToken&& token = {}) const
2237 : {
2238 37 : encoding_opts opt;
2239 37 : opt.space_as_plus = false;
2240 74 : return encoded_fragment().decode(
2241 74 : opt, std::forward<StringToken>(token));
2242 : }
2243 :
2244 : /** Return the fragment
2245 :
2246 : This function returns the fragment as a
2247 : string with percent-escapes.
2248 : Ownership is not transferred; the
2249 : string returned references the underlying
2250 : character buffer, which must remain valid
2251 : or else undefined behavior occurs.
2252 :
2253 : @par Example
2254 : @code
2255 : assert( url_view( "http://www.example.com/index.htm#a%2D1" ).encoded_fragment() == "a%2D1" );
2256 : @endcode
2257 :
2258 : @par Complexity
2259 : Constant.
2260 :
2261 : @par Exception Safety
2262 : Throws nothing.
2263 :
2264 : @par BNF
2265 : @code
2266 : fragment = *( pchar / "/" / "?" )
2267 :
2268 : pchar = unreserved / pct-encoded / sub-delims / ":" / "@"
2269 : @endcode
2270 :
2271 : @par Specification
2272 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.5">3.5. Fragment (rfc3986)</a>
2273 :
2274 : @see
2275 : @ref fragment,
2276 : @ref has_fragment.
2277 :
2278 : @return The fragment portion of the url.
2279 : */
2280 : pct_string_view
2281 : encoded_fragment() const noexcept;
2282 :
2283 : //--------------------------------------------
2284 : //
2285 : // Compound Fields
2286 : //
2287 : //--------------------------------------------
2288 :
2289 : /** Return the host and port
2290 :
2291 : If an authority is present, this
2292 : function returns the host and optional
2293 : port as a string, which may be empty.
2294 : Otherwise it returns an empty string.
2295 : The returned string may contain
2296 : percent escapes.
2297 :
2298 : @par Example
2299 : @code
2300 : assert( url_view( "http://www.example.com:8080/index.htm" ).encoded_host_and_port() == "www.example.com:8080" );
2301 : @endcode
2302 :
2303 : @par Complexity
2304 : Constant.
2305 :
2306 : @par Exception Safety
2307 : Throws nothing.
2308 :
2309 : @par BNF
2310 : @code
2311 : authority = [ userinfo "@" ] host [ ":" port ]
2312 : @endcode
2313 :
2314 : @par Specification
2315 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2">3.2.2. Host (rfc3986)</a>
2316 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.3">3.2.3. Port (rfc3986)</a>
2317 :
2318 : @see
2319 : @ref has_port,
2320 : @ref port,
2321 : @ref port_number.
2322 :
2323 : @return The host and port portion of the url.
2324 : */
2325 : pct_string_view
2326 : encoded_host_and_port() const noexcept;
2327 :
2328 : /** Return the origin
2329 :
2330 : If an authority is present, this
2331 : function returns the scheme and
2332 : authority portion of the url.
2333 : Otherwise, an empty string is
2334 : returned.
2335 : The returned string may contain
2336 : percent escapes.
2337 :
2338 : @par Example
2339 : @code
2340 : assert( url_view( "http://www.example.com:8080/index.htm?text=none#h1" ).encoded_origin() == "http://www.example.com:8080" );
2341 : @endcode
2342 :
2343 : @par Complexity
2344 : Constant.
2345 :
2346 : @par Exception Safety
2347 : Throws nothing.
2348 :
2349 : @see
2350 : @ref encoded_resource,
2351 : @ref encoded_target.
2352 :
2353 : @return The origin portion of the url.
2354 : */
2355 : pct_string_view
2356 : encoded_origin() const noexcept;
2357 :
2358 : /** Return the resource
2359 :
2360 : This function returns the resource, which
2361 : is the portion of the url that includes
2362 : only the path, query, and fragment.
2363 : The returned string may contain
2364 : percent escapes.
2365 :
2366 : @par Example
2367 : @code
2368 : assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_resource() == "/index.html?query#frag" );
2369 : @endcode
2370 :
2371 : @par Complexity
2372 : Constant.
2373 :
2374 : @par Exception Safety
2375 : Throws nothing.
2376 :
2377 : @par Specification
2378 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3">3.3. Path (rfc3986)</a>
2379 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4">3.4. Query (rfc3986)</a>
2380 :
2381 : @see
2382 : @ref encoded_origin,
2383 : @ref encoded_target.
2384 :
2385 : @return The resource portion of the url.
2386 : */
2387 : pct_string_view
2388 : encoded_resource() const noexcept;
2389 :
2390 : /** Return the target
2391 :
2392 : This function returns the target, which
2393 : is the portion of the url that includes
2394 : only the path and query.
2395 : The returned string may contain
2396 : percent escapes.
2397 :
2398 : @par Example
2399 : @code
2400 : assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_target() == "/index.html?query" );
2401 : @endcode
2402 :
2403 : @par Complexity
2404 : Constant.
2405 :
2406 : @par Exception Safety
2407 : Throws nothing.
2408 :
2409 : @par Specification
2410 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.3">3.3. Path (rfc3986)</a>
2411 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4">3.4. Query (rfc3986)</a>
2412 :
2413 : @see
2414 : @ref encoded_origin,
2415 : @ref encoded_resource.
2416 :
2417 : @return The target portion of the url.
2418 : */
2419 : pct_string_view
2420 : encoded_target() const noexcept;
2421 :
2422 : //--------------------------------------------
2423 : //
2424 : // Comparison
2425 : //
2426 : //--------------------------------------------
2427 :
2428 : /** Return the result of comparing this with another url
2429 :
2430 : This function compares two URLs
2431 : according to Syntax-Based comparison
2432 : algorithm.
2433 :
2434 : @par Complexity
2435 : Linear in `min( u0.size(), u1.size() )`
2436 :
2437 : @par Exception Safety
2438 : Throws nothing.
2439 :
2440 : @par Specification
2441 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2">6.2.2 Syntax-Based Normalization (rfc3986)</a>
2442 :
2443 : @param other The url to compare
2444 : @return -1 if `*this < other`, 0 if `this == other`, and 1 if `this > other`.
2445 : */
2446 : int
2447 : compare(url_view_base const& other) const noexcept;
2448 :
2449 : /** Return the result of comparing two URLs
2450 :
2451 : The URLs are compared component by
2452 : component as if they were first
2453 : normalized.
2454 :
2455 : @par Example
2456 : @code
2457 : url_view u0( "http://www.a.com/index.htm" );
2458 : url_view u1( "http://www.a.com/index.htm" );
2459 : assert( u0 == u1 );
2460 : @endcode
2461 :
2462 : @par Effects
2463 : @code
2464 : url a(u0);
2465 : a.normalize();
2466 : url b(u1);
2467 : b.normalize();
2468 : return a.buffer() == b.buffer();
2469 : @endcode
2470 :
2471 : @par Complexity
2472 : Linear in `min( u0.size(), u1.size() )`
2473 :
2474 : @par Exception Safety
2475 : Throws nothing
2476 :
2477 : @param u0 The first url to compare
2478 : @param u1 The second url to compare
2479 : @return `true` if `u0 == u1`
2480 :
2481 : @par Specification
2482 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2">6.2.2 Syntax-Based Normalization (rfc3986)</a>
2483 : */
2484 : friend
2485 : bool
2486 81 : operator==(
2487 : url_view_base const& u0,
2488 : url_view_base const& u1) noexcept
2489 : {
2490 81 : return u0.compare(u1) == 0;
2491 : }
2492 :
2493 : /** Return the result of comparing two URLs
2494 :
2495 : The URLs are compared component by
2496 : component as if they were first
2497 : normalized.
2498 :
2499 : @par Example
2500 : @code
2501 : url_view u0( "http://www.a.com/index.htm" );
2502 : url_view u1( "http://www.b.com/index.htm" );
2503 : assert( u0 != u1 );
2504 : @endcode
2505 :
2506 : @par Effects
2507 : @code
2508 : url a(u0);
2509 : a.normalize();
2510 : url b(u1);
2511 : b.normalize();
2512 : return a.buffer() != b.buffer();
2513 : @endcode
2514 :
2515 : @par Complexity
2516 : Linear in `min( u0.size(), u1.size() )`
2517 :
2518 : @par Exception Safety
2519 : Throws nothing
2520 :
2521 : @param u0 The first url to compare
2522 : @param u1 The second url to compare
2523 : @return `true` if `u0 != u1`
2524 :
2525 : @par Specification
2526 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2">6.2.2 Syntax-Based Normalization (rfc3986)</a>
2527 : */
2528 : friend
2529 : bool
2530 30 : operator!=(
2531 : url_view_base const& u0,
2532 : url_view_base const& u1) noexcept
2533 : {
2534 30 : return ! (u0 == u1);
2535 : }
2536 :
2537 : /** Return the result of comparing two URLs
2538 :
2539 : The URLs are compared component by
2540 : component as if they were first
2541 : normalized.
2542 :
2543 : @par Example
2544 : @code
2545 : url_view u0( "http://www.a.com/index.htm" );
2546 : url_view u1( "http://www.b.com/index.htm" );
2547 : assert( u0 < u1 );
2548 : @endcode
2549 :
2550 : @par Effects
2551 : @code
2552 : url a(u0);
2553 : a.normalize();
2554 : url b(u1);
2555 : b.normalize();
2556 : return a.buffer() < b.buffer();
2557 : @endcode
2558 :
2559 : @par Complexity
2560 : Linear in `min( u0.size(), u1.size() )`
2561 :
2562 : @par Exception Safety
2563 : Throws nothing
2564 :
2565 : @param u0 The first url to compare
2566 : @param u1 The second url to compare
2567 : @return `true` if `u0 < u1`
2568 :
2569 : @par Specification
2570 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2">6.2.2 Syntax-Based Normalization (rfc3986)</a>
2571 : */
2572 : friend
2573 : bool
2574 23 : operator<(
2575 : url_view_base const& u0,
2576 : url_view_base const& u1) noexcept
2577 : {
2578 23 : return u0.compare(u1) < 0;
2579 : }
2580 :
2581 : /** Return the result of comparing two URLs
2582 :
2583 : The URLs are compared component by
2584 : component as if they were first
2585 : normalized.
2586 :
2587 : @par Example
2588 : @code
2589 : url_view u0( "http://www.b.com/index.htm" );
2590 : url_view u1( "http://www.b.com/index.htm" );
2591 : assert( u0 <= u1 );
2592 : @endcode
2593 :
2594 : @par Effects
2595 : @code
2596 : url a(u0);
2597 : a.normalize();
2598 : url b(u1);
2599 : b.normalize();
2600 : return a.buffer() <= b.buffer();
2601 : @endcode
2602 :
2603 : @par Complexity
2604 : Linear in `min( u0.size(), u1.size() )`
2605 :
2606 : @par Exception Safety
2607 : Throws nothing
2608 :
2609 : @param u0 The first url to compare
2610 : @param u1 The second url to compare
2611 : @return `true` if `u0 <= u1`
2612 :
2613 : @par Specification
2614 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2">6.2.2 Syntax-Based Normalization (rfc3986)</a>
2615 : */
2616 : friend
2617 : bool
2618 23 : operator<=(
2619 : url_view_base const& u0,
2620 : url_view_base const& u1) noexcept
2621 : {
2622 23 : return u0.compare(u1) <= 0;
2623 : }
2624 :
2625 : /** Return the result of comparing two URLs
2626 :
2627 : The URLs are compared component by
2628 : component as if they were first
2629 : normalized.
2630 :
2631 : @par Example
2632 : @code
2633 : url_view u0( "http://www.b.com/index.htm" );
2634 : url_view u1( "http://www.a.com/index.htm" );
2635 : assert( u0 > u1 );
2636 : @endcode
2637 :
2638 : @par Effects
2639 : @code
2640 : url a(u0);
2641 : a.normalize();
2642 : url b(u1);
2643 : b.normalize();
2644 : return a.buffer() > b.buffer();
2645 : @endcode
2646 :
2647 : @par Complexity
2648 : Linear in `min( u0.size(), u1.size() )`
2649 :
2650 : @par Exception Safety
2651 : Throws nothing
2652 :
2653 : @param u0 The first url to compare
2654 : @param u1 The second url to compare
2655 : @return `true` if `u0 > u1`
2656 :
2657 : @par Specification
2658 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2">6.2.2 Syntax-Based Normalization (rfc3986)</a>
2659 : */
2660 : friend
2661 : bool
2662 23 : operator>(
2663 : url_view_base const& u0,
2664 : url_view_base const& u1) noexcept
2665 : {
2666 23 : return u0.compare(u1) > 0;
2667 : }
2668 :
2669 : /** Return the result of comparing two URLs
2670 :
2671 : The URLs are compared component by
2672 : component as if they were first
2673 : normalized.
2674 :
2675 : @par Example
2676 : @code
2677 : url_view u0( "http://www.a.com/index.htm" );
2678 : url_view u1( "http://www.a.com/index.htm" );
2679 : assert( u0 >= u1 );
2680 : @endcode
2681 :
2682 : @par Effects
2683 : @code
2684 : url a(u0);
2685 : a.normalize();
2686 : url b(u1);
2687 : b.normalize();
2688 : return a.buffer() >= b.buffer();
2689 : @endcode
2690 :
2691 : @par Complexity
2692 : Linear in `min( u0.size(), u1.size() )`
2693 :
2694 : @par Exception Safety
2695 : Throws nothing
2696 :
2697 : @param u0 The first url to compare
2698 : @param u1 The second url to compare
2699 : @return `true` if `u0 >= u1`
2700 :
2701 : @par Specification
2702 : @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-6.2.2">6.2.2 Syntax-Based Normalization (rfc3986)</a>
2703 : */
2704 : friend
2705 : bool
2706 23 : operator>=(
2707 : url_view_base const& u0,
2708 : url_view_base const& u1) noexcept
2709 : {
2710 23 : return u0.compare(u1) >= 0;
2711 : }
2712 :
2713 : /** Format the url to the output stream
2714 :
2715 : This function serializes the url to
2716 : the specified output stream. Any
2717 : percent-escapes are emitted as-is;
2718 : no decoding is performed.
2719 :
2720 : @par Example
2721 : @code
2722 : url_view u( "http://www.example.com/index.htm" );
2723 : std::stringstream ss;
2724 : ss << u;
2725 : assert( ss.str() == "http://www.example.com/index.htm" );
2726 : @endcode
2727 :
2728 : @par Effects
2729 : @code
2730 : return os << u.buffer();
2731 : @endcode
2732 :
2733 : @par Complexity
2734 : Linear in `u.buffer().size()`
2735 :
2736 : @par Exception Safety
2737 : Basic guarantee.
2738 :
2739 : @return A reference to the output stream, for chaining
2740 :
2741 : @param os The output stream to write to.
2742 :
2743 : @param u The url to write.
2744 : */
2745 : friend
2746 : std::ostream&
2747 31 : operator<<(
2748 : std::ostream& os,
2749 : url_view_base const& u)
2750 : {
2751 31 : return os << u.buffer();
2752 : }
2753 :
2754 : private:
2755 : //--------------------------------------------
2756 : //
2757 : // implementation
2758 : //
2759 : //--------------------------------------------
2760 : static
2761 : int
2762 : segments_compare(
2763 : segments_encoded_view seg0,
2764 : segments_encoded_view seg1) noexcept;
2765 : };
2766 :
2767 : //------------------------------------------------
2768 :
2769 : /** Format the url to the output stream
2770 :
2771 : This function serializes the url to
2772 : the specified output stream. Any
2773 : percent-escapes are emitted as-is;
2774 : no decoding is performed.
2775 :
2776 : @par Example
2777 : @code
2778 : url_view u( "http://www.example.com/index.htm" );
2779 : std::stringstream ss;
2780 : ss << u;
2781 : assert( ss.str() == "http://www.example.com/index.htm" );
2782 : @endcode
2783 :
2784 : @par Effects
2785 : @code
2786 : return os << u.buffer();
2787 : @endcode
2788 :
2789 : @par Complexity
2790 : Linear in `u.buffer().size()`
2791 :
2792 : @par Exception Safety
2793 : Basic guarantee.
2794 :
2795 : @return A reference to the output stream, for chaining
2796 :
2797 : @param os The output stream to write to.
2798 :
2799 : @param u The url to write.
2800 : */
2801 : std::ostream&
2802 : operator<<(
2803 : std::ostream& os,
2804 : url_view_base const& u);
2805 :
2806 : } // urls
2807 : } // boost
2808 :
2809 : #include <boost/url/impl/url_view_base.hpp>
2810 :
2811 : #endif
|
