count_as_transcodedο
ztd::text::count_as_transcoded
is a function that takes an input sequence of code_unit
s and attempts to count them, according to the error handler that is given. Because the error handler is included as part of the function call (and is provided by default is one is not passed in), the count operation will also continue to count if the error handler sets the error_code
member of the result to ztd::text::encoding_error::ok
but still performs some action. This is, for example, the case with ztd::text::replacement_handler_t - output replacement code units or code points will be counted as part of the final count and returned with result.error_code == ztd::text::encoding_error::ok
. You can differentiate error-less text from non-error text by checking result.errors_were_handled()
, which will be true if the error handler is called regardless of whether or not the error handler βsmoothsβ the problem over by inserting replacement characters, doing nothing, or otherwise.
The overloads of this function increase the level of control you have with each passed argument. At the last overload with four arguments, the function attempts to work call some extension points or falls back to the base function call in this order:
The
text_count_as_transcoded(input, from_encoding, to_encoding, from_handler, to_handler, from_state, to_state)
extension point, if possible.An internal, implementation-defined customization point.
The
basic_count_as_transcoded
base function.
The base function call, basic_count_as_transcoded
, simply performs the core counting loop using the Lucky 7 design.
During the basic_count_as_transcoded
loop, if it detects that there is a preferable text_count_as_transcoded_one
, it will call that method as text_count_as_transcoded_one(input, encoding, handler, state)
inside of the loop rather than doing the core design.
Note
π This means that if you implement none of the extension points whatsoever, implementing the basic decode_one
and encode_one
functions 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_count_as_transcoded
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.
Functionsο
-
template<typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto basic_count_as_transcoded(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot)ο Counts the number of code units that will result from attempting an transcode operation on the input code points.
Remark
This method will not check any ADL extension points. A combination of implementation techniques will be used to count code units, with a loop over the
.encode_one
/.decode_one
call into an intermediate, unseen buffer being the most basic choice.- Parameters
__input β [in] The input range (of code units) to find out how many code units of the transcoded output there are.
__from_encoding β [in] The encoding that is going to be used to decode the input into an intermediary output.
__to_encoding β [in] The encoding that is going to be used to encode the intermediary output.
__from_error_handler β [in] The error handler to invoke when an intermediary decoding operation fails.
__to_error_handler β [in] The error handler to invoke when the final encoding operation fails.
__from_state β [inout] The state attached to the
__from_encoding
that will be used for the intermediary decode step.__to_state β [inout] The state related to the
__to_encoding
that will be used for the final encoding step.__pivot β [inout] A reference to a descriptor of a (potentially usable) pivot range, usually a range of contiguous data from a span provided by the implementation but customizable by the end-user. If the intermediate conversion is what failed, then the ztd::text::pivotβs
error_code
member will be set to that error. This only happens if the overall operation also fails, and need not be checked unless to obtain additional information for when a top-level operation fails.
- Returns
A ztd::text::count_result that includes information about how many code units are present, taking into account any invoked errors (like replacement from ztd::text::replacement_handler_t) and a reference to the provided
__from_state
and__to_state
.
-
template<typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState, typename _Pivot>
constexpr auto count_as_transcoded(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state, _Pivot &&__pivot)ο Counts the number of code units that will result from attempting an transcode operation on the input code points.
Remark
This method checks for the ADL extension point
text_count_as_transcoded
. It will be called if it is possible. Otherwise, this function will defer to ztd::text::basic_count_as_transcoded.- Parameters
__input β [in] The input range (of code units) to find out how many code units of the transcoded output there are.
__from_encoding β [in] The encoding that is going to be used to decode the input into an intermediary output.
__to_encoding β [in] The encoding that is going to be used to encode the intermediary output.
__from_error_handler β [in] The error handler to invoke when an intermediary decoding operation fails.
__to_error_handler β [in] The error handler to invoke when the final encoding operation fails.
__from_state β [inout] The state attached to the
__from_encoding
that will be used for the intermediary decode step.__to_state β [inout] The state related to the
__to_encoding
that will be used for the final encoding step.__pivot β [inout] A reference to a descriptor of a (potentially usable) pivot range, usually a range of contiguous data from a span provided by the implementation but customizable by the end-user. If the intermediate conversion is what failed, then the ztd::text::pivotβs
error_code
member will be set to that error. This only happens if the overall operation also fails, and need not be checked unless to obtain additional information for when a top-level operation fails.
- Returns
A ztd::text::count_result that includes information about how many code units are present, taking into account any invoked errors (like replacement from ztd::text::replacement_handler_t) and a reference to the provided
__from_state
and__to_state
.
-
template<typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState, typename _ToState>
constexpr auto count_as_transcoded(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state, _ToState &__to_state)ο Counts the number of code units that will result from attempting an transcode operation on the input code points.
Remark
This method will call ztd::text::count_as_transcoded(input, from_encoding, to_encoding, from_error_handler, to_error_handler, from_state, to_state) with an
to_state
created by ztd::text::make_encode_state(to_encoding).- Parameters
__input β [in] The input range (of code units) to find out how many code units of the transcoded output there are.
__from_encoding β [in] The encoding that is going to be used to decode the input into an intermediary output.
__to_encoding β [in] The encoding that is going to be used to encode the intermediary output.
__from_error_handler β [in] The error handler to invoke when an intermediary decoding operation fails.
__to_error_handler β [in] The error handler to invoke when the final encoding operation fails.
__from_state β [inout] The state attached to the
__from_encoding
that will be used for the intermediary decode step.__to_state β [inout] The state attached to the
__to_encoding
that will be used for the final encode step.
- Returns
A ztd::text::stateless_count_result that includes information about how many code units are present, taking into account any invoked errors (like replacement from ztd::text::replacement_handler_t).
-
template<typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler, typename _FromState>
constexpr auto count_as_transcoded(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler, _FromState &__from_state)ο Counts the number of code units that will result from attempting an transcode operation on the input code points.
Remark
This method will call ztd::text::count_as_transcoded(input, from_encoding, to_encoding, from_error_handler, to_error_handler, from_state, to_state) with an
to_state
created by ztd::text::make_encode_state(to_encoding).- Parameters
__input β [in] The input range (of code units) to find out how many code units of the transcoded output there are.
__from_encoding β [in] The encoding that is going to be used to decode the input into an intermediary output.
__to_encoding β [in] The encoding that is going to be used to encode the intermediary output.
__from_error_handler β [in] The error handler to invoke when an intermediary decoding operation fails.
__to_error_handler β [in] The error handler to invoke when the final encoding operation fails.
__from_state β [inout] The state attached to the
__from_encoding
that will be used for the intermediary decode step.
- Returns
A ztd::text::stateless_count_result that includes information about how many code units are present, taking into account any invoked errors (like replacement from ztd::text::replacement_handler_t).
-
template<typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler, typename _ToErrorHandler>
constexpr auto count_as_transcoded(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler, _ToErrorHandler &&__to_error_handler)ο Counts the number of code units that will result from attempting an transcode operation on the input code points.
Remark
This method will call ztd::text::count_as_transcoded(input, from_encoding, to_encoding, from_error_handler, to_error_handler, from_state) with an
from_state
created by ztd::text::make_decode_state(from_encoding).- Parameters
__input β [in] The input range (of code units) to find out how many code units of the transcoded output there are.
__from_encoding β [in] The encoding that is going to be used to decode the input into an intermediary output.
__to_encoding β [in] The encoding that is going to be used to encode the intermediary output.
__from_error_handler β [in] The error handler to invoke when the decode portion of the transcode operation fails.
__to_error_handler β [in] The error handler to invoke when the encode portion of the transcode operation fails.
- Returns
A ztd::text::stateless_count_result that includes information about how many code units are present, taking into account any invoked errors (like replacement from ztd::text::replacement_handler_t).
-
template<typename _Input, typename _FromEncoding, typename _ToEncoding, typename _FromErrorHandler>
constexpr auto count_as_transcoded(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _FromErrorHandler &&__from_error_handler)ο Counts the number of code units that will result from attempting an transcode operation.
Remark
This method will call ztd::text::count_as_transcoded(input, from_encoding, to_encoding, from_error_handler, to_error_handler) by creating an
to_error_handler
similar to ztd::text::default_handler_t.- Parameters
__input β [in] The input range (of code units) to find out how many code units of the transcoded output there are.
__from_encoding β [in] The encoding that is going to be used to decode the input into an intermediary output.
__to_encoding β [in] The encoding that is going to be used to encode the intermediary output.
__from_error_handler β [in] The error handler to invoke when the decode portion of the transcode operation fails.
- Returns
A ztd::text::stateless_count_result that includes information about how many code units are present, taking into account any invoked errors (like replacement from ztd::text::replacement_handler_t).
-
template<typename _Input, typename _FromEncoding, typename _ToEncoding>
constexpr auto count_as_transcoded(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding)ο Counts the number of code units that will result from attempting an transcode operation.
Remark
This method will call ztd::text::count_as_transcoded(Input, Encoding, ErrorHandler) by creating an
error_handler
similar to ztd::text::default_handler_t.- Parameters
__input β [in] The input range (of code units) to find out how many code units of the transcoded output there are.
__from_encoding β [in] The encoding that is going to be used to decode the input into an intermediary output.
__to_encoding β [in] The encoding that is going to be used to encode the intermediary output.
- Returns
A ztd::text::stateless_count_result that includes information about how many code units are present, taking into account any invoked errors (like replacement from ztd::text::replacement_handler_t).
-
template<typename _Input, typename _ToEncoding>
constexpr auto count_as_transcoded(_Input &&__input, _ToEncoding &&__to_encoding)ο Counts the number of code units that will result from attempting an transcode operation on the input code points.
Remark
Calls ztd::text::count_as_transcoded(Input, Encoding) with an
encoding
that is derived from ztd::text::default_code_unit_encoding.- Parameters
__input β [in] The input range (of code units) to find out how many code units of the transcoded output there are.
__to_encoding β [in] The encoding that is going to be used to encode the input into an intermediary output.
- Returns
A ztd::text::stateless_count_result that includes information about how many code units are present, taking into account any invoked errors (like replacement from ztd::text::replacement_handler_t).