Multiple (Bulk) Conversion

Bulk conversions are a way to convert multiple complete indivisible units of work into multiple complete units of output (bytes/code units/code points written and/or state changes). Bulk conversions greedily consume input and only stop on either (a) input exhaustion AND state completion, or (b) error. Unlike single conversions, there is no theoretical or logical upper bound for the output buffer that can be given for an encoding transformation without knowing intimate details about the encoding and whether (valid) input is given to the transcoding operation given, especially if the input or output encoding is a variable-width (consumes or outputs 1 or more code units depending on what kind of input goes in). Therefore, it is much more probable and likely that an error will return cnc_mcerr_insufficient_output, which must be handled accordingly in order to fully process the given input.

Simulating Single Conversions with Bulk Conversions

A bulk conversion can be used to simulate a single conversion by arbitrarily limiting the size of an incoming input to 1 code unit, and seeing if it successfully transcodes. If it reports that the input is incomplete, keep incrementing the size of the incoming input 1 more code unit, until it either eventually reports success (cnc_mcerr_ok) or failure. If a known maximum upper limit is known for a given encoding, one can limit the incremental loop that increases the size of the input to that maximum limit.

Note that the above process can be incredibly slow since it requires walking over the same input over and over again until a non-cnc_mcerr_incomplete_sequence error code occurs. All of the named encoding functions that are not specialized for speed are instead implemented using the technique described in the indivisible unit of work documentation, and this technique is only employed for runtime-added, registry-based encodings that only provide bulk conversion through e.g. cnc_registry_add_multi().