transcode
The transcode
grouping of functions (transcode
, transcode_to
, and transcode_into_raw
) perform the task of doing bulk transcoding from an input
of code_unit
s to a second encoding’s code_unit
type. It expects to traffic through the code_point
type as the intermediary between the two functions. There is also a transcode_one
API as well that does a single indivisible unit of work for both decoding (to a common representation) and then encoding, and has the same variants as the bulk function.
Named Groups
There are 3 named functions for this behavior, and each function comes with several function overloads. Each named function produces increasingly more information, letting you opt into just how much information and control you’d like over the algorithm and behavior. The first one simply returns a container with the transformation applied, discarding much of the operation’s result information. This is useful for quick, one-off conversions where you do not care about any errors and would rather let it be handled by the error handler. The second _to
suffixed functions return a container within a result
type that contains additional information. The final _into
suffixed functions take an output range to write into, letting you explicitly control just how much space there is to write into as well as returning a detailed result
type.
The return type for these function calls is one of:
the desired output container (highest level);
ztd::text::transcode_result or ztd::text::stateless_transcode_result with the desired output container embedded as the .output parameter (mid level); or,
ztd::text::transcode_result or ztd::text::stateless_transcode_result returning just the input and output ranges (lowest level).
transcode(...)
This is the highest level bulk function.
This set of function overloads takes the provided input
, from_encoding
, to_encoding
, from_handler
, to_handler
, from_state
, and to_state
and produces an output container type. The default container will either be a std::basic_string
of the code_unit
type, or a std::vector
if it is not a known “character” type.
The container type can be specified by passing it as an explicit template parameter to this function, such as ztd::text::transcode<std::vector<char16_t>>("bark", ztd::text::utf16{});
. The output container is default constructed.
It will either call push_back
/insert
directly on the target container to fill it up, or serialize data to a temporary buffer (controlled by ZTD_TEXT_INTERMEDIATE_TRANSCODE_BUFFER_BYTE_SIZE) before then copying it into the desired output container through any available means (bulk .insert
, repeated .push_back
, or repeated single .insert
with the .cend()
iterator in that order).
This is the “fire and forget” version of the transcode
function, returning only the container and not returning any of the result or state information used to construct it.
transcode_to(...)
This is the mid level bulk function.
This set of function overloads takes the provided input
, from_encoding
, to_encoding
, from_handler
, to_handler
, from_state
, and to_state
and produces an output container type that is embedded within a ztd::text::transcode_result, or a ztd::text::stateless_transcode_result, depending on whether or not you called the version which takes a ztd::text::decode_state_t<Encoding> and/or a ztd::text::encode_state_t<Encoding> as a parameter or if it had to create one on the stack internally and discard it after the operation was finished.
The container type can be specified by passing it as an explicit template parameter to this function, such as ztd::text::transcode_to<std::string>(U"meow", ascii{});
. The output container is default constructed.
It will either call push_back
/insert
directly on the target container to fill it up, or serialize data to a temporary buffer (controlled by ZTD_TEXT_INTERMEDIATE_TRANSCODE_BUFFER_BYTE_SIZE) before then copying it into the desired output container through any available means (bulk .insert
, repeated .push_back
, or repeated single .insert
with the .cend()
iterator in that order).
If nothing goes wrong or the error handler lets the algorithm continue, .input
on the result should be empty.
transcode_into_raw(...)
This is the lowest level bulk function.
This set of function overloads takes the provided input
, from_encoding
, output
, to_encoding
, from_handler
, to_handler
, from_state
, and to_state
to write data into an output range specified by output
. The result is a ztd::text::transcode_result, or a ztd::text::stateless_transcode_result, depending on whether or not you called the version which takes a ztd::text::decode_state_t<Encoding> and/or a ztd::text::encode_state_t<Encoding> as a parameter or if it had to create one on the stack internally and discard it after the operation was finished.
It is up to the end-user to provide a suitably-sized output range for output
, otherwise this operation may return with ztd::text::encoding_error::insufficient_output. for the result
‘s error_code
member. The amount of space consumed can be determined by checking the std::distance
between the .begin()
of the original output
parameter and the .begin()
of the returned .output
member. The result also has error information and an .input
member for checking how much input was consumed.
If nothing goes wrong or the error handler lets the algorithm continue, .input
on the result should be empty.
For Everything
All named functions have 6 overloads. Each of the “higher level” functions, at the end of their overload call chain, will call the lower-level transcode_into_raw
to perform the work. The final transcode_into_raw
call uses the following ordering of extension points into calling the base implementation:
The
text_transcode_into_raw(input, from_encoding, output, to_encoding, ...)
extension point.An implementation-defined extension point if any internal optimizations are possible.
The
basic_transcode_into_raw(input, from_encoding, output, to_encoding, ...)
function.
The final function call, basic_transcode_into_raw
, simply performs the core transcode loop using the Lucky 7 design. basic_transcode_into_raw
accommodates the lowest level transformation using just decode_one
into a suitably sized intermediate buffer and then an encode_one
into the output, calling the relevant error handlers along the way. This design also means minimal stack space is used, keeping the core algorithm suitable for resource-constrained devices.
However, there is a caveat: if there exists a text_transcode_one(input, from_encoding, output, to_encoding, ...)
that is callable then it will be called to perform one unit of complete transformation. Otherwise, decode_one
/encode_one
The transcode_one
extension point is also used in the ztd::text::transcode_view<…> to speed up one-by-one translations for iteration-based types, where possible.
Note
👉 This means that if you implement none of the extension points whatsoever, implementing the basic decode_one
function of the from_encoding
and the transcode_one
of the to_encoding
function on your Encoding Object type will guarantee a proper, working implementation.
Note
👉 If you need to call the “basic” form of this function that takes no secret implementation shortcuts or user-defined extension points, then call basic_transcode_into_raw
directly. This can be useful to stop infinity loops when your extension points cannot handle certain inputs and thereby needs to “delegate” to the basic case.
Bulk Functions
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto basic_transcode_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function detects whether or not the ADL extension point
text_transcode
can be called with the provided parameters. If so, it will use that ADL extension point over the default implementation. Otherwise, it will loop over the two encodings and attempt to transcode by first decoding the input code units to code points, then encoding the intermediate code points to the desired, output code units.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handlers for the from and to encodings, respectively.
__to_error_handler – [in] The error handlers for the from and to encodings, respectively.
__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.__pivot – [inout] A reference to a descriptor of a (potentially usable) range as the intermediate pivot, usually a range of contiguous data from a span provided by the implementation but can be passed in here by the user.
- Returns
A ztd::text::transcode_result object that contains references to
__from_state
and__to_state
.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto transcode_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function detects whether or not the ADL extension point
text_transcode
can be called with the provided parameters. If so, it will use that ADL extension point over the default implementation. Otherwise, it will loop over the two encodings and attempt to transcode by first decoding the input code units to code points, then encoding the intermediate code points to the desired, output code units.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handlers for the from and to encodings, respectively.
__to_error_handler – [in] The error handlers for the from and to encodings, respectively.
__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.__pivot – [inout] A reference to a descriptor of a (potentially usable) range as the intermediate pivot, usually a range of contiguous data from a span provided by the implementation but can be passed in here by the user.
- Returns
A ztd::text::transcode_result object that contains references to
__from_state
and__to_state
.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState>
constexpr auto transcode_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function detects whether or not the ADL extension point
text_transcode
can be called with the provided parameters. If so, it will use that ADL extension point over the default implementation. Otherwise, it will loop over the two encodings and attempt to transcode by first decoding the input code units to code points, then encoding the intermediate code points to the desired, output code units.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handlers for the from and to encodings, respectively.
__to_error_handler – [in] The error handlers for the from and to encodings, respectively.
__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.
- Returns
A ztd::text::pivotless_transcode_result object that contains references to
__from_state
and__to_state
.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState>
constexpr auto transcode_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function calls the base reference, the ztd::text::transcode_into_raw after creating a
to_state
from ztd::text::make_encode_state. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.
- Returns
A ztd::text::stateless_transcode_result object.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler>
constexpr auto transcode_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates a decode state
from_state
by calling ztd::text::make_decode_state. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::pivotless_transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler>
constexpr auto transcode_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates an
to_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it. This matters for lossy conversions that are not injective. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::pivotless_transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding>
constexpr auto transcode_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates an
from_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it. This matters for lossy conversions that are not injective. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::pivotless_transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
-
template<typename _Input, typename _ToEncoding, typename _Output>
constexpr auto transcode_into_raw(_Input &&__input, _ToEncoding &&__to_encoding, _Output &&__output) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates both: a
from_error_handler
using a ztd::text::default_handler_t that is marked as careless to pass to the next function overload; and, afrom_encoding
to interpret the__input
by checking the__input
‘svalue_type.
This matters for lossy conversions that are not injective. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::pivotless_transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto transcode_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function detects whether or not the ADL extension point
text_transcode
can be called with the provided parameters. If so, it will use that ADL extension point over the default implementation. Otherwise, it will loop over the two encodings and attempt to transcode by first decoding the input code units to code points, then encoding the intermediate code points to the desired, output code units.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handlers for the from and to encodings, respectively.
__to_error_handler – [in] The error handlers for the from and to encodings, respectively.
__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.__pivot – [inout] A reference to a descriptor of a (potentially usable) range as the intermediate pivot, usually a range of contiguous data from a span provided by the implementation but can be passed in here by the user.
- Returns
A ztd::text::pivotless_transcode_result object that contains references to
__from_state
and__to_state
.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState>
constexpr auto transcode_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function detects whether or not the ADL extension point
text_transcode
can be called with the provided parameters. If so, it will use that ADL extension point over the default implementation. Otherwise, it will loop over the two encodings and attempt to transcode by first decoding the input code units to code points, then encoding the intermediate code points to the desired, output code units.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handlers for the from and to encodings, respectively.
__to_error_handler – [in] The error handlers for the from and to encodings, respectively.
__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.
- Returns
A ztd::text::pivotless_transcode_result object that contains references to
__from_state
and__to_state
.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState>
constexpr auto transcode_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function calls the base reference, the ztd::text::transcode_into after creating a
to_state
from ztd::text::make_encode_state. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::pivotless_transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.
- Returns
A ztd::text::stateless_transcode_result object.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler>
constexpr auto transcode_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates a decode state
from_state
by calling ztd::text::make_decode_state. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::pivotless_transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler>
constexpr auto transcode_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates an
to_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it. This matters for lossy conversions that are not injective. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::pivotless_transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding>
constexpr auto transcode_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates an
from_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it. This matters for lossy conversions that are not injective. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::pivotless_transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
-
template<typename _Input, typename _ToEncoding, typename _Output>
constexpr auto transcode_into(_Input &&__input, _ToEncoding &&__to_encoding, _Output &&__output) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates both: a
from_error_handler
using a ztd::text::default_handler_t that is marked as careless to pass to the next function overload; and, afrom_encoding
to interpret the__input
by checking the__input
‘svalue_type.
This matters for lossy conversions that are not injective. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::pivotless_transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto transcode_to(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.__pivot – [inout] A reference to a descriptor of a (potentially usable) range as the intermediate pivot, usually a range of contiguous data from a span provided by the implementation but can be passed in here by the user.
- Returns
A ztd::text::transcode_result object that contains references to
__from_state
and__to_state
and anoutput
parameter that contains the_OutputContainer
specified. If the container has acontainer.reserve
function, it is and some multiple of the input’s size is used to pre-size the container, to aid withpush_back
/insert
reallocation pains.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState>
constexpr auto transcode_to(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.
- Returns
A ztd::text::pivotless_transcode_result object that contains references to
__from_state
and__to_state
and anoutput
parameter that contains the_OutputContainer
specified. If the container has acontainer.reserve
function, it is and some multiple of the input’s size is used to pre-size the container, to aid withpush_back
/insert
reallocation pains.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState>
constexpr auto transcode_to(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
A default state for the encode step of the operation is create using ztd::text::make_encode_state. The return type is stateless since both states must be passed in. If you want to have access to the states, create both of them yourself and pass them into a lower-level function that accepts those parameters.
- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.
- Returns
A ztd::text::stateless_transcode_result object that contains references to an
container.output
parameter that contains the_OutputContainer
specified.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler>
constexpr auto transcode_to(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
A default state for the decode step of the operation is create using ztd::text::make_decode_state. The return type is stateless since both states must be passed in. If you want to have access to the states, create both of them yourself and pass them into a lower-level function that accepts those parameters.
- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.
- Returns
A ztd::text::stateless_transcode_result object that contains references to an
container.output
parameter that contains the_OutputContainer
specified.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler>
constexpr auto transcode_to(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
A
to_error_handler
for the encode step of the operation is created using default construction of a ztd::text::default_handler_t that is marked as careless. The return type is stateless since both states must be passed in. If you want to have access to the states, create both of them yourself and pass them into a lower-level function that accepts those parameters.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.
- Returns
A ztd::text::stateless_transcode_result object that contains references to an
container.output
parameter that contains the_OutputContainer
specified.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding>
constexpr auto transcode_to(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
A
from_error_handler
for the encode step of the operation is created using default construction of a ztd::text::default_handler_t that is marked as careless. The return type is stateless since both states must be passed in. If you want to have access to the states, create both of them yourself and pass them into a lower-level function that accepts those parameters.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
- Returns
A ztd::text::stateless_transcode_result object that contains references to an
container.output
parameter that contains the_OutputContainer
specified.
-
template<typename _OutputContainer = void, typename _Input, typename _ToEncoding>
constexpr auto transcode_to(_Input &&__input, _ToEncoding &&__to_encoding) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
A
from_error_handler
for the encode step of the operation is created using default construction of a ztd::text::default_handler_t that is marked as careless. The return type is stateless since both states must be passed in. If you want to have access to the states, create both of them yourself and pass them into a lower-level function that accepts those parameters.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
- Returns
A ztd::text::stateless_transcode_result object that contains references to an
container.output
parameter that contains the_OutputContainer
specified.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto transcode(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.__pivot – [inout] A reference to a descriptor of a (potentially usable) range as the intermediate pivot, usually a range of contiguous data from a span provided by the implementation but can be passed in here by the user.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_to or ztd::text::transcode_into_raw.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState>
constexpr auto transcode(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_to or ztd::text::transcode_into_raw.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState>
constexpr auto transcode(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
This function creates an
to_state
for the encoding step of the operation using ztd::text::make_encode_state.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_to or ztd::text::transcode_into_raw.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler>
constexpr auto transcode(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
This function creates an
from_state
for the encoding step of the operation using ztd::text::make_decode_state.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_to or ztd::text::transcode_into_raw.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler>
constexpr auto transcode(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
This function creates a
to_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it. This matters for lossy conversions that are not injective.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_to or ztd::text::transcode_into_raw.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding>
constexpr auto transcode(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
This function creates a
from_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it. This matters for lossy conversions that are not injective.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_to or ztd::text::transcode_into_raw.
-
template<typename _OutputContainer = void, typename _Input, typename _ToEncoding>
constexpr auto transcode(_Input &&__input, _ToEncoding &&__to_encoding) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
This function creates both: a
from_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it; and, afrom_encoding
derived from the__input
’svalue_type.
The careless marking matters for lossy conversions that are not injective.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a
std::basic_string
or astd::vector
of some sort.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_to or ztd::text::transcode_into_raw.
Single Functions
-
template<typename _Input, typename _Output, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto basic_transcode_one_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view. nly one.
Remark
This function detects whether or not the ADL extension point
text_transcode
can be called with the provided parameters. If so, it will use that ADL extension point over the default implementation. Otherwise, it will loop over the two encodings and attempt to transcode by first decoding the input code units to code points, then encoding the intermediate code points to the desired, output code units.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handlers for the from and to encodings, respectively.
__to_error_handler – [in] The error handlers for the from and to encodings, respectively.
__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.__pivot – [inout] A reference to a descriptor of a (potentially usable) range as the intermediate pivot, usually a range of contiguous data from a span provided by the implementation but can be passed in here by the user.
- Returns
A ztd::text::transcode_result object that contains references to
__from_state
and__to_state
.
-
template<typename _Input, typename _Output, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto transcode_one_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view. Only performs one distinct unit of encoding.
Remark
This function detects whether or not the ADL extension point
text_transcode_one
can be called with the provided parameters. If so, it will use that ADL extension point over the default implementation. Otherwise, it will loop over the two encodings and attempt to transcode by first decoding the input code units to code points, then encoding the intermediate code points to the desired, output code units.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handlers for the from and to encodings, respectively.
__to_error_handler – [in] The error handlers for the from and to encodings, respectively.
__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.__pivot – [inout] A reference to a descriptor of a (potentially usable) range as the intermediate pivot, usually a range of contiguous data from a span provided by the implementation but can be passed in here by the user.
- Returns
A ztd::text::transcode_result object that contains references to
__from_state
and__to_state
.
-
template<typename _Input, typename _Output, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState>
constexpr auto transcode_one_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view. Only performs one distinct unit of encoding.
Remark
This function detects whether or not the ADL extension point
text_transcode_one
can be called with the provided parameters. If so, it will use that ADL extension point over the default implementation. Otherwise, it will loop over the two encodings and attempt to transcode by first decoding the input code units to code points, then encoding the intermediate code points to the desired, output code units.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handlers for the from and to encodings, respectively.
__to_error_handler – [in] The error handlers for the from and to encodings, respectively.
__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.
- Returns
A ztd::text::transcode_result object that contains references to
__from_state
and__to_state
.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState>
constexpr auto transcode_one_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function calls the base reference, the ztd::text::transcode_one_into_raw after creating a
to_state
from ztd::text::make_encode_state. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.
- Returns
A ztd::text::stateless_transcode_result object.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler>
constexpr auto transcode_one_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates a decode state
from_state
by calling ztd::text::make_decode_state. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler>
constexpr auto transcode_one_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates an
to_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it. This matters for lossy conversions that are not injective. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding>
constexpr auto transcode_one_into_raw(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates an
from_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it. This matters for lossy conversions that are not injective. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
-
template<typename _Input, typename _ToEncoding, typename _Output>
constexpr auto transcode_one_into_raw(_Input &&__input, _ToEncoding &&__to_encoding, _Output &&__output) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates both: a
from_error_handler
using a ztd::text::default_handler_t that is marked as careless to pass to the next function overload; and, afrom_encoding
to interpret the__input
by checking the__input
‘svalue_type.
This matters for lossy conversions that are not injective. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
-
template<typename _Input, typename _Output, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto basic_transcode_one_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view. Only performs one distinct unit of encoding.
Remark
This function detects whether or not the ADL extension point
text_transcode_one
can be called with the provided parameters. If so, it will use that ADL extension point over the default implementation. Otherwise, it will loop over the two encodings and attempt to transcode by first decoding the input code units to code points, then encoding the intermediate code points to the desired, output code units.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handlers for the from and to encodings, respectively.
__to_error_handler – [in] The error handlers for the from and to encodings, respectively.
__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.__pivot – [inout] A reference to a descriptor of a (potentially usable) range as the intermediate pivot, usually a range of contiguous data from a span provided by the implementation but can be passed in here by the user.
- Returns
A ztd::text::transcode_result object that contains references to
__from_state
and__to_state
.
-
template<typename _Input, typename _Output, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto transcode_one_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view. Only performs one distinct unit of encoding.
Remark
This function detects whether or not the ADL extension point
text_transcode_one
can be called with the provided parameters. If so, it will use that ADL extension point over the default implementation. Otherwise, it will loop over the two encodings and attempt to transcode by first decoding the input code units to code points, then encoding the intermediate code points to the desired, output code units.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handlers for the from and to encodings, respectively.
__to_error_handler – [in] The error handlers for the from and to encodings, respectively.
__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.__pivot – [inout] A reference to a descriptor of a (potentially usable) range as the intermediate pivot, usually a range of contiguous data from a span provided by the implementation but can be passed in here by the user.
- Returns
A ztd::text::transcode_result object that contains references to
__from_state
and__to_state
.
-
template<typename _Input, typename _Output, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState>
constexpr auto transcode_one_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view. Only performs one distinct unit of encoding.
Remark
This function detects whether or not the ADL extension point
text_transcode_one
can be called with the provided parameters. If so, it will use that ADL extension point over the default implementation. Otherwise, it will loop over the two encodings and attempt to transcode by first decoding the input code units to code points, then encoding the intermediate code points to the desired, output code units.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handlers for the from and to encodings, respectively.
__to_error_handler – [in] The error handlers for the from and to encodings, respectively.
__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.
- Returns
A ztd::text::transcode_result object that contains references to
__from_state
and__to_state
.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState>
constexpr auto transcode_one_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function calls the base reference, the ztd::text::transcode_one_into after creating a
to_state
from ztd::text::make_encode_state. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.
- Returns
A ztd::text::stateless_transcode_result object.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler>
constexpr auto transcode_one_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates a decode state
from_state
by calling ztd::text::make_decode_state. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding, typename _FromErrorHandler>
constexpr auto transcode_one_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates an
to_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it. This matters for lossy conversions that are not injective. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.
-
template<typename _Input, typename _FromEncoding, typename _Output, typename _ToEncoding>
constexpr auto transcode_one_into(_Input &&__input, _FromEncoding &&__from_encoding, _Output &&__output, _ToEncoding &&__to_encoding) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates an
from_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it. This matters for lossy conversions that are not injective. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
-
template<typename _Input, typename _ToEncoding, typename _Output>
constexpr auto transcode_one_into(_Input &&__input, _ToEncoding &&__to_encoding, _Output &&__output) Converts the code units of the given input view through the from encoding to code units of the to encoding into the output view.
Remark
This function creates both: a
from_error_handler
using a ztd::text::default_handler_t that is marked as careless to pass to the next function overload; and, afrom_encoding
to interpret the__input
by checking the__input
‘svalue_type.
This matters for lossy conversions that are not injective. The result from this function returns a ztd::text::stateless_transcode_result as opposed to a ztd::text::transcode_result because the state information is on the stack, and returning the state in those types by reference will result in references to memory that has already been cleaned up. If you need access to the state parameters, call the lower-level functionality with your own created states.- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__output – [in] An output_view to write code units to as the result of the encode operation from the intermediate code points.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto transcode_one_to(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.__pivot – [inout] A reference to a descriptor of a (potentially usable) range as the intermediate pivot, usually a range of contiguous data from a span provided by the implementation but can be passed in here by the user.
- Returns
A ztd::text::transcode_result object that contains references to
__from_state
and__to_state
and anoutput
parameter that contains the_OutputContainer
specified. If the container has acontainer.reserve
function, it is and some multiple of the input’s size is used to pre-size the container, to aid withpush_back
/insert
reallocation pains.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState>
constexpr auto transcode_one_to(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.
- Returns
A ztd::text::transcode_result object that contains references to
__from_state
and__to_state
and anoutput
parameter that contains the_OutputContainer
specified. If the container has acontainer.reserve
function, it is and some multiple of the input’s size is used to pre-size the container, to aid withpush_back
/insert
reallocation pains.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState>
constexpr auto transcode_one_to(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
A default state for the encode step of the operation is create using ztd::text::make_encode_state. The return type is stateless since both states must be passed in. If you want to have access to the states, create both of them yourself and pass them into a lower-level function that accepts those parameters.
- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.
- Returns
A ztd::text::stateless_transcode_result object that contains references to an
container.output
parameter that contains the_OutputContainer
specified.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler>
constexpr auto transcode_one_to(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
A default state for the decode step of the operation is create using ztd::text::make_decode_state. The return type is stateless since both states must be passed in. If you want to have access to the states, create both of them yourself and pass them into a lower-level function that accepts those parameters.
- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.
- Returns
A ztd::text::stateless_transcode_result object that contains references to an
container.output
parameter that contains the_OutputContainer
specified.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler>
constexpr auto transcode_one_to(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
A
to_error_handler
for the encode step of the operation is created using default construction of a ztd::text::default_handler_t that is marked as careless. The return type is stateless since both states must be passed in. If you want to have access to the states, create both of them yourself and pass them into a lower-level function that accepts those parameters.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.
- Returns
A ztd::text::stateless_transcode_result object that contains references to an
container.output
parameter that contains the_OutputContainer
specified.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding>
constexpr auto transcode_one_to(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
A
from_error_handler
for the encode step of the operation is created using default construction of a ztd::text::default_handler_t that is marked as careless. The return type is stateless since both states must be passed in. If you want to have access to the states, create both of them yourself and pass them into a lower-level function that accepts those parameters.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
- Returns
A ztd::text::stateless_transcode_result object that contains references to an
container.output
parameter that contains the_OutputContainer
specified.
-
template<typename _OutputContainer, typename _Input, typename _ToEncoding>
constexpr auto transcode_one_to(_Input &&__input, _ToEncoding &&__to_encoding) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
A
from_error_handler
for the encode step of the operation is created using default construction of a ztd::text::default_handler_t that is marked as careless. The return type is stateless since both states must be passed in. If you want to have access to the states, create both of them yourself and pass them into a lower-level function that accepts those parameters.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
- Returns
A ztd::text::stateless_transcode_result object that contains references to an
container.output
parameter that contains the_OutputContainer
specified.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto transcode_one(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.__pivot – [inout] A reference to a descriptor of a (potentially usable) range as the intermediate pivot, usually a range of contiguous data from a span provided by the implementation but can be passed in here by the user.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_one_to or ztd::text::transcode_one_into.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState>
constexpr auto transcode_one(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.__to_state – [inout] A reference to the associated state for the
__to_encoding
‘s encode step.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_one_to or ztd::text::transcode_one_into.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState>
constexpr auto transcode_one(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
This function creates an
to_state
for the encoding step of the operation using ztd::text::make_encode_state.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.__from_state – [inout] A reference to the associated state for the
__from_encoding
‘s decode step.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_one_to or ztd::text::transcode_one_into.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler>
constexpr auto transcode_one(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
This function creates an
from_state
for the encoding step of the operation using ztd::text::make_decode_state.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.__to_error_handler – [in] The error handler for the
__to_encoding
‘s encode step.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_one_to or ztd::text::transcode_one_into.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler>
constexpr auto transcode_one(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
This function creates a
to_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it. This matters for lossy conversions that are not injective.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
__from_error_handler – [in] The error handler for the
__from_encoding
‘s decode step.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_one_to or ztd::text::transcode_one_into.
-
template<typename _OutputContainer = void, typename _Input, typename _FromEncoding, typename _ToEncoding>
constexpr auto transcode_one(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
This function creates a
from_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it. This matters for lossy conversions that are not injective.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__from_encoding – [in] The encoding that will be used to decode the input’s code units into intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_one_to or ztd::text::transcode_one_into.
-
template<typename _OutputContainer = void, typename _Input, typename _ToEncoding>
constexpr auto transcode_one(_Input &&__input, _ToEncoding &&__to_encoding) Converts the code units of the given input view through the from encoding to code units of the to encoding for the output, which is then returned in a result structure with additional information about success.
Remark
This function creates both: a
from_error_handler
from a class like ztd::text::default_handler_t, but that is marked as careless since you did not explicitly provide it; and, afrom_encoding
derived from the"__input"'s
value_type.
The careless marking matters for lossy conversions that are not injective.- Template Parameters
_OutputContainer – The container to default-construct and serialize data into. Typically, a fixed-size container of some sort.
- Parameters
__input – [in] An input_view to read code units from and use in the decode operation that will produce intermediate code points.
__to_encoding – [in] The encoding that will be used to encode the intermediate code points into the final code units.
- Returns
An
_OutputContainer
with the result, regardless of whether an error occurs or not. If you are looking for error information and not just a quick one-off conversion function, please use ztd::text::transcode_one_to or ztd::text::transcode_one_into.