boost::urls::string_token::StringToken

Concept for a string token

Synopsis

Declared in <boost/url/grammar/string_token.hpp>

template<class T>
concept StringToken = std::derived_from<T, string_token::arg> &&
    requires (T t, std::size_t n)
{
    typename T::result_type;
    { t.prepare(n) } ‐> std::same_as<char*>;
    { t.result() } ‐> std::convertible_to<typename T::result_type>;
};

Description

This concept is satisfied if T is a valid string token type.

A string token is an rvalue passed to a function template which customizes the return type of the function and also controls how a modifiable character buffer is obtained and presented.

The string token's lifetime extends only for the duration of the function call in which it appears as a parameter.

A string token cannot be copied, moved, or assigned, and must be destroyed when the function returns or throws.

Semantics

T::result_type determines the return type of functions that accept a string token.

The prepare() function overrides the virtual function in the base class arg. It must return a pointer to a character buffer of at least size n, otherwise throw an exception. This function is called only once or not at all.

The result() function is invoked by the algorithm to receive the result from the string token. It is only invoked if prepare() returned successfully and the string token was not destroyed. It is only called after prepare() returns successfully, and the string token is destroyed when the algorithm completes or if an exception is thrown.

String tokens cannot be reused.

Exemplars

String token prototype:

struct StringToken : string_token::arg
{
    using result_type = std::string;

    char* prepare( std::size_t n ) override;

    result_type result();
};

Algorithm prototype:

namespace detail {

// Algorithm implementation may be placed
// out of line, and written as an ordinary
// function (no template required).
void algorithm_impl( string_token::arg& token )
{
    std::size_t n = 0;

    // calculate space needed in n
    // ...

    // acquire a destination buffer
    char* dest = token.prepare( n );

    // write the characters to the buffer
}
} // detail

// public interface is a function template,
// defaulting to return std::string.
template< class StringToken = string_token::return_string >
auto
algorithm( StringToken&& token = {} ) ->
    typename StringToken::result_type
{
    // invoke the algorithm with the token
    algorithm_impl( token );

    // return the result from the token
    return token.result();
}

Models

The following classes and functions implement and generate string tokens.

  • return_string

  • assign_to

  • preserve_size

Created with MrDocs