Index/include / boost / url / url_view_base.hpp
Prev Index Next

include/boost/url/url_view_base.hpp

100.0% Lines (94/94) 100.0% Functions (33/33) 94.4% Branches (17/18)
include/boost/url/url_view_base.hpp
Line Branch Hits 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
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 113283 times.
 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
1/1
✓ Branch 2 taken 40 times.
 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
1/1
✓ Branch 2 taken 58 times.
 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
1/1
✓ Branch 2 taken 28 times.
 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
1/1
✓ Branch 3 taken 2 times.
 176 return encoded_host().decode(
1084
1/1
✓ Branch 2 taken 86 times.
 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
1/1
✓ Branch 2 taken 99 times.
 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
1/1
✓ Branch 2 taken 93 times.
 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
1/1
✓ Branch 2 taken 10 times.
 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
2/2
✓ Branch 2 taken 1147 times.
✓ Branch 3 taken 431 times.
 2725 impl().len(id_path) > 0 &&
1696
2/2
✓ Branch 3 taken 720 times.
✓ Branch 4 taken 427 times.
 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
1/1
✓ Branch 3 taken 3 times.
 112 return encoded_path().decode(
1752
1/1
✓ Branch 2 taken 53 times.
 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
1/1
✓ Branch 2 taken 41 times.
 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
1/1
✓ Branch 2 taken 37 times.
 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
2812