Conversion Registry

typedef struct cnc_conversion_registry cnc_conversion_registry

A typedef to allow for plain and normal usage of the type name cnc_conversion_registry.

cnc_open_err cnc_registry_new(cnc_conversion_registry **__out_p_registry, cnc_registry_options __registry_options)

Creates a new registry.

Remark

This will default to using a normal cnc_conversion_heap which uses the globally-available allocator (malloc, free, realloc, etc.).

Parameters

  • __out_p_registry – [inout] The output pointer to the handle of the cnc_conversion_registry that will be created.

  • __registry_options – [in] The options that affect how this registry is created.

cnc_open_err cnc_registry_open(cnc_conversion_registry **__out_p_registry, cnc_conversion_heap *__p_heap, cnc_registry_options __registry_options)

Creates a new registry.

Remark

All allocations shall be done through the passed-in heap if needed. It is unspecified if the implementation can or will use the heap at all (e.g., there is a small buffer optimization applied).

Parameters

  • __out_p_registry – [inout] The output pointer to the handle of the cnc_conversion_registry that will be created.

  • __p_heap – [in] A pointer to the heap to use. The heap this points to will be copied into the registry upon successful creation.

  • __registry_options – [in] The options that affect how this registry is created.

cnc_open_err cnc_registry_add(cnc_conversion_registry *__registry, const ztd_char_t *__from, const ztd_char_t *__to, cnc_conversion_function *__multi_conversion_function, cnc_conversion_function *__single_conversion_function, cnc_state_is_complete_function *__state_is_complete_function, cnc_open_function *__open_function, cnc_close_function *__close_function)

Adds a new conversion from the specified __from and __to names to the specified registry.

Remark

This function has identical behavior to cnc_registry_add_n, where the __from_size and __to_size arguments are calculated by calling the equivalent of strlen on __from and __to, respectively. If __from or __to are nullptr, then the function will assume they are the empty string (and use the default name in that case).

Parameters

  • __registry – [in] The registry to create the new conversion pair in.

  • __from – [in] A pointer to a null-terminated c string encoded in UTF-8 representing the name of the encoding to convert from. Can be nullptr.

  • __to – [in] A pointer to a null-terminated c string encoded in UTF-8 representing the name of the encoding to convert to. Can be nullptr.

  • __multi_conversion_function – [in] The conversion cnc_conversion_function which will perform a bulk conversion (consumes as much input as is available until exhausted or an error occurs). Can be nullptr, but only if the __single_conversion_function is not nullptr as well.

  • __single_conversion_function – [in] The conversion cnc_conversion_function which will perform a singular conversion (consumes only one completely unit of input and produces on complete unit of output). Can be nullptr, but only if the __multi_conversion_function is not nullptr as well.

  • __state_is_complete_function – [in] A function to use to check if, when the input is empty, if there is still leftover data to be output from the state.

  • __open_function – [in] The cnc_open_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

  • __close_function – [in] The cnc_close_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

cnc_open_err cnc_registry_add_n(cnc_conversion_registry *__registry, size_t __from_size, const ztd_char_t __from[ZTD_PTR_EXTENT(__from_size)], size_t __to_size, const ztd_char_t __to[ZTD_PTR_EXTENT(__to_size)], cnc_conversion_function *__multi_conversion_function, cnc_conversion_function *__single_conversion_function, cnc_state_is_complete_function *__state_is_complete_function, cnc_open_function *__open_function, cnc_close_function *__close_function)

Adds a new conversion from the specified __from and __to names to the specified registry.

Remark

This function has identical behavior to cnc_registry_add_n, where the __from_size and __to_size arguments are calculated by calling the equivalent of strlen on __from and __to, respectively. If __from or __to are nullptr, then the function will assume they are the empty string (and use the default name in that case).

Parameters

  • __registry – [in] The registry to create the new conversion pair in.

  • __from_size – [in] The number of code units in the __from parameter.

  • __from – [in] A pointer to a string encoded in UTF-8 representing the name of the encoding to convert from. The string need not be null-terminated. Can be nullptr.

  • __to_size – [in] The number of code units in the __to parameter.

  • __to – [in] A pointer to a string encoded in UTF-8 representing the name of the encoding to convert to. The string need not be null-terminated. Can be nullptr.

  • __multi_conversion_function – [in] The conversion cnc_conversion_function which will perform a bulk conversion (consumes as much input as is available until exhausted or an error occurs). Can be nullptr, but only if the __single_conversion_function is not nullptr as well.

  • __single_conversion_function – [in] The conversion cnc_conversion_function which will perform a singular conversion (consumes only one completely unit of input and produces on complete unit of output). Can be nullptr, but only if the __multi_conversion_function is not nullptr as well.

  • __state_is_complete_function – [in] A function to use to check if, when the input is empty, if there is still leftover data to be output from the state.

  • __open_function – [in] The cnc_open_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

  • __close_function – [in] The cnc_close_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

cnc_open_err cnc_registry_add_multi(cnc_conversion_registry *__registry, const ztd_char_t *__from, const ztd_char_t *__to, cnc_conversion_function *__multi_conversion_function, cnc_state_is_complete_function *__state_is_complete_function, cnc_open_function *__open_function, cnc_close_function *__close_function)

Adds a new conversion from the specified __from and __to names to the specified registry.

Remark

Identical to calling cnc_registry_add_n, with the __multi_conversion_function parameter set to nullptr. The __from_size and __to_size arguments are calculated by calling the equivalent of strlen on __from and __to, respectively. If __from or __to are nullptr, then the function will assume they are the empty string (and use the default name in that case).

Parameters

  • __registry – [in] The registry to create the new conversion pair in.

  • __from – [in] A pointer to a null-terminated c string encoded in UTF-8 representing the encoding to convert from. Can be nullptr.

  • __to – [in] A pointer to a null-terminated c string encoded in UTF-8 representing the encoding to convert to. Can be nullptr.

  • __multi_conversion_function – [in] The conversion cnc_conversion_function which will perform a bulk conversion (consumes as much input as is available until exhausted or an error occurs). Can be nullptr, but only if the __single_conversion_function is not nullptr as well.

  • __state_is_complete_function – [in] A function to use to check if, when the input is empty, if there is still leftover data to be output from the state.

  • __open_function – [in] The cnc_open_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

  • __close_function – [in] The cnc_close_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

cnc_open_err cnc_registry_add_multi_n(cnc_conversion_registry *__registry, size_t __from_size, const ztd_char_t __from[ZTD_PTR_EXTENT(__from_size)], size_t __to_size, const ztd_char_t __to[ZTD_PTR_EXTENT(__to_size)], cnc_conversion_function *__multi_conversion_function, cnc_state_is_complete_function *__state_is_complete_function, cnc_open_function *__open_function, cnc_close_function *__close_function)

Adds a new conversion from the specified __from and __to names to the specified registry.

Remark

Identical to calling cnc_registry_add_n, with the __single_conversion_function parameter set to nullptr.

Parameters

  • __registry – [in] The registry to create the new conversion pair in.

  • __from_size – [in] The number of code units in the __from parameter.

  • __from – [in] A pointer to a string encoded in UTF-8 representing the encoding to convert from. The string need not be null-terminated. Can be nullptr.

  • __to_size – [in] The number of code units in the __to parameter.

  • __to – [in] A pointer to a string encoded in UTF-8 representing the encoding to convert to. The string need not be null-terminated. Can be nullptr.

  • __multi_conversion_function – [in] The conversion cnc_conversion_function which will perform a bulk conversion (consumes as much input as is available until exhausted or an error occurs). Can be nullptr, but only if the __single_conversion_function is not nullptr as well.

  • __state_is_complete_function – [in] A function to use to check if, when the input is empty, if there is still leftover data to be output from the state.

  • __open_function – [in] The cnc_open_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

  • __close_function – [in] The cnc_close_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

cnc_open_err cnc_registry_add_single(cnc_conversion_registry *__registry, const ztd_char_t *__from, const ztd_char_t *__to, cnc_conversion_function *__single_conversion_function, cnc_state_is_complete_function *__state_is_complete_function, cnc_open_function *__open_function, cnc_close_function *__close_function)

Adds a new conversion from the specified __from and __to names to the specified registry.

Remark

Identical to calling cnc_registry_add_n, with the __multi_conversion_function parameter set to nullptr. The __from_size and __to_size arguments are calculated by calling the equivalent of strlen on __from and __to, respectively. If __from or __to are nullptr, then the function will assume they are the empty string (and use the default name in that case).

Parameters

  • __registry – [in] The registry to create the new conversion pair in.

  • __from – [in] A pointer to a null-terminated c string encoded in UTF-8 representing the encoding to convert from. Can be nullptr.

  • __to – [in] A pointer to a null-terminated c string encoded in UTF-8 representing the encoding to convert to. Can be nullptr.

  • __single_conversion_function – [in] The conversion cnc_conversion_function which will perform a singular conversion (consumes only one completely unit of input and produces on complete unit of output). Shall not be nullptr.

  • __state_is_complete_function – [in] A function to use to check if, when the input is empty, if there is still leftover data to be output from the state.

  • __open_function – [in] The cnc_open_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

  • __close_function – [in] The cnc_close_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

cnc_open_err cnc_registry_add_single_n(cnc_conversion_registry *__registry, size_t __from_size, const ztd_char_t __from[ZTD_PTR_EXTENT(__from_size)], size_t __to_size, const ztd_char_t __to[ZTD_PTR_EXTENT(__to_size)], cnc_conversion_function *__single_conversion_function, cnc_state_is_complete_function *__state_is_complete_function, cnc_open_function *__open_function, cnc_close_function *__close_function)

Adds a new conversion from the specified __from and __to names to the specified registry.

Remark

Identical to calling cnc_registry_add_n, with the __multi_conversion_function parameter set to nullptr.

Parameters

  • __registry – [in] The registry to create the new conversion pair in.

  • __from_size – [in] The number of code units in the __from parameter.

  • __from – [in] A pointer to a string encoded in UTF-8 representing the encoding to convert from. The string need not be null-terminated. Can be nullptr.

  • __to_size – [in] The number of code units in the __to parameter.

  • __to – [in] A pointer to a string encoded in UTF-8 representing the encoding to convert to. The string need not be null-terminated. Can be nullptr.

  • __single_conversion_function – [in] The conversion cnc_conversion_function which will perform a singular conversion (consumes only one completely unit of input and produces on complete unit of output). Shall not be nullptr.

  • __state_is_complete_function – [in] A function to use to check if, when the input is empty, if there is still leftover data to be output from the state.

  • __open_function – [in] The cnc_open_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

  • __close_function – [in] The cnc_close_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

cnc_open_err cnc_registry_add_c8(cnc_conversion_registry *__registry, const ztd_char8_t *__from, const ztd_char8_t *__to, cnc_conversion_function *__multi_conversion_function, cnc_conversion_function *__single_conversion_function, cnc_state_is_complete_function *__state_is_complete_function, cnc_open_function *__open_function, cnc_close_function *__close_function)

Adds a new conversion from the specified __from and __to names to the specified registry.

Remark

This function has identical behavior to cnc_registry_add_n, where the __from_size and __to_size arguments are calculated by calling the equivalent of strlen on __from and __to, respectively. If __from or __to are nullptr, then the function will assume they are the empty string (and use the default name in that case).

Parameters

  • __registry – [in] The registry to create the new conversion pair in.

  • __from – [in] A pointer to a null-terminated c string encoded in UTF-8 representing the name of the encoding to convert from. Can be nullptr.

  • __to – [in] A pointer to a null-terminated c string encoded in UTF-8 representing the name of the encoding to convert to. Can be nullptr.

  • __multi_conversion_function – [in] The conversion cnc_conversion_function which will perform a bulk conversion (consumes as much input as is available until exhausted or an error occurs). Can be nullptr, but only if the __single_conversion_function is not nullptr as well.

  • __single_conversion_function – [in] The conversion cnc_conversion_function which will perform a singular conversion (consumes only one completely unit of input and produces on complete unit of output). Can be nullptr, but only if the __multi_conversion_function is not nullptr as well.

  • __state_is_complete_function – [in] A function to use to check if, when the input is empty, if there is still leftover data to be output from the state.

  • __open_function – [in] The cnc_open_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

  • __close_function – [in] The cnc_close_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

cnc_open_err cnc_registry_add_c8n(cnc_conversion_registry *__registry, size_t __from_size, const ztd_char8_t __from[ZTD_PTR_EXTENT(__from_size)], size_t __to_size, const ztd_char8_t __to[ZTD_PTR_EXTENT(__to_size)], cnc_conversion_function *__multi_conversion_function, cnc_conversion_function *__single_conversion_function, cnc_state_is_complete_function *__state_is_complete_function, cnc_open_function *__open_function, cnc_close_function *__close_function)

Adds a new conversion from the specified __from and __to names to the specified registry.

Remark

This function has identical behavior to cnc_registry_add_n, where the __from_size and __to_size arguments are calculated by calling the equivalent of strlen on __from and __to, respectively. If __from or __to are nullptr, then the function will assume they are the empty string (and use the default name in that case).

Parameters

  • __registry – [in] The registry to create the new conversion pair in.

  • __from_size – [in] The number of code units in the __from parameter.

  • __from – [in] A pointer to a string encoded in UTF-8 representing the name of the encoding to convert from. The string need not be null-terminated. Can be nullptr.

  • __to_size – [in] The number of code units in the __to parameter.

  • __to – [in] A pointer to a string encoded in UTF-8 representing the name of the encoding to convert to. The string need not be null-terminated. Can be nullptr.

  • __multi_conversion_function – [in] The conversion cnc_conversion_function which will perform a bulk conversion (consumes as much input as is available until exhausted or an error occurs). Can be nullptr, but only if the __single_conversion_function is not nullptr as well.

  • __single_conversion_function – [in] The conversion cnc_conversion_function which will perform a singular conversion (consumes only one completely unit of input and produces on complete unit of output). Can be nullptr, but only if the __multi_conversion_function is not nullptr as well.

  • __state_is_complete_function – [in] A function to use to check if, when the input is empty, if there is still leftover data to be output from the state.

  • __open_function – [in] The cnc_open_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

  • __close_function – [in] The cnc_close_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

cnc_open_err cnc_registry_add_multi_c8(cnc_conversion_registry *__registry, const ztd_char8_t *__from, const ztd_char8_t *__to, cnc_conversion_function *__multi_conversion_function, cnc_state_is_complete_function *__state_is_complete_function, cnc_open_function *__open_function, cnc_close_function *__close_function)

Adds a new conversion from the specified __from and __to names to the specified registry.

Remark

Identical to calling cnc_registry_add_n, with the __multi_conversion_function parameter set to nullptr. The __from_size and __to_size arguments are calculated by calling the equivalent of strlen on __from and __to, respectively. If __from or __to are nullptr, then the function will assume they are the empty string (and use the default name in that case).

Parameters

  • __registry – [in] The registry to create the new conversion pair in.

  • __from – [in] A pointer to a null-terminated c string encoded in UTF-8 representing the encoding to convert from. Can be nullptr.

  • __to – [in] A pointer to a null-terminated c string encoded in UTF-8 representing the encoding to convert to. Can be nullptr.

  • __multi_conversion_function – [in] The conversion cnc_conversion_function which will perform a bulk conversion (consumes as much input as is available until exhausted or an error occurs). Can be nullptr, but only if the __single_conversion_function is not nullptr as well.

  • __state_is_complete_function – [in] A function to use to check if, when the input is empty, if there is still leftover data to be output from the state.

  • __open_function – [in] The cnc_open_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

  • __close_function – [in] The cnc_close_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

cnc_open_err cnc_registry_add_multi_c8n(cnc_conversion_registry *__registry, size_t __from_size, const ztd_char8_t __from[ZTD_PTR_EXTENT(__from_size)], size_t __to_size, const ztd_char8_t __to[ZTD_PTR_EXTENT(__to_size)], cnc_conversion_function *__multi_conversion_function, cnc_state_is_complete_function *__state_is_complete_function, cnc_open_function *__open_function, cnc_close_function *__close_function)

Adds a new conversion from the specified __from and __to names to the specified registry.

Remark

Identical to calling cnc_registry_add_n, with the __single_conversion_function parameter set to nullptr.

Parameters

  • __registry – [in] The registry to create the new conversion pair in.

  • __from_size – [in] The number of code units in the __from parameter.

  • __from – [in] A pointer to a string encoded in UTF-8 representing the encoding to convert from. The string need not be null-terminated. Can be nullptr.

  • __to_size – [in] The number of code units in the __to parameter.

  • __to – [in] A pointer to a string encoded in UTF-8 representing the encoding to convert to. The string need not be null-terminated. Can be nullptr.

  • __multi_conversion_function – [in] The conversion cnc_conversion_function which will perform a bulk conversion (consumes as much input as is available until exhausted or an error occurs). Can be nullptr, but only if the __single_conversion_function is not nullptr as well.

  • __state_is_complete_function – [in] A function to use to check if, when the input is empty, if there is still leftover data to be output from the state.

  • __open_function – [in] The cnc_open_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

  • __close_function – [in] The cnc_close_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

cnc_open_err cnc_registry_add_single_c8(cnc_conversion_registry *__registry, const ztd_char8_t *__from, const ztd_char8_t *__to, cnc_conversion_function *__single_conversion_function, cnc_state_is_complete_function *__state_is_complete_function, cnc_open_function *__open_function, cnc_close_function *__close_function)

Adds a new conversion from the specified __from and __to names to the specified registry.

Remark

Identical to calling cnc_registry_add_n, with the __multi_conversion_function parameter set to nullptr. The __from_size and __to_size arguments are calculated by calling the equivalent of strlen on __from and __to, respectively. If __from or __to are nullptr, then the function will assume they are the empty string (and use the default name in that case).

Parameters

  • __registry – [in] The registry to create the new conversion pair in.

  • __from – [in] A pointer to a null-terminated c string encoded in UTF-8 representing the encoding to convert from. Can be nullptr.

  • __to – [in] A pointer to a null-terminated c string encoded in UTF-8 representing the encoding to convert to. Can be nullptr.

  • __single_conversion_function – [in] The conversion cnc_conversion_function which will perform a singular conversion (consumes only one completely unit of input and produces on complete unit of output). Shall not be nullptr.

  • __state_is_complete_function – [in] A function to use to check if, when the input is empty, if there is still leftover data to be output from the state.

  • __open_function – [in] The cnc_open_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

  • __close_function – [in] The cnc_close_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

cnc_open_err cnc_registry_add_single_c8n(cnc_conversion_registry *__registry, size_t __from_size, const ztd_char8_t __from[ZTD_PTR_EXTENT(__from_size)], size_t __to_size, const ztd_char8_t __to[ZTD_PTR_EXTENT(__to_size)], cnc_conversion_function *__single_conversion_function, cnc_state_is_complete_function *__state_is_complete_function, cnc_open_function *__open_function, cnc_close_function *__close_function)

Adds a new conversion from the specified __from and __to names to the specified registry.

Remark

Identical to calling cnc_registry_add_n, with the __multi_conversion_function parameter set to nullptr.

Parameters

  • __registry – [in] The registry to create the new conversion pair in.

  • __from_size – [in] The number of code units in the __from parameter.

  • __from – [in] A pointer to a string encoded in UTF-8 representing the encoding to convert from. The string need not be null-terminated. Can be nullptr.

  • __to_size – [in] The number of code units in the __to parameter.

  • __to – [in] A pointer to a string encoded in UTF-8 representing the encoding to convert to. The string need not be null-terminated. Can be nullptr.

  • __single_conversion_function – [in] The conversion cnc_conversion_function which will perform a singular conversion (consumes only one completely unit of input and produces on complete unit of output). Shall not be nullptr.

  • __state_is_complete_function – [in] A function to use to check if, when the input is empty, if there is still leftover data to be output from the state.

  • __open_function – [in] The cnc_open_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

  • __close_function – [in] The cnc_close_function to be used for allocating additional space during function calls which open new cnc_conversion handles. Can be nullptr.

void cnc_registry_close(cnc_conversion_registry *__registry)

Closes an open registry.

Remark

This function MUST be paired with cnc_registry_open. It cannot be paired with any other creation function. This will close the registry before it’s memory is deleted/freed: see cnc_registry_close for more information. If registry is nullptr, this function will do nothing.

Parameters

__registry – [in] The registry to delete.

void cnc_registry_delete(cnc_conversion_registry *__registry)

Deletes a registry.

Remark

This function MUST be paired with cnc_registry_new. It cannot be paired with any other creation function. This will close the registry before it’s memory is deleted/freed: see cnc_registry_close for more information. If registry is nullptr, this function will do nothing.

Parameters

__registry – [in] The registry to delete.

const cnc_conversion_heap *cnc_registry_heap(const cnc_conversion_registry *__registry)

Retrieves the heap associated with this registry that is used to perform any and all allocations.

Parameters

__registry – [in] The conversion registry to retrieve the heap of.

void cnc_registry_pairs_list_c8n(const cnc_conversion_registry *__registry, cnc_conversion_registry_pair_c8_function *__callback_function, void *__user_data)

Provides the list of encoding conversions currently registered to the provided __registry.

Remark

This functions does not modify the contents of the registry and therefore can be called from any number of threads simultaneously. The callback function is invoked once more each pair. Note that each conversion pair is distinct from the others: a conversion pair of (“UTF-8”, “SHIFT-JIS”) is distinct from (“SHIFT-JIS”, “UTF-8”). If registry or __callback_function is nullptr, this function will do nothing.

Parameters

  • __registry – [in] The conversion registry whose conversion pairs should be iterated through and passed to the function.

  • __callback_function – [in] The function that should be called with each conversion pair. See cnc_conversion_registry_pair_function for more details about the expectation of each given parameter.

  • __user_data – [in] A pointer to data that should be given to the __callback_function.

void cnc_registry_pairs_list_n(const cnc_conversion_registry *__registry, cnc_conversion_registry_pair_function *__callback_function, void *__user_data)

Provides the list of encoding conversions currently registered to the provided __registry.

Remark

This functions does not modify the contents of the registry and therefore can be called from any number of threads simultaneously. The callback function is invoked once more each pair. Note that each conversion pair is distinct from the others: a conversion pair of (“UTF-8”, “SHIFT-JIS”) is distinct from (“SHIFT-JIS”, “UTF-8”). If registry or __callback_function is nullptr, this function will do nothing.

Parameters

  • __registry – [in] The conversion registry whose conversion pairs should be iterated through and passed to the function.

  • __callback_function – [in] The function that should be called with each conversion pair. See cnc_conversion_registry_pair_function for more details about the expectation of each given parameter.

  • __user_data – [in] A pointer to data that should be given to the __callback_function.