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