Generic Typed Conversionsο
Generic typed conversions rely on the types being put in to determine what encodings and conversions should be done. They are more flexibile when the input is generic, or the user has well-defined source and destination pointers to use with the API. The type-to-prefix/encoding mapping for this function is described in the naming documentation. When using these functions, using nullptr
is ambiguous because the macro/template cannot understand what the to / from pointers should be. In those cases, cast the nullptr
value with (CharTypeHere**)nullptr
.
Bulk Conversion Functionsο
-
cnc_cxsntocysn(__p_maybe_dst_len, __p_maybe_dst, __p_src_len, __p_src)ο
Converts from the encoding given by
__p_src
βs character type to__p_maybe_dst
βs character type in bulk. Identical in behavior to cnc_cxsnrtocysn, with the__p_state
argument passed in from a properly initialized cnc_mcstate_t object of automatic storage duration (it is a βstackβ-based variable that does not live beyond the call of this function).
-
cnc_cxsnrtocysn(__p_maybe_dst_len, __p_maybe_dst, __p_src_len, __p_src, __p_state)ο
Converts from the encoding given by
__p_src
βs character type to__p_maybe_dst
βs character type one at a time.Remark
Note that it is impossible for this type to handle
nullptr
properly for its destination and source arguments because of its templated nature, since that is how it derives the type. Therefore, thenullptr
passed in must first be coerced to a type with a cast, for example:cnc_mcerr err = cnc_cxsntocysn(&required_len, (ztd_char_t**)nullptr, &src_len, &src_ptr, &state);
- Parameters
__p_maybe_dst_len β [inout] A poinvter to the size of the output buffer. If this is
nullptr
, then it will not update the count (and the output stream will automatically be considered large enough to handle all data, if__p_maybe_dst
is notnullptr
).__p_maybe_dst β [inout] A pointer to the pointer of the output buffer. If this or the pointer within are
nullptr
, than this function will not write output data (it may still decrement the value pointed to by__p_maybe_dst_len
).__p_src_len β [inout] A pointer to the size of the input buffer (in number of elements). If this is
nullptr
or points to a value equivalent to0
, then the input is considered empty and cnc_mcerr_ok is returned.__p_src β [inout] A pointer to the pointer of the input buffer. If this or the pointer within are
nullptr
, than the input is considered empty and cnc_mcerr_ok is returned.__p_state β [inout] A pointer to the conversion state. If this is
nullptr
, a value-initialized (= {0}
or similar) cnc_mcstate_t is used.
Single Conversion Functionsο
-
cnc_cxntocyn(__p_maybe_dst_len, __p_maybe_dst, __p_src_len, __p_src)ο
Converts from the encoding given by
__p_src
βs character type to__p_maybe_dst
βs character type, one at a time. Identical in behavior to cnc_cxnrtocyn, with the__p_state
argument passed in from a properly initialized cnc_mcstate_t object of automatic storage duration (it is a βstackβ-based variable that does not live beyond the call of this function).
-
cnc_cxnrtocyn(__p_maybe_dst_len, __p_maybe_dst, __p_src_len, __p_src, __p_state)ο
Converts from the encoding given by
__p_src
βs character type to__p_maybe_dst
βs character type.Remark
Note that it is impossible for this type to handle
nullptr
properly for its destination and source arguments because of its templated nature, since that is how it derives the type. Therefore, thenullptr
passed in must first be coerced to a type with a cast, for example:cnc_mcerr err = cnc_cxsntocysn(&required_len, (ztd_char_t**)nullptr, &src_len, &src_ptr, &state);
- Parameters
__p_maybe_dst_len β [inout] A pointer to the size of the output buffer (in number of elements). If this is
nullptr
, then it will not update the count (and the output stream will automatically be considered large enough to handle all data, if__p_maybe_dst
is notnullptr
).__p_maybe_dst β [inout] A pointer to the pointer of the output buffer. If this or the pointer within are
nullptr
, than this function will not write output data (it may still decrement the value pointed to by__p_maybe_dst_len
).__p_src_len β [inout] A pointer to the size of the input buffer (in number of elements). If this is
nullptr
or points to a value equivalent to0
, then the input is considered empty and cnc_mcerr_ok is returned.__p_src β [inout] A pointer to the pointer of the input buffer. If this or the pointer within are
nullptr
, than the input is considered empty and cnc_mcerr_ok is returned.__p_state β [inout] A pointer to the conversion state. If this is
nullptr
, a value-initialized (= {0}
or similar) cnc_mcstate_t is used.