:relfileprefix: ../../
[#boost-urls-format-05]

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


Format arguments into a URL


== Synopsis

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

[source,cpp,subs="verbatim,macros,-callouts"]
----
template<class... Args>
xref:boost/urls/url.adoc[url]
format(
    core::string_view fmt,
    Args&&... args);
----

== Description


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

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.

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

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.

=== 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_error`
| 
`fmt` contains an invalid format string and
the result contains an invalid URL after
replacements are applied.

|===


== Return Value


A URL holding the formatted result.



== Parameters

|===
| Name | Description 

| *fmt*
| 
The format URL string.

| *args*
| 
Arguments to be formatted.

|===




== See Also


xref:boost/urls/format_to-0b.adoc[format_to]
.