Singular Conversion

Singular conversions are foundational because they are guaranteed to only encode a single complete unit of information and output a single complete unit of information (or change the operating state in some manner), per doing one indivisible unit of work.

Singular conversions also have a maximally-bounded input size that is guaranteed to either change the state or compute one complete unit of output (which may result in multiple bytes/code units/code points being written out). This means that one can, for each individual operation, provide enough space to guarantee that doing an output operation will never be more than a statically-known, maximally-sized buffer (and thus avoid ever having to handle the cnc_mcerr_insufficient_output return code). This is necessary for low-memory environments which may need to process input with the smallest possible memory guarantee available. As an example, given the general form of a function (whose parameters and style is discussed in the functions section), one can put together a concrete general-purpose

Looping over a set of input using a singular conversion is a valid way to transform a singular conversion into a bulk conversion. This technique is handy for guaranteeing correctness from composing a bulk operation from a correctly-implemented single conversion, but hinders throughput and speed due to needing to check for safety and constantly recalculate and update sizes. This does not necessarily mean that singular conversion must always be done: there are techniques that can convert multiple indivisible units of input at a time through much more efficient means.

The benefit of a Single Conversion API that only performs one indivisible unit of work is the ability to build every single other piece of the API through this very functionality.

conversion algorithms to become single conversion algorithms, though the performance of such an algorithm is noticeably worse.