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 be static or constexpr) that returns a range of code units to insert directly into an output stream on a failed encode operation. It can also be called as a secondary backup if an decode operation fails, whereupon it will use the values in the range to attempt decodeing 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 be static or constexpr) that returns a range of code points to insert directly into an output stream on a failed decode operation. It can also be called as a secondary backup if an encode operation fails, whereupon it will use the values in the range to attempt encodeing 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 be static or constexpr) that returns a maybe-range. If the expression if (maybe_returned_range) evaluates to true, it will get the range returned by the function by performing a dereference of decltype(auto) returned_range = *maybe_returned_range;. If the conditional expression does not evaluate to true, 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 be static or constexpr) that returns a maybe-range. If the expression if (maybe_returned_range) evaluates to true, it will get the range returned by the function by performing a dereference of decltype(auto) returned_range = *maybe_returned_range;. If the conditional expression does not evaluate to true, 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() or replacement_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 a maybe_replacement_code_points() or a maybe_replacement_code_units() function. If either is present, they are expected to return a std::optional of a contiguous range. If it is engaged (the std::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 character U+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.