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