[#boost-urls-url-set_encoded_host]
= xref:boost.adoc[boost]::xref:boost/urls.adoc[urls]::xref:boost/urls/url.adoc[url]::set_encoded_host
:relfileprefix: ../../../
:mrdocs:


Set the host

== Synopsis


Declared in `<https://www.github.com/boostorg/url/blob/develop/include/boost/url/url.hpp#L441[boost/url/url.hpp]>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
xref:boost/urls/url.adoc[url]&
set_encoded_host(xref:boost/urls/pct_string_view.adoc[pct_string_view] s);
----

== Description


Depending on the contents of the passed        string, this function sets the host:

* If the string is a valid IPv4 address,        then the host is set to the address.
        The host type is 
host_type::ipv4
.
* If the string is a valid IPv6 address        enclosed in square brackets, then the
        host is set to that address.        The host type is 
host_type::ipv6
.
* If the string is a valid IPvFuture        address enclosed in square brackets, then
        the host is set to that address.        The host type is 
host_type::ipvfuture
.
* Otherwise, the host name is set to        the string. This string can contain percent
        escapes, or can be empty.        Escapes in the string are preserved,
        and reserved characters in the string        are percent‐escaped in the result.
        The host type is 
host_type::name
.

In all cases, when this function returns,        the URL contains an authority.


=== Example

[,cpp]
----
assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );
----

=== Postconditions

[,cpp]
----
this->has_authority() == true
----

=== Complexity

Linear in `this‐>size() + s.size()`.


=== Exception Safety

Strong guarantee.        Calls to allocate may throw.        Exceptions thrown on invalid input.


=== BNF

[,cpp]
----
host        = IP-literal / IPv4address / reg-name

IP-literal  = "[" ( IPv6address / IPvFuture  ) "]"

reg-name    = *( unreserved / pct-encoded / "-" / ".")
----

=== Specification

* link:https://en.wikipedia.org/wiki/IPv4[IPv4 (Wikipedia)]
        
* link:https://datatracker.ietf.org/doc/html/rfc4291[IP Version 6 Addressing Architecture (rfc4291)]
        
* link:https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.2[            3.2.2. Host (rfc3986)]



== Exceptions


|===
| Name | Thrown on

| `system_error`
| `s` contains an invalid percent‐encoding.


|===

== Parameters


|===
| Name | Description

| *s*
| The string to set.


|===

== See Also


xref:boost/urls/url_base/set_encoded_host_address.adoc[set_encoded_host_address],            xref:boost/urls/url_base/set_encoded_host_name.adoc[set_encoded_host_name],            xref:boost/urls/url_base/set_host.adoc[set_host],            xref:boost/urls/url_base/set_host_address.adoc[set_host_address],            xref:boost/urls/url_base/set_host_ipv4.adoc[set_host_ipv4],            xref:boost/urls/url_base/set_host_ipv6.adoc[set_host_ipv6],            xref:boost/urls/url_base/set_host_ipvfuture.adoc[set_host_ipvfuture],            xref:boost/urls/url_base/set_host_name.adoc[set_host_name].






[.small]#Created with https://www.mrdocs.com[MrDocs]#