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 namecnc_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 notnullptr
. If either isnullptr
, 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 notnullptr
. If either isnullptr
, 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 notnullptr
. If either isnullptr
, 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 notnullptr
. If either isnullptr
, 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
isnullptr
, 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
isnullptr
, this function does nothing.- Parameters
__conversion – [in] The cnc_conversion handle to destroy. Can be
nullptr
.