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