Diff coverage report for

//

//

// Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)

// Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/boostorg/url

// Official repository: https://github.com/boostorg/url

//

//

#ifndef BOOST_URL_FORMAT_HPP

#ifndef BOOST_URL_FORMAT_HPP

#define BOOST_URL_FORMAT_HPP

#define BOOST_URL_FORMAT_HPP

#include <boost/url/detail/config.hpp>

#include <boost/url/detail/config.hpp>

#include <boost/core/detail/string_view.hpp>

#include <boost/core/detail/string_view.hpp>

#include <boost/url/url.hpp>

#include <boost/url/url.hpp>

#include <boost/url/detail/vformat.hpp>

#include <boost/url/detail/vformat.hpp>

#include <initializer_list>

#include <initializer_list>

#ifdef BOOST_URL_HAS_CONCEPTS

#ifdef BOOST_URL_HAS_CONCEPTS

#include <concepts>

#include <concepts>

#endif

#endif

namespace boost {

namespace boost {

namespace urls {

namespace urls {

/** A temporary reference to a named formatting argument

/** A temporary reference to a named formatting argument

    This class represents a temporary reference

    This class represents a temporary reference

    to a named formatting argument used by the

    to a named formatting argument used by the

    @ref format function.

    @ref format function.

    Named arguments should always be created

    Named arguments should always be created

    with the @ref arg function.

    with the @ref arg function.

    Any type that can be formatted into a URL

    Any type that can be formatted into a URL

    with the @ref format function can also be used

    with the @ref format function can also be used

    in a named argument. All named arguments

    in a named argument. All named arguments

    are convertible to @ref format_arg and

    are convertible to @ref format_arg and

    can be used in the @ref format function.

    can be used in the @ref format function.

    @see

    @see

        @ref arg,

        @ref arg,

        @ref format,

        @ref format,

        @ref format_to,

        @ref format_to,

        @ref format_arg.

        @ref format_arg.

  */

  */

template <class T>

template <class T>

using named_arg = detail::named_arg<T>;

using named_arg = detail::named_arg<T>;

/** A temporary reference to a formatting argument

/** A temporary reference to a formatting argument

    This class represents a temporary reference

    This class represents a temporary reference

    to a formatting argument used by the

    to a formatting argument used by the

    @ref format function.

    @ref format function.

    A @ref format argument should always be

    A @ref format argument should always be

    created by passing the argument to be

    created by passing the argument to be

    formatted directly to the @ref format function.

    formatted directly to the @ref format function.

    Any type that can be formatted into a URL

    Any type that can be formatted into a URL

    with the @ref format function is convertible

    with the @ref format function is convertible

    to this type.

    to this type.

    This includes basic types, types convertible

    This includes basic types, types convertible

    to `core::string_view`, and @ref named_arg.

    to `core::string_view`, and @ref named_arg.

    @see

    @see

        @ref format,

        @ref format,

        @ref format_to,

        @ref format_to,

        @ref arg.

        @ref arg.

  */

  */

using format_arg = detail::format_arg;

using format_arg = detail::format_arg;

/** Format arguments into a URL

/** Format arguments into a URL

    Format arguments according to the format

    Format arguments according to the format

    URL string into a @ref url.

    URL string into a @ref url.

    The rules for a format URL string are the same

    The rules for a format URL string are the same

    as for a `std::format_string`, where replacement

    as for a `std::format_string`, where replacement

    fields are delimited by curly braces.

    fields are delimited by curly braces.

    The URL components to which replacement fields

    The URL components to which replacement fields

    belong are identified before replacement is

    belong are identified before replacement is

    applied and any invalid characters for that

    applied and any invalid characters for that

    formatted argument are percent-escaped.

    formatted argument are percent-escaped.

    Hence, the delimiters between URL components,

    Hence, the delimiters between URL components,

    such as `:`, `//`, `?`, and `#`, should be

    such as `:`, `//`, `?`, and `#`, should be

    included in the URL format string. Likewise,

    included in the URL format string. Likewise,

    a format string with a single `"{}"` is

    a format string with a single `"{}"` is

    interpreted as a path and any replacement

    interpreted as a path and any replacement

    characters invalid in this component will be

    characters invalid in this component will be

    encoded to form a valid URL.

    encoded to form a valid URL.

    @par Example

    @par Example

    @code

    @code

    assert(format("{}://{}:{}/rfc/{}",

    assert(format("{}://{}:{}/rfc/{}",

        "https", "www.ietf.org", 80, "rfc2396.txt"

        "https", "www.ietf.org", 80, "rfc2396.txt"

        ).buffer() == "https://www.ietf.org:80/rfc/rfc2396.txt");

        ).buffer() == "https://www.ietf.org:80/rfc/rfc2396.txt");

    @endcode

    @endcode

    Arguments that contain special characters are

    Arguments that contain special characters are

    automatically percent-encoded for the URL

    automatically percent-encoded for the URL

    component where they appear:

    component where they appear:

    @code

    @code

    assert(format("https://example.com/~{}",

    assert(format("https://example.com/~{}",

        "John Doe"

        "John Doe"

        ).buffer() == "https://example.com/~John%20Doe");

        ).buffer() == "https://example.com/~John%20Doe");

    @endcode

    @endcode

    @note

    @note

    The formatting machinery relies on language and library

    The formatting machinery relies on language and library

    features that are broken on GCC 4.8 and GCC 5.x, so this

    features that are broken on GCC 4.8 and GCC 5.x, so this

    function is not supported on those compilers.

    function is not supported on those compilers.

    @par Preconditions

    @par Preconditions

    All replacement fields must be valid and the

    All replacement fields must be valid and the

    resulting URL should be valid after arguments

    resulting URL should be valid after arguments

    are formatted into the URL.

    are formatted into the URL.

    Because any invalid characters for a URL

    Because any invalid characters for a URL

    component are encoded by this function, only

    component are encoded by this function, only

    replacements in the scheme and port components

    replacements in the scheme and port components

    might be invalid, as these components do not

    might be invalid, as these components do not

    allow percent-encoding of arbitrary

    allow percent-encoding of arbitrary

    characters.

    characters.

    @return A URL holding the formatted result.

    @return A URL holding the formatted result.

    @param fmt The format URL string.

    @param fmt The format URL string.

    @param args Arguments to be formatted.

    @param args Arguments to be formatted.

    @throws system_error

    @throws system_error

    `fmt` contains an invalid format string and

    `fmt` contains an invalid format string and

    the result contains an invalid URL after

    the result contains an invalid URL after

    replacements are applied.

    replacements are applied.

    @par BNF

    @par BNF

    @code

    @code

    replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"

    replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"

    arg_id            ::=  integer | identifier

    arg_id            ::=  integer | identifier

    integer           ::=  digit+

    integer           ::=  digit+

    digit             ::=  "0"..."9"

    digit             ::=  "0"..."9"

    identifier        ::=  id_start id_continue*

    identifier        ::=  id_start id_continue*

    id_start          ::=  "a"..."z" | "A"..."Z" | "_"

    id_start          ::=  "a"..."z" | "A"..."Z" | "_"

    id_continue       ::=  id_start | digit

    id_continue       ::=  id_start | digit

    @endcode

    @endcode

    @par Specification

    @par Specification

    @li <a href="https://fmt.dev/latest/syntax.html"

    @li <a href="https://fmt.dev/latest/syntax.html"

        >Format String Syntax</a>

        >Format String Syntax</a>

    @see

    @see

        @ref format_to,

        @ref format_to,

        @ref arg.

        @ref arg.

*/

*/

template <BOOST_URL_CONSTRAINT(std::convertible_to<format_arg>)... Args>

template <BOOST_URL_CONSTRAINT(std::convertible_to<format_arg>)... Args>

url

url

    core::string_view fmt,

    core::string_view fmt,

    Args&&... args)

    Args&&... args)

{

{

    return detail::vformat(

    return detail::vformat(

}

}

/** Format arguments into a URL

/** Format arguments into a URL

    Format arguments according to the format

    Format arguments according to the format

    URL string into a @ref url_base.

    URL string into a @ref url_base.

    The rules for a format URL string are the same

    The rules for a format URL string are the same

    as for a `std::format_string`, where replacement

    as for a `std::format_string`, where replacement

    fields are delimited by curly braces.

    fields are delimited by curly braces.

    The URL components to which replacement fields

    The URL components to which replacement fields

    belong are identified before replacement is

    belong are identified before replacement is

    applied and any invalid characters for that

    applied and any invalid characters for that

    formatted argument are percent-escaped.

    formatted argument are percent-escaped.

    Hence, the delimiters between URL components,

    Hence, the delimiters between URL components,

    such as `:`, `//`, `?`, and `#`, should be

    such as `:`, `//`, `?`, and `#`, should be

    included in the URL format string. Likewise,

    included in the URL format string. Likewise,

    a format string with a single `"{}"` is

    a format string with a single `"{}"` is

    interpreted as a path and any replacement

    interpreted as a path and any replacement

    characters invalid in this component will be

    characters invalid in this component will be

    encoded to form a valid URL.

    encoded to form a valid URL.

    @par Example

    @par Example

    @code

    @code

    static_url<50> u;

    static_url<50> u;

    format_to(u, "{}://{}:{}/rfc/{}",

    format_to(u, "{}://{}:{}/rfc/{}",

        "https", "www.ietf.org", 80, "rfc2396.txt");

        "https", "www.ietf.org", 80, "rfc2396.txt");

    assert(u.buffer() == "https://www.ietf.org:80/rfc/rfc2396.txt");

    assert(u.buffer() == "https://www.ietf.org:80/rfc/rfc2396.txt");

    @endcode

    @endcode

    @par Preconditions

    @par Preconditions

    All replacement fields must be valid and the

    All replacement fields must be valid and the

    resulting URL should be valid after arguments

    resulting URL should be valid after arguments

    are formatted into the URL.

    are formatted into the URL.

    Because any invalid characters for a URL

    Because any invalid characters for a URL

    component are encoded by this function, only

    component are encoded by this function, only

    replacements in the scheme and port components

    replacements in the scheme and port components

    might be invalid, as these components do not

    might be invalid, as these components do not

    allow percent-encoding of arbitrary

    allow percent-encoding of arbitrary

    characters.

    characters.

    @par Exception Safety

    @par Exception Safety

    Strong guarantee.

    Strong guarantee.

    @param u An object that derives from @ref url_base.

    @param u An object that derives from @ref url_base.

    @param fmt The format URL string.

    @param fmt The format URL string.

    @param args Arguments to be formatted.

    @param args Arguments to be formatted.

    @throws system_error

    @throws system_error

    `fmt` contains an invalid format string and

    `fmt` contains an invalid format string and

    `u` contains an invalid URL after replacements

    `u` contains an invalid URL after replacements

    are applied.

    are applied.

    @par BNF

    @par BNF

    @code

    @code

    replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"

    replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"

    arg_id            ::=  integer | identifier

    arg_id            ::=  integer | identifier

    integer           ::=  digit+

    integer           ::=  digit+

    digit             ::=  "0"..."9"

    digit             ::=  "0"..."9"

    identifier        ::=  id_start id_continue*

    identifier        ::=  id_start id_continue*

    id_start          ::=  "a"..."z" | "A"..."Z" | "_"

    id_start          ::=  "a"..."z" | "A"..."Z" | "_"

    id_continue       ::=  id_start | digit

    id_continue       ::=  id_start | digit

    @endcode

    @endcode

    @par Specification

    @par Specification

    @li <a href="https://fmt.dev/latest/syntax.html"

    @li <a href="https://fmt.dev/latest/syntax.html"

        >Format String Syntax</a>

        >Format String Syntax</a>

    @see

    @see

        @ref format.

        @ref format.

*/

*/

template <BOOST_URL_CONSTRAINT(std::convertible_to<format_arg>)... Args>

template <BOOST_URL_CONSTRAINT(std::convertible_to<format_arg>)... Args>

void

void

    url_base& u,

    url_base& u,

    core::string_view fmt,

    core::string_view fmt,

    Args&&... args)

    Args&&... args)

{

{

            std::forward<Args>(args)...));

            std::forward<Args>(args)...));

/** Format arguments into a URL

/** Format arguments into a URL

    Format arguments according to the format

    Format arguments according to the format

    URL string into a @ref url.

    URL string into a @ref url.

    This overload allows type-erased arguments

    This overload allows type-erased arguments

    to be passed as an initializer_list, which

    to be passed as an initializer_list, which

    is mostly convenient for named parameters.

    is mostly convenient for named parameters.

    All arguments must be convertible to a

    All arguments must be convertible to a

    implementation defined type able to store a

    implementation defined type able to store a

    type-erased reference to any valid format

    type-erased reference to any valid format

    argument.

    argument.

    The rules for a format URL string are the same

    The rules for a format URL string are the same

    as for a `std::format_string`, where replacement

    as for a `std::format_string`, where replacement

    fields are delimited by curly braces.

    fields are delimited by curly braces.

    The URL components to which replacement fields

    The URL components to which replacement fields

    belong are identified before replacement is

    belong are identified before replacement is

    applied and any invalid characters for that

    applied and any invalid characters for that

    formatted argument are percent-escaped.

    formatted argument are percent-escaped.

    Hence, the delimiters between URL components,

    Hence, the delimiters between URL components,

    such as `:`, `//`, `?`, and `#`, should be

    such as `:`, `//`, `?`, and `#`, should be

    included in the URL format string. Likewise,

    included in the URL format string. Likewise,

    a format string with a single `"{}"` is

    a format string with a single `"{}"` is

    interpreted as a path and any replacement

    interpreted as a path and any replacement

    characters invalid in this component will be

    characters invalid in this component will be

    encoded to form a valid URL.

    encoded to form a valid URL.

    @par Example

    @par Example

    @code

    @code

    assert(format(

    assert(format(

        "{scheme}://{host}:{port}/{dir}/{file}",

        "{scheme}://{host}:{port}/{dir}/{file}",

        {{"scheme", "https"}, {"port", 80},

        {{"scheme", "https"}, {"port", 80},

         {"host", "example.com"},

         {"host", "example.com"},

         {"dir", "path/to"},

         {"dir", "path/to"},

         {"file", "file.txt"}}

         {"file", "file.txt"}}

        ).buffer() == "https://example.com:80/path/to/file.txt");

        ).buffer() == "https://example.com:80/path/to/file.txt");

    @endcode

    @endcode

    @par Preconditions

    @par Preconditions

    All replacement fields must be valid and the

    All replacement fields must be valid and the

    resulting URL should be valid after arguments

    resulting URL should be valid after arguments

    are formatted into the URL.

    are formatted into the URL.

    Because any invalid characters for a URL

    Because any invalid characters for a URL

    component are encoded by this function, only

    component are encoded by this function, only

    replacements in the scheme and port components

    replacements in the scheme and port components

    might be invalid, as these components do not

    might be invalid, as these components do not

    allow percent-encoding of arbitrary

    allow percent-encoding of arbitrary

    characters.

    characters.

    @return A URL holding the formatted result.

    @return A URL holding the formatted result.

    @param fmt The format URL string.

    @param fmt The format URL string.

    @param args Arguments to be formatted.

    @param args Arguments to be formatted.

    @throws system_error

    @throws system_error

    `fmt` contains an invalid format string and

    `fmt` contains an invalid format string and

    the result contains an invalid URL after

    the result contains an invalid URL after

    replacements are applied.

    replacements are applied.

    @par BNF

    @par BNF

    @code

    @code

    replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"

    replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"

    arg_id            ::=  integer | identifier

    arg_id            ::=  integer | identifier

    integer           ::=  digit+

    integer           ::=  digit+

    digit             ::=  "0"..."9"

    digit             ::=  "0"..."9"

    identifier        ::=  id_start id_continue*

    identifier        ::=  id_start id_continue*

    id_start          ::=  "a"..."z" | "A"..."Z" | "_"

    id_start          ::=  "a"..."z" | "A"..."Z" | "_"

    id_continue       ::=  id_start | digit

    id_continue       ::=  id_start | digit

    @endcode

    @endcode

    @par Specification

    @par Specification

    @li <a href="https://fmt.dev/latest/syntax.html"

    @li <a href="https://fmt.dev/latest/syntax.html"

        >Format String Syntax</a>

        >Format String Syntax</a>

    @see

    @see

        @ref format_to.

        @ref format_to.

*/

*/

inline

inline

url

url

    core::string_view fmt,

    core::string_view fmt,

    std::initializer_list<format_arg> args)

    std::initializer_list<format_arg> args)

{

{

    return detail::vformat(

    return detail::vformat(

        fmt, detail::format_args(

        fmt, detail::format_args(

}

}

/** Format arguments into a URL

/** Format arguments into a URL

    Format arguments according to the format

    Format arguments according to the format

    URL string into a @ref url_base.

    URL string into a @ref url_base.

    This overload allows type-erased arguments

    This overload allows type-erased arguments

    to be passed as an initializer_list, which

    to be passed as an initializer_list, which

    is mostly convenient for named parameters.

    is mostly convenient for named parameters.

    All arguments must be convertible to a

    All arguments must be convertible to a

    implementation defined type able to store a

    implementation defined type able to store a

    type-erased reference to any valid format

    type-erased reference to any valid format

    argument.

    argument.

    The rules for a format URL string are the same

    The rules for a format URL string are the same

    as for a `std::format_string`, where replacement

    as for a `std::format_string`, where replacement

    fields are delimited by curly braces.

    fields are delimited by curly braces.

    The URL components to which replacement fields

    The URL components to which replacement fields

    belong are identified before replacement is

    belong are identified before replacement is

    applied and any invalid characters for that

    applied and any invalid characters for that

    formatted argument are percent-escaped.

    formatted argument are percent-escaped.

    Hence, the delimiters between URL components,

    Hence, the delimiters between URL components,

    such as `:`, `//`, `?`, and `#`, should be

    such as `:`, `//`, `?`, and `#`, should be

    included in the URL format string. Likewise,

    included in the URL format string. Likewise,

    a format string with a single `"{}"` is

    a format string with a single `"{}"` is

    interpreted as a path and any replacement

    interpreted as a path and any replacement

    characters invalid in this component will be

    characters invalid in this component will be

    encoded to form a valid URL.

    encoded to form a valid URL.

    @par Example

    @par Example

    @code

    @code

    url u;

    url u;

    format_to(u,

    format_to(u,

        "{scheme}://{host}:{port}/{dir}/{file}",

        "{scheme}://{host}:{port}/{dir}/{file}",

        {{"scheme", "https"}, {"port", 80},

        {{"scheme", "https"}, {"port", 80},

         {"host", "example.com"},

         {"host", "example.com"},

         {"dir", "path/to"},

         {"dir", "path/to"},

         {"file", "file.txt"}});

         {"file", "file.txt"}});

    assert(u.buffer() == "https://example.com:80/path/to/file.txt");

    assert(u.buffer() == "https://example.com:80/path/to/file.txt");

    @endcode

    @endcode

    @par Preconditions

    @par Preconditions

    All replacement fields must be valid and the

    All replacement fields must be valid and the

    resulting URL should be valid after arguments

    resulting URL should be valid after arguments

    are formatted into the URL.

    are formatted into the URL.

    Because any invalid characters for a URL

    Because any invalid characters for a URL

    component are encoded by this function, only

    component are encoded by this function, only

    replacements in the scheme and port components

    replacements in the scheme and port components

    might be invalid, as these components do not

    might be invalid, as these components do not

    allow percent-encoding of arbitrary

    allow percent-encoding of arbitrary

    characters.

    characters.

    @par Exception Safety

    @par Exception Safety

    Strong guarantee.

    Strong guarantee.

    @param u An object that derives from @ref url_base.

    @param u An object that derives from @ref url_base.

    @param fmt The format URL string.

    @param fmt The format URL string.

    @param args Arguments to be formatted.

    @param args Arguments to be formatted.

    @throws system_error

    @throws system_error

    `fmt` contains an invalid format string and

    `fmt` contains an invalid format string and

    `u` contains an invalid URL after replacements

    `u` contains an invalid URL after replacements

    are applied.

    are applied.

    @par BNF

    @par BNF

    @code

    @code

    replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"

    replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"

    arg_id            ::=  integer | identifier

    arg_id            ::=  integer | identifier

    integer           ::=  digit+

    integer           ::=  digit+

    digit             ::=  "0"..."9"

    digit             ::=  "0"..."9"

    identifier        ::=  id_start id_continue*

    identifier        ::=  id_start id_continue*

    id_start          ::=  "a"..."z" | "A"..."Z" | "_"

    id_start          ::=  "a"..."z" | "A"..."Z" | "_"

    id_continue       ::=  id_start | digit

    id_continue       ::=  id_start | digit

    @endcode

    @endcode

    @par Specification

    @par Specification

    @li <a href="https://fmt.dev/latest/syntax.html"

    @li <a href="https://fmt.dev/latest/syntax.html"

        >Format String Syntax</a>

        >Format String Syntax</a>

    @see

    @see

        @ref format.

        @ref format.

*/

*/

inline

inline

void

void

    url_base& u,

    url_base& u,

    core::string_view fmt,

    core::string_view fmt,

    std::initializer_list<format_arg> args)

    std::initializer_list<format_arg> args)

{

{

        u, fmt, detail::format_args(

        u, fmt, detail::format_args(

            args.begin(), args.end()));

            args.begin(), args.end()));

/** Designate a named argument for a replacement field

/** Designate a named argument for a replacement field

    Construct a named argument for a format URL

    Construct a named argument for a format URL

    string that contains named replacement fields.

    string that contains named replacement fields.

    The function parameters should be convertible

    The function parameters should be convertible

    to an implementation defined type able to

    to an implementation defined type able to

    store the name and a reference to any type

    store the name and a reference to any type

    potentially used as a format argument.

    potentially used as a format argument.

    @par Example

    @par Example

    @code

    @code

    assert(format(

    assert(format(

        "https://example.com/~{username}",

        "https://example.com/~{username}",

        arg("username", "mark")

        arg("username", "mark")

        ).buffer() == "https://example.com/~mark");

        ).buffer() == "https://example.com/~mark");

    @endcode

    @endcode

    @return A temporary object with reference

    @return A temporary object with reference

    semantics for a named argument

    semantics for a named argument

    @param name The format argument name

    @param name The format argument name

    @param arg The format argument value

    @param arg The format argument value

    @see

    @see

        @ref format,

        @ref format,

        @ref format_to.

        @ref format_to.

*/

*/

template <class T>

template <class T>

named_arg<T>

named_arg<T>

{

{

}

}

} // url

} // url

} // boost

} // boost

#endif

#endif