[#boost-urls-format]
= 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#L142[boost&sol;url&sol;format&period;hpp]&gt;`

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

[.small]#xref:boost/urls/format-05.adoc[_» more..._]#

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

[.small]#xref:boost/urls/format-02.adoc[_» more..._]#

== Description


Format arguments according to the format    URL string into a xref:boost/urls/url.adoc[url]&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("{}", "Hello world!").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;


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

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



== Exceptions


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


|===
| Name | Description

| *fmt*
| The format URL string&period;


| *args*
| Arguments to be formatted&period;


|===

== See Also


xref:boost/urls/format_to-0b.adoc[format&lowbar;to],        xref:boost/urls/arg.adoc[arg]&period;






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