| Home | Libraries | People | FAQ | More

### StringToken

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.

##### Requirements

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 `string_token::arg`.
    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 `n`, otherwise throw an exception.
    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 `prepare` returned successfuly and the string token was not destroyed.

##### Algorithm Requirements

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
- 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

- `string_token::return_string`
- `string_token::assign_to`
- `string_token::preserve_size`
- `string_token::return_string`