:relfileprefix: ../../
[#boost-urls-format_to-0b]

== xref:boost.adoc[pass:[boost]]::xref:boost/urls.adoc[pass:[urls]]::format_to


Format arguments into a URL


=== Synopsis

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

[source,cpp,subs="verbatim,macros,-callouts"]
----
void
format_to(
    xref:boost/urls/url_base.adoc[url_base]& u,
    core::string_view fmt,
    std::initializer_list<pass:q[_see-below_]> args);
----

=== Description


Format arguments according to the format
URL string into a
xref:boost/urls/url_base.adoc[url_base]
.

This overload allows type-erased arguments
to be passed as an initializer_list, which
is mostly convenient for named parameters.

All arguments must be convertible to a
implementation defined type able to store a
type-erased reference to any valid format
argument.

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 `:`, `&sol;&sol;`, `?`, 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.
[,cpp]
----
static_url<30> u;
format_to(u, "user/{id}", {{"id", 1}})
assert(u.buffer() == "user/1");
----

=== 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.

=== Strong guarantee.
[,cpp]
----
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
----

* link:https://fmt.dev/latest/syntax.html[Format String Syntax]



=== Exceptions

|===
| Name | Thrown on

| ``fmt``
| 
contains an invalid format string and
`u` contains an invalid URL after replacements
are applied.

|===



=== Parameters

|===
| Name | Description 

| *u*
| 
An object that derives from
xref:boost/urls/url_base.adoc[url_base]
.

| *fmt*
| 
The format URL string.

| *args*
| 
Arguments to be formatted.

|===




=== See Also


xref:boost/urls/format-02.adoc[format]
.



