Design Goals and Philosophy
The goal of this library are to:
enable people to write new code that can properly handle encoded information, specifically text;
give them effective means to convert that information in various ways for their own encodings;
do so without using hidden allocations or other conversions that are not controllable;
and, allow them to not need to provide pairwise conversions for every encoding pair they care about.
To this end, there are 2 sets of functionality: typed and static conversions which utilize proper input and output buffer types, and untyped conversions which go through a level of indirection and explicitly work on byte-based (unsigned char) buffers. Each of the 2 sets of functionality are further subdivided into 2 use cases that users are about:
Singular Conversions: where a user wants to encode, decode, or transcode one complete unit of information at a time and receive an error when that conversion fails.
Multiple (bulk) Conversions: where a user wants to encode, decode, or transcode the maximum amount of information possible in a single given call, for speed or throughput reasons.
Finally, to make sure this library is capable of scaling and does not have users hobbling together pairwise function calls for each encoding pair they care about, we provide automatic translation through an indirect layer that leverages one of the popular omni-encodings (e.g. Unicode) so that users do not have to provide conversion routines to every possible other encoding: just the ones they care about.