Syntax
char *CONV_Utf8ToLocalString(
char *src,
int length,
int *error_code,
size_t *output_length,
CONV_UNICODE_TO_LOCAL UnicodeToLocalCallback
);
Parameters
- src
- [in] A pointer to a UTF-8 string.
- length
- [in] Specifies the number of bytes to convert. Negative values convert the range until the string pointed to by src ends with a NUL.
- error_code
- [out] A pointer to a variable that returns an error code. Specify NULL when no error code is required.
- output_length
- [out] A pointer to a variable that returns the number of output bytes excluding the NUL at the end of the conversion result. Specify NULL when the number of output bytes is not required.
- UnicodeToLocalCallback
- [in] A pointer to a callback function that converts Unicode to a custom code.
Return value
Returns a pointer to the buffer that stores the conversion result if the conversion is successful, NULL otherwise.Remarks
Use this function to convert a UTF-8 string to a string of custom code (original code) defined by the application program.Converts a string of the length specified by length from the beginning of the UTF-8 string pointed to by src with using the callback function specified in UnicodeToLocalCallback, and returns a pointer to the buffer that stores the conversion result.
If you specify a negative value for length, the range until the string pointed to by src ends with NUL is converted.
If a NUL is detected before the string pointed to by src reaches the length specified by length, the string up to the NUL is converted.
If the string pointed to by src contains Unicode that cannot be converted to the custom code, replace that character with '?' and continue the conversion. In this case, it returns the following error code in the variable pointed to by error_code.
| Error code | Description |
|---|---|
| CONV_UNSUPPORTED_CODE_WARNING | It contained a character code that could not be converted. |
If the conversion is successful, end the conversion result string with a NUL and return the number of bytes of the conversion result excluding the NUL to the variable pointed to by output_length.
If the conversion fails, it returns NULL and returns the following error code in the variable pointed to by error_code.
| Error code | Desription |
|---|---|
| CONV_INVALID_PARAMETER_ERROR | Parameter error. |
| CONV_MEMORY_ALLOCATION_ERROR | Memory allocation error. |
| CONV_INVALID_UTF8_FORMAT_ERROR | A byte sequence that does not meet the UTF-8 standard has been detected. |
If this function returns a value other than NULL, you need to free the buffer with the free function.
Convert a Unicode to your custom code with a callback function specified in UnicodeToLocalCallback. The interface of the callback function is as follows:
Syntax
typedef char * (*CONV_UNICODE_TO_LOCAL)(
unsigned short unicode
);
Parameters
- unicode
- [in] Unicode
Return value
If the conversion is successful, it returns a pointer to the buffer containing the character code of the custom code, otherwise NULL.Remarks
Convert the Unicode specified by unicode to a character code of the custom code.If the converted custom code is 1-byte code, store it in the 1st byte of a 2-byte buffer, set NUL in the 2nd byte, and return a pointer to this buffer.
2-byte buffer:
| +0 | 1-byte code |
| +1 | NUL |
If the converted custom code is a 2-byte code, store the 1st byte of code in the 1st byte of a 2-byte buffer, store the 2nd byte of code in the 2nd byte of the buffer and returns a pointer to this buffer.
2-byte buffer:
| +0 | 1st byte of the 2-byte code |
| +1 | 2nd byte of the 2-byte code |
If the character code of the custom code corresponding to the specified Unicode does not exist, NULL is returned.
This interface of the callback function is compatible with the following function:
CONV_UnicodeToCP437ose function
CONV_UnicodeToSjis function
Requirements
Header file:
CodeConversion.hLibrary file:
libCodeConversion.a
libSTARTUPOPH5000.a
Sample
Sample
// Callback function
char *MyUnicodeToCP437(unsigned short unicode)
{
static char buf[2];
if (unicode == 0x00A2){
// '¢' -> 0x9B
buf[0] = 0x9B;
buf[1] = 0;
return buf;
}else if (unicode == 0x00A5){
// '¥' -> 0x9D
buf[0] = 0x9D;
buf[1] = 0;
return buf;
}else{
// Use CONV_UnicodeToCP437ose() for the other code.
return CONV_UnicodeToCP437ose(unicode);
}
}
// Customized conversion
char *My_Utf8ToCP437String(char *src, int length, int *error_code, size_t *output_length)
{
char *ret = CONV_Utf8ToLocalString(src, length, error_code, output_length, MyUnicodeToCP437);
return ret;
}
See also
Last updated: 2021/08/02