:relfileprefix: ../../../
[#boost-urls-url-set_encoded_host_address]

= xref:boost.adoc[pass:[boost]]::xref:boost/urls.adoc[pass:[urls]]::xref:boost/urls/url.adoc[pass:[url]]::set_encoded_host_address


Set the host to an address


== Synopsis

Declared in header `<https://www.github.com/boostorg/url/blob/develop/include/boost/url/url.hpp#L444[boost/url/url.hpp,window=blank_]>`

[source,cpp,subs="verbatim,macros,-callouts"]
----
xref:boost/urls/url.adoc[url]&
set_encoded_host_address(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
xref:boost/urls/host_type/ipv4.adoc[host_type::ipv4]
.

* If the string is a valid IPv6 address,
then the host is set to that address.
The host type is
xref:boost/urls/host_type/ipv6.adoc[host_type::ipv6]
.

* If the string is a valid IPvFuture,
then the host is set to that address.
The host type is
xref:boost/urls/host_type/ipvfuture.adoc[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
xref:boost/urls/host_type/name.adoc[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-&gt;size() + s.size()`.

=== Exception Safety

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

=== BNF
[,cpp]
----
IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

IPvFuture     = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

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.adoc[set_encoded_host]
,
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]
.