[#boost-urls-string_token-StringToken]
= xref:boost.adoc[boost]::xref:boost/urls.adoc[urls]::xref:boost/urls/string_token.adoc[string_token]::StringToken
:relfileprefix: ../../../
:mrdocs:


Concept for a string token

== Synopsis


Declared in `<https://www.github.com/boostorg/url/blob/develop/include/boost/url/grammar/string_token.hpp#L228[boost/url/grammar/string_token.hpp]>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
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 xref:boost/urls/string_token/arg.adoc[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:

[,cpp]
----
struct StringToken : string_token::arg
{
    using result_type = std::string;

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

    result_type result();
};
----
Algorithm prototype:

[,cpp]
----
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&period;

* return&lowbar;string
    
* assign&lowbar;to
    
* preserve&lowbar;size





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