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