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

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

  • append_to

  • assign_to

  • preserve_size

  • append_to