mirror of
https://github.com/boostorg/url.git
synced 2026-01-31 08:42:22 +00:00
67 lines
2.1 KiB
Plaintext
67 lines
2.1 KiB
Plaintext
//
|
|
// 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]
|
|
----
|
|
|