replacement_handlerο
The replacement_handler_t
is the go-to error handling class. It is also the ztd::text::default_handler unless configured otherwise.
Replacement works by using several different hooks on the provided encoding objects, or by falling back to some defaults if certain conditions are met. The user-controllable hooks are:
encoding.replacement_code_units(...)
, a function (which can bestatic
orconstexpr
) that returns a range of code units to insert directly into an output stream on a failedencode
operation. It can also be called as a secondary backup if andecode
operation fails, whereupon it will use the values in the range to attemptdecode
ing them into the output if possible. It can be empty, to indicate that nothing is to be inserted.encoding.replacement_code_points(...)
, a function (which can bestatic
orconstexpr
) that returns a range of code points to insert directly into an output stream on a faileddecode
operation. It can also be called as a secondary backup if anencode
operation fails, whereupon it will use the values in the range to attemptencode
ing them into the output if possible. It can be empty, to indicate that nothing is to be inserted.encoding.maybe_replacement_code_units(...)
, a function (which can bestatic
orconstexpr
) that returns a maybe-range. If the expressionif (maybe_returned_range)
evaluates totrue
, it will get the range returned by the function by performing a dereference ofdecltype(auto) returned_range = *maybe_returned_range;
. If the conditional expression does not evaluate totrue
, it will assume that nothing can be returned from the function. This is useful for runtime-only encodings or encodings that wrap other encodings and may not have a replacement function. The dereferenced returned range is used exactly as its non-maybe
counterpart.encoding.maybe_replacement_code_points(...)
, a function (which can bestatic
orconstexpr
) that returns a maybe-range. If the expressionif (maybe_returned_range)
evaluates totrue
, it will get the range returned by the function by performing a dereference ofdecltype(auto) returned_range = *maybe_returned_range;
. If the conditional expression does not evaluate totrue
, it will assume that nothing can be returned from the function. This is useful for runtime-only encodings or encodings that wrap other encodings and may not have a replacement function. The dereferenced returned range is used exactly as its non-maybe
counterpart.
Each replacement handler can take the current encode_state
/decode_state
parameter for its desired operation, if it so chooses. This will allow replacements to hook into the statefulness of any given encoding operation. It will call replacement_code_units(state)
first, if itβs well-formed. Otherwise, it will call replacement_code_units()
. It will do this with each of the 4 replacement functions mentioned above.
After a replacement is done (if any), the function will then skip over bad input. The skipping is done by calling ztd::text::skip_input_error(β¦) with the encoding and result object, before returning, and after replacements are done.
-
constexpr replacement_handler_t ztd::text::replacement_handler = {}ο
A convenience variable for passing the replacement_handler_t handler to functions.
-
class replacement_handler_tο
An error handler that replaces bad code points and code units with a chosen code point / code unit sequence.
Remark
This class hooks into the encodings passed as the first parameter to the error handling functions to see if they define either
replacement_code_points()
orreplacement_code_units()
function. If so, they will call them and use the returned contiguous range to isnert code points or code units into the function. If neither of these exist, then it checks for a definition of amaybe_replacement_code_points()
or amaybe_replacement_code_units()
function. If either is present, they are expected to return astd::optional
of a contiguous range. If it is engaged (thestd::optional
is filled) it will be used. Otherwise, if it is not engaged, then it will explicitly fall back to attempt to insert the default replacement characterU
+FFFD (U'οΏ½'
) or?
character. If the output is out of room for the desired object, then nothing will be inserted at all.Subclassed by default_handler_t
Public Functions
-
template<typename _Encoding, typename _Input, typename _Output, typename _State, typename _InputProgress, typename _OutputProgress>
inline constexpr auto operator()(const _Encoding &__encoding, encode_result<_Input, _Output, _State> __result, const _InputProgress &__input_progress, const _OutputProgress &__output_progress) const noexcept(::ztd::text::is_nothrow_skip_input_error_v<const _Encoding&, encode_result<_Input, _Output, _State>, const _InputProgress&, const _OutputProgress&>)ο The function call for inserting replacement code units at the point of failure, before returning flow back to the caller of the encode operation.
- Parameters
__encoding β [in] The Encoding that experienced the error.
__result β [in] The current state of the encode operation.
__input_progress β [in] How much input was (potentially irreversibly) read from the input range before undergoing the attempted encode operation.
__output_progress β [in] How much output was (potentially irreversibly) written to the output range before undergoing the attempted encode operation.
-
template<typename _Encoding, typename _Input, typename _Output, typename _State, typename _InputProgress, typename _OutputProgress>
inline constexpr auto operator()(const _Encoding &__encoding, decode_result<_Input, _Output, _State> __result, const _InputProgress &__input_progress, const _OutputProgress &__output_progress) const noexcept(::ztd::text::is_nothrow_skip_input_error_v<const _Encoding&, decode_result<_Input, _Output, _State>, const _InputProgress&, const _OutputProgress&>)ο The function call for inserting replacement code points at the point of failure, before returning flow back to the caller of the decode operation.
- Parameters
__encoding β [in] The Encoding that experienced the error.
__result β [in] The current state of the encode operation.
__input_progress β [in] How much input was (potentially irreversibly) read from the input range before undergoing the attempted encode operation.
__output_progress β [in] How much output was (potentially irreversibly) written to the output range before undergoing the attempted encode operation.
-
template<typename _Encoding, typename _Input, typename _Output, typename _State, typename _InputProgress, typename _OutputProgress>