//
// Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
//
// Official repository: https://github.com/boostorg/url
//

= String Token

Functions which perform percent-decoding return values using cpp: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.

[source,cpp]
----
include::example$unit/snippets.cpp[tag=snippet_string_token_1,indent=0]
----

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__ cpp:string_token::assign_to[] can be used to assign
the decoded value to an existing string:

[source,cpp]
----
include::example$unit/snippets.cpp[tag=snippet_string_token_2,indent=0]
----

The __StringToken__ cpp:string_token::append_to[] can be used to append
the decoded value to an existing string:

[source,cpp]
----
include::example$unit/snippets.cpp[tag=snippet_string_token_3,indent=0]
----

The __StringToken__ cpp:string_token::preserve_size[] can be used to
return a cpp:string_view[] instead of a cpp:std::string[].
The underlying storage for the cpp:string_view[] is
provided to the token.

[source,cpp]
----
include::example$unit/snippets.cpp[tag=snippet_string_token_4,indent=0]
----

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

The trait cpp:string_token::is_token[] can be used to determine if a type
is a __StringToken__:

[source,cpp]
----
include::example$unit/snippets.cpp[tag=snippet_string_token_5,indent=0]
----