[#boost-urls-format_to-02]
= xref:boost.adoc[boost]::xref:boost/urls.adoc[urls]::format&lowbar;to
:relfileprefix: ../../
:mrdocs:

Format arguments into a URL

== Synopsis

Declared in `&lt;https://www.github.com/boostorg/url/blob/develop/include/boost/url/format.hpp#L225[boost&sol;url&sol;format&period;hpp]&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;std::convertible&lowbar;to&lt;format&lowbar;arg&gt;&period;&period;&period; Args&gt;
void
format&lowbar;to(
    xref:boost/urls/url_base.adoc[url&lowbar;base]& u,
    core::string&lowbar;view fmt,
    Args&period;&period;&period;&&&period;&period;&period; args);
----

== Description

Format arguments according to the format URL string into a xref:boost/urls/url_base.adoc[`url&lowbar;base`]&period;

The rules for a format URL string are the same as for a `std&colon;&colon;format&lowbar;string`, where replacement fields are delimited by curly braces&period;

The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent&hyphen;escaped&period;

Hence, the delimiters between URL components, such as `&colon;`, `&sol;&sol;`, `?`, and `&num;`, should be included in the URL format string&period; Likewise, a format string with a single `&quot;&lcub;&rcub;&quot;` is interpreted as a path and any replacement characters invalid in this component will be encoded to form a valid URL&period;

== Example

[,cpp]
----
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&period;

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&hyphen;encoding of arbitrary characters&period;

== Exception Safety

Strong guarantee&period;

== BNF

[,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
----
== Specification

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

== Exceptions

[cols=2]
|===
| Name
| Thrown on
| `system&lowbar;error`
| `fmt` contains an invalid format string and `u` contains an invalid URL after replacements are applied&period;
|===

== Parameters

[cols=2]
|===
| Name
| Description
| *u*
| An object that derives from xref:boost/urls/url_base.adoc[`url&lowbar;base`]&period;
| *fmt*
| The format URL string&period;
| *args*
| Arguments to be formatted&period;
|===

== See Also

xref:boost/urls/format-06.adoc[`format`]&period;


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