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 fill first 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.
-
constexpr replacement_handler_t ztd::text::replacement_handler = {}¶
A convenience variable for passing the replacement_handler_t handler to functions.
-
class ztd::text::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 _InputRange, typename _OutputRange, typename _State, typename _InputProgress, typename _OutputProgress>
inline constexpr auto operator()(const _Encoding &__encoding, encode_result<_InputRange, _OutputRange, _State> __result, const _InputProgress&, const _OutputProgress&) const noexcept¶ 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.
-
template<typename _Encoding, typename _InputRange, typename _OutputRange, typename _State, typename _InputProgress, typename _OutputProgress>
inline constexpr auto operator()(const _Encoding &__encoding, decode_result<_InputRange, _OutputRange, _State> __result, const _InputProgress&, const _OutputProgress&) const noexcept¶ 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.