...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
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.
In this table:
T
is a type meeting the
requirements of StringToken
t
is an rvalue reference
of type T
n
is a value of type
std::size_t
Table 1.39. Valid expressions
Expression |
Result |
Semantics, Pre/Post-conditions |
---|---|---|
std::derived_from<T,string_token::arg> |
true
|
All string tokens must be publicly and unambiguously derived from
|
T::result_type |
This type determines the return type of functions which accept a string token. |
|
t.prepare(n); |
char* |
This function overrides the virtual function in the base. It must
return a pointer to a character buffer of at least size |
t.result(); |
T::result_type |
This function is invoked by the algorithm to receive the result
from the string token. It is only invoked if |
When an algorithm accepts a string token, it must meet these requirements:
prepare
is called only
once or not at all,
result
is only called
after prepare
returns
successfully, and
String tokens cannot be reused.
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