ztd::text::count_as_encoded is a function that takes an input sequence of
code_points 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 - 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:
text_count_as_encoded(input, encoding, handler, state)extension point, if possible.
An internal, implementation-defined customization point.
The base function call,
basic_count_as_encoded, simply performs the core counting loop using the Lucky 7 design.
basic_count_as_encoded loop, if it detects that there is a preferable
text_count_as_encoded_one, it will call that method as
text_count_as_encoded_one(input, encoding, handler, state) inside of the loop rather than doing the core design.
👉 This means that if you implement none of the extension points whatsoever, implementing the basic
encode_one function on your Encoding Object type will guarantee a proper, working implementation.
👉 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_encoded 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.