Registry-Based Conversions: Resource Handles

cnc_conversion is first and foremost a handle to a resource. It must be opened/created like one, and destroyed like one. The *_new flavor of functions perform the allocation automatically using the associated registry's heap. The *_open flavor fo functions let the user pass in an area of memory (or probe to find out the exact area of memory) to open the handle into. The *_open flavor of functions is for particularly advanced users who want maximum control over where the type is placed and allocated and is much more complicated to use: users are recommended to use cnc_conv_new() and cnc_conv_new_n() where appropriate to save on precision handling and hassle.

cnc_conversion Creation

typedef struct cnc_conversion cnc_conversion

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

cnc_open_err cnc_conv_open(cnc_conversion_registry *__registry, const ztd_char_t *__from, const ztd_char_t *__to, cnc_conversion **__out_p_conversion, size_t *__p_available_space, unsigned char *__space, cnc_conversion_info *__p_info)

Opens a new encoding in the provided space.

Remark

This call defers to calling cnc_conv_open_n after computing the length of the __from and __to parameters, if they are not nullptr. If either is nullptr, their size is assumed to be 0.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_available_space[inout] The amount of space available in the __space parameter, in the number of bytes, that can be used to allocate any necessary data for the cnc_conversion handle.

  • __space[inout] A pointer to space which can be used for opening up the conversion handle, which has the size indicated by __p_available_space.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_open_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 **__out_p_conversion, size_t *__p_available_space, void *__space, cnc_conversion_info *__p_info)

Opens a new encoding in the provided space an returns it through __out_p_conversion.

Remark

If there is a conversion that can be achieved by using an intermediate encoding (e.g., converting from the desired __from encoding to UTF-32, then from UTF-32 to the desired __to encoding), then an indirect transcode will be opened if a direct encoding cannot be opened. If there is not enough space to write out, then this function will provide the amount needed in __p_available_space directly. Otherwise, it will decrement the value pointed to be __p_available_space by the amount of space used.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from_size[in] The size of the __from string.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to_size[in] The size of the __to string.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_available_space[inout] The amount of space available in the __space parameter, in the number of bytes, that can be used to allocate any necessary data for the cnc_conversion handle.

  • __space[inout] A pointer to space which can be used for opening up the conversion handle, which has the size indicated by __p_available_space.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_open_select(cnc_conversion_registry *__registry, const ztd_char_t *__from, const ztd_char_t *__to, cnc_indirect_selection_function *__selection, cnc_conversion **__out_p_conversion, size_t *__p_available_space, void *__space, cnc_conversion_info *__p_info)

Opens a new encoding in the provided space an returns it through __out_p_conversion.

Remark

If there is a conversion that can be achieved by using an intermediate encoding (e.g., converting from the desired __from encoding to UTF-32, then from UTF-32 to the desired __to encoding), then an indirect transcode will be opened if a direct encoding cannot be opened. If there is not enough space to write out, then this function will provide the amount needed in __p_available_space directly. Otherwise, it will decrement the value pointed to be __p_available_space by the amount of space used.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __selection[in] A function pointer to an indirect selection function.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_available_space[inout] The amount of space available in the __space parameter, in the number of bytes, that can be used to allocate any necessary data for the cnc_conversion handle.

  • __space[inout] A pointer to space which can be used for opening up the conversion handle, which has the size indicated by __p_available_space.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_open_select_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_indirect_selection_function *__selection, cnc_conversion **__out_p_conversion, size_t *__p_available_space, void *__space, cnc_conversion_info *__p_info)

Opens a new encoding in the provided space an returns it through __out_p_conversion.

Remark

If there is a conversion that can be achieved by using an intermediate encoding (e.g., converting from the desired __from encoding to UTF-32, then from UTF-32 to the desired __to encoding), then an indirect transcode will be opened if a direct encoding cannot be opened. If there is not enough space to write out, then this function will provide the amount needed in __p_available_space directly. Otherwise, it will decrement the value pointed to be __p_available_space by the amount of space used.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from_size[in] The size of the __from string.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to_size[in] The size of the __to string.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __selection[in] A function pointer to an indirect selection function.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_available_space[inout] The amount of space available in the __space parameter, in the number of bytes, that can be used to allocate any necessary data for the cnc_conversion handle.

  • __space[inout] A pointer to space which can be used for opening up the conversion handle, which has the size indicated by __p_available_space.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_new(cnc_conversion_registry *__registry, const ztd_char_t *__from, const ztd_char_t *__to, cnc_conversion **__out_p_conversion, cnc_conversion_info *__p_info)

Creates a new encoding using the heap provided to the __registry.

Remark

This call defers to calling cnc_conv_new_n after computing the length of the __from and __to parameters, if they are not nullptr. If either is nullptr, their size is assumed to be 0.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_new_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 **__out_p_conversion, cnc_conversion_info *__p_info)

Creates a new encoding using the heap provided to the __registry.

Remark

This call defers to calling cnc_conv_open_n after computing the necessary size from cnc_conv_open_n.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from_size[in] The size of the __from string.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to_size[in] The size of the __to string.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_new_select(cnc_conversion_registry *__registry, const ztd_char_t *__from, const ztd_char_t *__to, cnc_indirect_selection_function *__selection, cnc_conversion **__out_p_conversion, cnc_conversion_info *__p_info)

Creates a new encoding using the heap provided to the __registry.

Remark

This call defers to calling cnc_conv_open_n after computing the necessary size from cnc_conv_open_n.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __selection[in] A function pointer to a indirect selection function.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_new_select_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_indirect_selection_function *__selection, cnc_conversion **__out_p_conversion, cnc_conversion_info *__p_info)

Creates a new encoding using the heap provided to the __registry.

Remark

This call defers to calling cnc_conv_open_n after computing the necessary size from cnc_conv_open_n.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from_size[in] The size of the __from string.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to_size[in] The size of the __to string.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __selection[in] A function pointer to a indirect selection function.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_open_c8(cnc_conversion_registry *__registry, const ztd_char8_t *__from, const ztd_char8_t *__to, cnc_conversion **__out_p_conversion, size_t *__p_available_space, unsigned char *__space, cnc_conversion_info *__p_info)

Opens a new encoding in the provided space.

Remark

This call defers to calling cnc_conv_open_n after computing the length of the __from and __to parameters, if they are not nullptr. If either is nullptr, their size is assumed to be 0.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_available_space[inout] The amount of space available in the __space parameter, in the number of bytes, that can be used to allocate any necessary data for the cnc_conversion handle.

  • __space[inout] A pointer to space which can be used for opening up the conversion handle, which has the size indicated by __p_available_space.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_open_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 **__out_p_conversion, size_t *__p_available_space, void *__space, cnc_conversion_info *__p_info)

Opens a new encoding in the provided space an returns it through __out_p_conversion.

Remark

If there is a conversion that can be achieved by using an intermediate encoding (e.g., converting from the desired __from encoding to UTF-32, then from UTF-32 to the desired __to encoding), then an indirect transcode will be opened if a direct encoding cannot be opened. If there is not enough space to write out, then this function will provide the amount needed in __p_available_space directly. Otherwise, it will decrement the value pointed to be __p_available_space by the amount of space used.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from_size[in] The size of the __from string.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to_size[in] The size of the __to string.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_available_space[inout] The amount of space available in the __space parameter, in the number of bytes, that can be used to allocate any necessary data for the cnc_conversion handle.

  • __space[inout] A pointer to space which can be used for opening up the conversion handle, which has the size indicated by __p_available_space.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_open_c8_select(cnc_conversion_registry *__registry, const ztd_char8_t *__from, const ztd_char8_t *__to, cnc_indirect_selection_c8_function *__selection, cnc_conversion **__out_p_conversion, size_t *__p_available_space, void *__space, cnc_conversion_info *__p_info)

Opens a new encoding in the provided space an returns it through __out_p_conversion.

Remark

If there is a conversion that can be achieved by using an intermediate encoding (e.g., converting from the desired __from encoding to UTF-32, then from UTF-32 to the desired __to encoding), then an indirect transcode will be opened if a direct encoding cannot be opened. If there is not enough space to write out, then this function will provide the amount needed in __p_available_space directly. Otherwise, it will decrement the value pointed to be __p_available_space by the amount of space used.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __selection[in] A function pointer to an indirect selection function.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_available_space[inout] The amount of space available in the __space parameter, in the number of bytes, that can be used to allocate any necessary data for the cnc_conversion handle.

  • __space[inout] A pointer to space which can be used for opening up the conversion handle, which has the size indicated by __p_available_space.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_open_select_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_indirect_selection_c8_function *__selection, cnc_conversion **__out_p_conversion, size_t *__p_available_space, void *__space, cnc_conversion_info *__p_info)

Opens a new encoding in the provided space an returns it through __out_p_conversion.

Remark

If there is a conversion that can be achieved by using an intermediate encoding (e.g., converting from the desired __from encoding to UTF-32, then from UTF-32 to the desired __to encoding), then an indirect transcode will be opened if a direct encoding cannot be opened. If there is not enough space to write out, then this function will provide the amount needed in __p_available_space directly. Otherwise, it will decrement the value pointed to be __p_available_space by the amount of space used.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from_size[in] The size of the __from string.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to_size[in] The size of the __to string.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __selection[in] A function pointer to an indirect selection function.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_available_space[inout] The amount of space available in the __space parameter, in the number of bytes, that can be used to allocate any necessary data for the cnc_conversion handle.

  • __space[inout] A pointer to space which can be used for opening up the conversion handle, which has the size indicated by __p_available_space.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_new_c8(cnc_conversion_registry *__registry, const ztd_char8_t *__from, const ztd_char8_t *__to, cnc_conversion **__out_p_conversion, cnc_conversion_info *__p_info)

Creates a new encoding using the heap provided to the __registry.

Remark

This call defers to calling cnc_conv_new_n after computing the length of the __from and __to parameters, if they are not nullptr. If either is nullptr, their size is assumed to be 0.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_new_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 **__out_p_conversion, cnc_conversion_info *__p_info)

Creates a new encoding using the heap provided to the __registry.

Remark

This call defers to calling cnc_conv_open_n after computing the necessary size from cnc_conv_open_n.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from_size[in] The size of the __from string.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to_size[in] The size of the __to string.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_new_c8_select(cnc_conversion_registry *__registry, const ztd_char8_t *__from, const ztd_char8_t *__to, cnc_indirect_selection_c8_function *__selection, cnc_conversion **__out_p_conversion, cnc_conversion_info *__p_info)

Creates a new encoding using the heap provided to the __registry.

Remark

This call defers to calling cnc_conv_open_n after computing the necessary size from cnc_conv_open_n.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __selection[in] A function pointer to a indirect selection function.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

cnc_open_err cnc_conv_new_select_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_indirect_selection_c8_function *__selection, cnc_conversion **__out_p_conversion, cnc_conversion_info *__p_info)

Creates a new encoding using the heap provided to the __registry.

Remark

This call defers to calling cnc_conv_open_n after computing the necessary size from cnc_conv_open_n.

Parameters
  • __registry[in] The registry to use for opening the cnc_conversion handle.

  • __from_size[in] The size of the __from string.

  • __from[in] A pointer to data encoded as UTF-8 representing the encoding to transcode from.

  • __to_size[in] The size of the __to string.

  • __to[in] A pointer to data encoded as UTF-8 representing the encoding to transcode to.

  • __selection[in] A function pointer to a indirect selection function.

  • __out_p_conversion[inout] A pointer to the cnc_conversion handle to open.

  • __p_info[inout] A pointer to an already-created cnc_conversion_info that will be filled out with information regarding how the transcoding operation was opened, if it was successful.

void cnc_conv_close(cnc_conversion *__conversion)

Closes (destroys) the data used by the cnc_conversion handle pointed to by __conversion.

Remark

This function, to use a C++ analogy, behaves much like a destructor. It does not free any memory: it simply destroys anything created or used by the cnc_open_function supplied when registrying the “from” and “to” conversion pair. If __conversion is nullptr, this function does nothing.

Parameters

__conversion[in] The cnc_conversion handle to destroy. Can be nullptr.

void cnc_conv_delete(cnc_conversion *__conversion)

Deletes and data used by the cnc_conversion handle pointed to by __conversion.

Remark

This function will call cnc_conv_close on the __conversion function, and then delete the memory. It must not be used if cnc_conv_new or cnc_conv_new_n was not used. If __conversion is nullptr, this function does nothing.

Parameters

__conversion[in] The cnc_conversion handle to destroy. Can be nullptr.