Count as Encoded
Counting encodable data is the action of finding out how many code units will result from a given sequence of already decoded information, AKA a sequence of code points. Essentially, we run the encoding algorithm loop, but instead of giving the end user the encoded values, we instead simply provide the count for running that bulk operation.
Thusly, we use the algorithm as below to do the work. Given an input
of code_unit
s with an encoding
, an initial count
set at 0, and any necessary additional state
, we can generically predict how many code units will result from a decoding operation by running the following loop:
⏩ Is the
input
value empty? If so, is thestate
finished and have nothing to output? If both are true, return the current results with the the emptyinput
, curentcount
, andstate
, everything is okay ✅!⏩ Otherwise,
Set up an
intermediate
storage location ofcode_unit
s, using themax_code_units
of the input encoding, for the next operations.Do the
encode_one
step frominput
(using itsbegin()
andend()
) into theintermediate
code_unit
storage location, saving the returnedintermediate_output
from theencode_one
call.🛑 If it failed, return with the current
input
(unmodified from before this iteration, if possible), currentcount
, andstate
s.
Compute the difference between the
begin(intermediate)
from the original step, and thebegin(intermediate_output)
returned byencode_one
; add that difference to the currentcount
.
⏩ Update
input
‘sbegin()
value to point to after what was read by theencode_one
step.⤴️ Go back to the start.
This involves a single encoding type, and so does not need any cooperation to count the code_point
s. Note that this algorithm doesn’t show what the error handler does; if the error handler “erases” the failure by setting the result type’s .error_code == ztd::text::encoding_error::ok
, then the algorithm will keep going. This is useful to, for example, detect the maximum size of an operation even if it errors and would result in replacement characters being inserted (e.g., from ztd::text::replacement_handler_t).
Check out the API documentation for ztd::text::count_as_encoded to learn more.