validate_transcodable_asο
ztd::text::validate_transcodable_as
is a function that takes an input sequence of code_unit
s and attempts to validate that they can be turned into the code_point
s of the provided encoding. Unlike the ztd::text::count_as_decoded function, this does not take an error handler. Any error, even if it would be corrected over, produces a stop in the algorithm and a validate_result/stateless_validate_result object gets returned with the .valid
member set to false.
The overloads of this function increase the level of control 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_validate_transcodable_as(input, from_encoding, to_encoding, decode_state, encode_state)
extension point, if possible.An internal, implementation-defined customization point.
The
basic_validate_transcodable_as
base function.
The base function call, basic_validate_transcodable_as
, simply performs the core validating loop using the Lucky 7 design. The reason the last overload takes 2 state arguments is due to how the base implementation works from the core validating loop. If during the 3-argument overload it is detected that text_validate_transcodable_as(input, encoding, decode_state)
can be called, it will be called without attempt to create an encode_state
value with ztd::text::make_encode_state(β¦).
During the basic_validate_transcodable_as
loop, if it detects that there is a preferable text_validate_transcodable_as_one
, it will call that method as text_validate_transcodable_as_one(input, encoding, decode_state)
inside of the loop rather than doing the core design.
The ztd::text::validate_result type only includes the decode_state
in all cases.
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_validate_transcodable_as
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 _DecodeState, typename _EncodeState, typename _Pivot>
constexpr auto basic_validate_transcodable_as(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _DecodeState &__decode_state, _EncodeState &__encode_state, _Pivot &&__pivot)ο Validates the code units of the
__input
according to the__from_encoding
with the given states__decode_state
and__encode_state
to see if it can be turned into code points, and then code units again.Remark
This function explicitly does not call any extension points. It defers to doing a typical loop over the code points to verify it can be decoded into code points, and then encoded back into code units, with no errors and with the exact same value sequence as the original.
- Parameters
__input β [in] The input range of code units to validate is possible for encoding into code points.
__from_encoding β [in] The encoding to verify can properly encode the input of code units.
__to_encoding β [in] The encoding to verify can properly encode the input of code units.
__decode_state β [inout] The state to use for the decoding portion of the validation check.
__encode_state β [inout] The state to use for the encoding portion of the validation check.
__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.
-
template<typename _Input, typename _FromEncoding, typename _ToEncoding, typename _DecodeState, typename _EncodeState, typename _Pivot>
constexpr auto validate_transcodable_as(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _DecodeState &__decode_state, _EncodeState &__encode_state, _Pivot &&__pivot)ο Validates the code units of the
__input
according to the__encoding
with the given states__decode_state
and__encode_state
to see if it can be turned into code points.Remark
This functions checks to see if extension points for
text_validate_transcodable_as
is available taking the available 4 parameters. If so, it calls this. Otherwise, it defers to ztd::text::validate_transcodable_as.- Parameters
__input β [in] The input range of code units to validate is possible for encoding into code points.
__from_encoding β [in] The encoding to verify can properly encode the input of code units.
__to_encoding β [in] The encoding to verify can properly encode the input of code units.
__decode_state β [inout] The state to use for the decoding portion of the validation check.
__encode_state β [inout] The state to use for the encoding portion of the validation check.
__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.
-
template<typename _Input, typename _FromEncoding, typename _ToEncoding, typename _DecodeState, typename _EncodeState>
constexpr auto validate_transcodable_as(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _DecodeState &__decode_state, _EncodeState &__encode_state)ο Validates the code units of the
__input
according to the__encoding
with the given states__decode_state
and__encode_state
to see if it can be turned into code points.Remark
This functions checks to see if extension points for
text_validate_transcodable_as
is available taking the available 4 parameters. If so, it calls this. Otherwise, it defers to ztd::text::validate_transcodable_as.- Parameters
__input β [in] The input range of code units to validate is possible for encoding into code points.
__from_encoding β [in] The encoding to verify can properly encode the input of code units.
__to_encoding β [in] The encoding to verify can properly encode the input of code units.
__decode_state β [inout] The state to use for the decoding portion of the validation check.
__encode_state β [inout] The state to use for the encoding portion of the validation check.
-
template<typename _Input, typename _FromEncoding, typename _ToEncoding, typename _DecodeState>
constexpr auto validate_transcodable_as(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding, _DecodeState &__decode_state)ο Validates the code units of the
__input
according to the__from_encoding
object with the given state__decode_state
to see if it can be turned into code units of the__to_encoding
object.Remark
This functions will call ztd::text::make_encode_state with
__to_encoding
to create a defaultencode_state
.- Parameters
__input β [in] The input range of code units to validate is possible for encoding into code points.
__from_encoding β [in] The encoding to verify can properly encode the input of code units.
__to_encoding β [in] The encoding to verify can properly encode the input of code units.
__decode_state β [inout] The state to use for the decoding portion of the validation check.
-
template<typename _Input, typename _FromEncoding, typename _ToEncoding>
constexpr auto validate_transcodable_as(_Input &&__input, _FromEncoding &&__from_encoding, _ToEncoding &&__to_encoding)ο Validates the code units of the
__input
according to the__from_encoding
object to see if it can be turned into code units of the__to_encoding
object.Remark
This functions will call ztd::text::make_decode_state with the
__from_encoding
object to create a defaultdecode_state
to use before passing it to the next overload.- Parameters
__input β [in] The input range of code units to validate is possible for encoding into code points.
__from_encoding β [in] The encoding to verify can properly encode the input of code units.
__to_encoding β [in] The encoding to verify can properly encode the input of code units.
-
template<typename _Input, typename _ToEncoding>
constexpr auto validate_transcodable_as(_Input &&__input, _ToEncoding &&__to_encoding)ο Validates the code units of the
__input
according to the__from_encoding
object to see if it can be turned into code units of the__to_encoding
object.Remark
This functions will call ztd::text::make_encode_state with
__to_encoding
to create a defaultencode_state
.- Parameters
__input β [in] The input range of code units to validate is possible for encoding into code points.
__to_encoding β [in] The encoding to verify can properly encode the input of code units.