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, the nullptr 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 not nullptr).

  • __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 to 0, 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, the nullptr 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 not nullptr).

  • __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 to 0, 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.