| Home | Libraries | People | FAQ | More

##### url::set_encoded_host_address

Set the host to an address.

###### Synopsis

    url&
    set_encoded_host_address(
        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, then the host is set to that address. The host type is `host_type::ipv6`.
- If the string is a valid IPvFuture, 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

    assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

###### Postconditions

    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.

###### Exceptions

Type | Thrown On
--- | ---
`system_error` | `s` contains an invalid percent-encoding.

###### Parameters

Name | Description
--- | ---
`s` | The string to set.

###### BNF

    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

- IPv4 (Wikipedia)
- IP Version 6 Addressing Architecture (rfc4291)
- 3.2.2. Host (rfc3986)

###### See Also

`set_encoded_host`, `set_encoded_host_name`, `set_host`, `set_host_address`, `set_host_ipv4`, `set_host_ipv6`, `set_host_ipvfuture`, `set_host_name`.