count_as_transcoded

ztd::text::count_as_transcoded is a function that takes an input sequence of code_units 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).