[#boost-urls-string_token-StringToken]
= xref:boost.adoc[boost]::xref:boost/urls.adoc[urls]::xref:boost/urls/string_token.adoc[string&lowbar;token]::StringToken
:relfileprefix: ../../../
:mrdocs:

Concept for a string token

== Synopsis

Declared in `&lt;https://www.github.com/boostorg/url/blob/develop/include/boost/url/grammar/string_token.hpp#L231[boost&sol;url&sol;grammar&sol;string&lowbar;token&period;hpp]&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;class T&gt;
concept StringToken = std&colon;&colon;derived&lowbar;from&lt;T, string&lowbar;token&colon;&colon;arg&gt; &amp;&amp;
    requires (T t, std&colon;&colon;size&lowbar;t n)
&lcub;
    typename T&colon;&colon;result&lowbar;type&semi;
    &lcub; t&period;prepare(n) &rcub; &hyphen;&gt; std&colon;&colon;same&lowbar;as&lt;char&ast;&gt;&semi;
    &lcub; t&period;result() &rcub; &hyphen;&gt; std&colon;&colon;convertible&lowbar;to&lt;typename T&colon;&colon;result&lowbar;type&gt;&semi;
&rcub;;
----

== Description

This concept is satisfied if `T` is a valid string token type&period;

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&period;

The string token&apos;s lifetime extends only for the duration of the function call in which it appears as a parameter&period;

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

== Semantics

`T&colon;&colon;result&lowbar;type` determines the return type of functions that accept a string token&period;

The `prepare()` function overrides the virtual function in the base class xref:boost/urls/string_token/arg.adoc[`arg`]&period; It must return a pointer to a character buffer of at least size `n`, otherwise throw an exception&period; This function is called only once or not at all&period;

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

String tokens cannot be reused&period;

== Exemplars

String token prototype&colon;

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

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

    result_type result();
};
----
Algorithm prototype&colon;

[,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]#
