PxTranslateStateToUTF()

Translate characters to UTF-8, using an internal state buffer

Synopsis:

#include <photon/PxProto.h>

int PxTranslateStateToUTF( struct PxTransCtrl *ctrl, 
                           const char *src, 
                           int maxsrc, 
                           int *consumed, 
                           char *dst, 
                           int maxdst );

Description:

This function is similar to PxTranslateToUTF() except that it uses an internal state buffer.

Since many encodings are multibyte, it's possible (in cases where input data is being provided from a file or socket) for a conversion to end in the middle of a multibyte sequence or for the output buffer to be too small to hold the complete encoding of the final character. This routine buffers any partial encoding, using those bytes as the start of a character sequence for the next PxTranslateStateToUTF() call.

This routine uses an appropriately sized temporary overflow buffer, allocated by the PxTranslateSet() routine.

The parameters src and maxsrc specify the input buffer; the parameters dst and maxdst specify the output UTF-8 buffer. These have the same meaning as in the PxTranslateToUTF() function. The consumed parameter will be updated with the number of bytes converted from the source buffer; this may be NULL if this information isn't required (i.e. if the source is always correctly encoded and the destination buffer is always sufficiently large).

Returns:

The number of bytes produced in the destination buffer, or -1 on error.

Classification:

Photon

See also:

PxTranslateList(), PxTranslateFromUTF(), PxTranslateSet(), PxTranslateStateFromUTF(), PxTranslateToUTF(), PxTranslateUnknown()

Unicode Multilingual Support in the Photon Programmer's Guide