[#boost-urls-format-02]
= xref:boost.adoc[boost]::xref:boost/urls.adoc[urls]::format
:relfileprefix: ../../
:mrdocs:

Format arguments into a URL

== Synopsis

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

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
xref:boost/urls/url.adoc[url]
format(
    core::string&lowbar;view fmt,
    std::initializer&lowbar;list&lt;format&lowbar;arg&gt; args);
----

== Description

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

This overload allows type&hyphen;erased arguments to be passed as an initializer&lowbar;list, which is mostly convenient for named parameters&period;

All arguments must be convertible to a implementation defined type able to store a type&hyphen;erased reference to any valid format argument&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]
----
assert(format(
    "{scheme}://{host}:{port}/{dir}/{file}",
    {{"scheme", "https"}, {"port", 80},
     {"host", "example.com"},
     {"dir", "path/to"},
     {"file", "file.txt"}}
    ).buffer() == "https://example.com:80/path/to/file.txt");
----
== 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;

== 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="1,4"]
|===
| Name
| Thrown on
| `system&lowbar;error`
| `fmt` contains an invalid format string and the result contains an invalid URL after replacements are applied&period;
|===

== Return Value

A URL holding the formatted result&period;

== Parameters

[cols="1,4"]
|===
|Name|Description

| *fmt*
| The format URL string&period;
| *args*
| Arguments to be formatted&period;
|===

== See Also

xref:boost/urls/format_to-01.adoc[`format&lowbar;to`]&period;


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