State

Occasionally, state objects are passed to the routines that perform conversions. These can do things such as hold onto shift state, have special flags for special processing (e.g., for assuming input for a given function is valid). In general, the state parameter comes last and is a pointer to a state the user creates (or, if using the typed conversion functions, may be created for you and used.) The function therefore usually ends up of the form:

#include <uchar.h>

typedef struct my_state {
        bool assume_valid_input;
        char accumulation[2];
} my_state;

cnc_mcerr my_single_conversion_to_utf32(size_t* p_output_size,
        const char32_t** p_output,
        size_t* p_input_size,
        const char** p_input,
        my_state* p_state);

As described by the indivisible unit of work, reading input can change the state internally, even accumulate data in the state while outputting 0 characters. Because state may influence whether or not a conversion is complete (e.g., it has accumulated data inside of it and must empty it out), complex state objects should add a visible inspection function to check if the state is “complete” (has nothing left to output and is awaiting no further characters):

#include <uchar.h>

typedef struct my_conversion_state {
        char accumulation[2];
        unsigned char accumulation_count;
        bool assume_valid_input;
} my_conversion_state;

bool my_state_is_complete(const my_conversion_state* p_state);

cnc_mcerr my_single_conversion_to_utf32(size_t* p_output_size,
        const char32_t** p_output,
        size_t* p_input_size,
        const char** p_input,
        my_conversion_state* p_state);

The cnc_mcstate_t type has a similar function named cnc_mcstate_is_complete(), used for this purpose. As a completely made up example for a complete made up encoding,

#include <ztd/cuneicode.h>

#include <ztd/idk/size.h>
#include <ztd/idk/restrict.h>

#include <stdio.h>
#include <string.h>
#include <stddef.h>

cnc_mcerr my_bulk_mcsnrtoc8sn(size_t* output_size, unsigned char** output,
     size_t* input_size, const char** restrict input, cnc_mcstate_t* state) {
	cnc_mcstate_t invocation_unique_internal_state;
	if (state == NULL) {
		invocation_unique_internal_state = (cnc_mcstate_t) { 0 };
		state                            = &invocation_unique_internal_state;
	}
	if (input == NULL || *input == NULL) {
		return cnc_mcnrtoc8n(output_size, output, input_size, input, state);
	}
	for (;;) {
		cnc_mcerr err
		     = cnc_mcnrtoc8n(output_size, output, input_size, input, state);
		if (err != cnc_mcerr_ok) {
			return err;
		}
		if (*input_size > 0) {
			continue;
		}
		bool state_finished = cnc_mcstate_is_complete(state);
		if (!state_finished) {
			continue;
		}
		return err;
	}
}

int main() {
	const char input[]              = "abc";
	const char* input_ptr           = input;
	const size_t initial_input_size = ztdc_c_array_size(input);
	size_t input_size               = initial_input_size;

	unsigned char output[CNC_C8_MAX * ztdc_c_array_size(input)] = { 0 };
	unsigned char* output_ptr                                  = output;
	const size_t initial_output_size = ztdc_c_array_size(output);
	size_t output_size               = initial_output_size;

	cnc_mcerr err = my_bulk_mcsnrtoc8sn(
	     &output_size, &output_ptr, &input_size, &input_ptr, NULL);
	const size_t output_written = initial_output_size - output_size;
	const size_t input_read     = initial_input_size - input_size;
	if (err != cnc_mcerr_ok) {
		fprintf(stderr, "The conversion failed with an unexpected error of %s.",
		     cnc_mcerr_to_str(err));
		return 1;
	}

	const unsigned char expected_output[] = "abc";

	if (memcmp(output, expected_output, output_written) != 0) {
		fprintf(stderr,
		     "The expected intput was not the same as the expected output.");
		return 2;
	}

	fprintf(stdout, "Read: %zu units\nWrote: %zu units\nWritten value: %s\n",
	     input_read, output_written, (const char*)output);

	return 0;
}