String Token :: Boost Libraries Documentation

# String Token

Functions which perform percent-decoding return values using `std::string` when called without special arguments. This is the best default for ergonomics, and a good enough default for performance considering that many decoded strings fit in the small buffer available to most standard implementations.

    url_view u("http://www.example.com/my%20file.txt");
    pct_string_view sv = u.encoded_path();
    assert(sv == "/my%20file.txt");
    std::string s = u.path();
    assert(s == "/my file.txt");

Some use-cases may desire more control over how these algorithms acquire and store data in strings, for example:

- Returning a string using a non-default allocator

- Reusing the storage of an existing string

- Appending to existing strings

The library provides a special customization mechanism called StringToken to control how algorithms which require an output buffer acquire their storage.

The StringToken `string_token::assign_to` can be used to assign the decoded value to an existing string:

    url_view u("http://www.example.com/my%20file.txt");
    std::string s = "existing string";
    u.path(string_token::assign_to(s));
    assert(s == "/my file.txt");

The StringToken `string_token::append_to` can be used to append the decoded value to an existing string:

    url_view u("http://www.example.com/my%20file.txt");
    std::string s = "existing string";
    u.path(string_token::append_to(s));
    assert(s == "existing string/my file.txt");

The StringToken `string_token::preserve_size` can be used to return a `string_view` instead of a `std::string`. The underlying storage for the `string_view` is provided to the token.

    url_view u("http://www.example.com/my%20file.txt");
    std::string s = "existing string";
    boost::core::string_view sv = u.path(string_token::preserve_size(s));
    assert(sv == "/my file.txt");

When no customization is provided, the default behavior is to use the default `string_token::return_string` token which returns a `std::string`.

The trait `string_token::is_token` can be used to determine if a type is a StringToken:

    static_assert(
        string_token::is_token<string_token::return_string>::value);

Edit this Page