Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the master branch, built from commit 5002c2d6a2.
PrevUpHomeNext

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:

Table 1.12. 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:

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


PrevUpHomeNext