| Home | Libraries | People | FAQ | More

##### format_to (1 of 2 overloads)

Format arguments into a URL.

###### Synopsis

Defined in header `<boost/url/format.hpp>`

    template<
        class... Args>
    void
    format_to(
        url_base& u,
        core::string_view fmt,
        Args&&... args);

###### Description

Format arguments according to the format URL string into a `url_base`. The rules for a format URL string are the same as for a `std::format_string`, where replacement fields are delimited by curly braces. The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent-escaped. Hence, the delimiters between URL components, such as `:`, `//`, `?`, and `#`, should be included in the URL format string. Likewise, a format string with a single `"{}"` is interpreted as a path and any replacement characters invalid in this component will be encoded to form a valid URL.

###### Example

    static_url<30> u;
    format(u, "{}" , "Hello world!" );
    assert(u.buffer() == "Hello%20world%21" );

###### Preconditions

All replacement fields must be valid and the resulting URL should be valid after arguments are formatted into the URL. Because any invalid characters for a URL component are encoded by this function, only replacements in the scheme and port components might be invalid, as these components do not allow percent-encoding of arbitrary characters.

###### Exception Safety

Strong guarantee.

###### Parameters

Name | Description
--- | ---
`u` | An object that derives from `url_base`.
`fmt` | The format URL string.
`args` | Arguments to be formatted.

###### Exceptions

Type | Thrown On
--- | ---
`system_error` | `fmt` contains an invalid format string and `u` contains an invalid URL after replacements are applied.

###### BNF

    replacement_field ::=  "{" [arg_id] [ ":" (format_spec | chrono_format_spec)] "}"
    arg_id            ::=  integer | identifier
    integer           ::=  digit+
    digit             ::=  "0" ... "9"
    identifier        ::=  id_start id_continue*
    id_start          ::=  "a" ... "z" | "A" ... "Z" | "_"
    id_continue       ::=  id_start | digit

###### Specification

- Format String Syntax

###### See Also

`format`.

Convenience header `<boost/url.hpp>`