ENCConvertString[Src]To[Dst]

Syntax

#include <revolution/enc.h>

ENCResult ENCConvertStringAsciiToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
ENCResult ENCConvertStringUnicodeToAscii(u8* dst, s32* dstlen, const u16* src, s32* srclen);

ENCResult ENCConvertStringUtf32ToUtf16(u16* dst, s32* dstlen, const u32* src, s32* srclen);
ENCResult ENCConvertStringUtf16ToUtf32(u32* dst, s32* dstlen, const u16* src, s32* srclen);
ENCResult ENCConvertStringUtf16ToUtf8(u8* dst, s32* dstlen, const u16* src, s32* srclen);
ENCResult ENCConvertStringUtf8ToUtf16(u16* dst, s32* dstlen, const u8* src, s32* srclen);

ENCResult ENCConvertStringSjisToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
ENCResult ENCConvertStringUnicodeToSjis(u8* dst, s32* dstlen, const u16* src, s32* srclen);
ENCResult ENCConvertStringJisToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
ENCResult ENCConvertStringUnicodeToJis(u8* dst, s32* dstlen, const u16* src, s32* srclen);

ENCResult ENCConvertStringGb2312ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
ENCResult ENCConvertStringUnicodeToGb2312(u8* dst, s32* dstlen, const u16* src, s32* srclen);

ENCResult ENCConvertStringUhcToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
ENCResult ENCConvertStringUnicodeToUhc(u8* dst, s32* dstlen, const u16* src, s32* srclen);

ENCResult ENCConvertStringLatin1ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
ENCResult ENCConvertStringUnicodeToLatin1(u8* dst, s32* dstlen, const u16* src, s32* srclen);
ENCResult ENCConvertStringLatin2ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
ENCResult ENCConvertStringUnicodeToLatin2(u8* dst, s32* dstlen, const u16* src, s32* srclen);
ENCResult ENCConvertStringLatin3ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
ENCResult ENCConvertStringUnicodeToLatin3(u8* dst, s32* dstlen, const u16* src, s32* srclen);
ENCResult ENCConvertStringGreekToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
ENCResult ENCConvertStringUnicodeToGreek(u8* dst, s32* dstlen, const u16* src, s32* srclen);
ENCResult ENCConvertStringLatin6ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
ENCResult ENCConvertStringUnicodeToLatin6(u8* dst, s32* dstlen, const u16* src, s32* srclen);
ENCResult ENCConvertStringLatin9ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
ENCResult ENCConvertStringUnicodeToLatin9(u8* dst, s32* dstlen, const u16* src, s32* srclen);

ENCResult ENCConvertStringWin1252ToUnicode(u16* dst, s32* dstlen, const u8* src, s32* srclen);
ENCResult ENCConvertStringUnicodeToWin1252(u8* dst, s32* dstlen, const u16* src, s32* srclen);

Arguments

dst Destination buffer of the converted string. Termination character will not be attached. If dst is NULL, the string will not be written.
dstlen The size of the converted string destination buffer. This is the size (buffer size/type size) of the type-conversion string in *dst.
After conversion, the size written to the buffer will be stored.
When dst is NULL, the destination buffer size will be ignored, and the buffer size necessary for writing the converted string will be stored.
src The source string buffer.
srclen The source string buffer size. This is the size (buffer size/type size) of the type-conversion string in *src. A string larger than specified by srclen will not be read.
If srclen is NULL or a negative value, src will be loaded until the termination character is found.
If srclen is not NULL, the size of the loaded string buffer will be stored here.

Return Values

ENC_OK: Normal exit.
ENC_ERR_NO_BUF_LEFT: Write destination buffer size insufficient.
ENC_ERR_NO_MAP_RULE: Unconvertable characters detected.
ENC_ERR_INVALID_PARAM: Invalid argument.
ENC_ERR_INVALID_FORMAT: Detected characters outside of the prescribed set for the input character code.

Description

Converts the encoding of a given string from [Src] to [Dst] and then obtains the size of the buffer where the converted string was written.
A termination character does not get attached.

If the destination buffer is not specified, the buffer size necessary for the write operation will be obtained.
If a character that cannot be converted is detected, ENC_ERR_NO_MAP_RULE is returned and the conversion process ends.

The size (buffer size/type size) of the type-conversion strings *dst and *src is stored in dstlen and srclen, respectively.For example, UTF-8 is of type u8 and therefore uses single-byte units. Unicode is of type u16 and therefore uses double-byte units.

Function names take the following format:

ENCConvertString[Src]To[Dst]

The relationship between the abbreviations ([Src] and [Dst]) used in function names and the supported character encodings is as follows.
Refer to the ENC API Introduction for details on conversion rules for each of the character encodings.

Abbreviation used in the function name Supported character encoding
Ascii US-ASCII
Unicode UTF-16BE
Utf32 UTF-32BE
Utf16 UTF-16BE, UTF-16LE (input only)
Utf8 UTF-8
Sjis Shift_JIS
Jis ISO-2022-JP
Gb2312 GB2312
Uhc UHC
Latin1 ISO-8859-1
Latin2 ISO-8859-2
Latin3 ISO-8859-3
Greek ISO-8859-7
Latin6 ISO-8859-10
Latin9 ISO-8859-15
Win1252 windows-1252

ENC_ERR_NOT_LOADED was eliminated in RevolutionSDK 3.2.
If you specify conversion to a character code whose conversion table has been stripped, this function will return ENC_ERR_NO_MAP_RULE.

See Also

ENC API Introduction

Revision History

2008/07/08 Revised the description of the buffer size. Added a description of the supported character encodings.
2008/03/31 Eliminated ENC_ERR_NOT_LOADED.
2008/02/21 Added character codes for Korean and Chinese.
2007/11/21 Corrected an error in argument types.
2007/05/24 Added previously omitted functions.
2007/03/02 Corrected errors.
2007/02/05 Added ENC_ERR_NOT_LOADED.
2006/12/25 Added supported character encodings.
2006/10/19 Added supported character encodings.
2006/08/08 Initial version.

CONFIDENTIAL