Oracle TO_MULTI_BYTE() Function

Oracle TO_MULTI_BYTE() is a built-in function that converts all single-byte characters in the given parameter to their corresponding multi-byte characters and returns a value of the same data type as the parameter.

TO_MULTI_BYTE() is the opposite of TO_SINGLE_BYTE().

Oracle `TO_MULTI_BYTE()` Syntax

Here is the syntax for the Oracle TO_MULTI_BYTE() function:

TO_MULTI_BYTE(char)

Parameters

char: Required. It can be a CHAR, VARCHAR2, NCHAR, or NVARCHAR2 data type.

Return Value

The Oracle TO_MULTI_BYTE() function converts all single-byte characters in the given parameter to their corresponding multi-byte characters and returns a value of the same data type as the parameter.

If the single-byte characters in char have no corresponding multi-byte characters, they will appear in the output string as single-byte characters. This function is only useful when the database character set includes both single-byte and multi-byte characters.

This function does not directly support CLOB data but can be passed as an argument through implicit data conversion.

If any argument is NULL, TO_MULTI_BYTE() returns NULL.

Oracle `TO_MULTI_BYTE()` Examples

Here are several examples that demonstrate how to use the Oracle TO_MULTI_BYTE() function.

Basic Usage

The following example demonstrates how to convert the single-byte A to the multi-byte A in UTF8:

SELECT TO_MULTI_BYTE('A')
FROM dual;

输出：

TO_MULTI_BYTE('A')
_____________________
Ａ

Let’s make it more visible with the DUMP() function:

SELECT
  DUMP('A'),
  DUMP(TO_MULTI_BYTE('A'))
FROM dual;

输出：

DUMP('A')           DUMP(TO_MULTI_BYTE('A'))
___________________ ___________________________
Typ=96 Len=1: 65    Typ=1 Len=3: 239,188,161

The type ID for 'A' is 96 and the length is 1. The returned value of TO_MULTI_BYTE('A') has a type ID of 1 and a length of 3.

NULL Parameter

If any argument is NULL, TO_MULTI_BYTE() returns NULL.

SET NULL 'NULL';
SELECT
    TO_MULTI_BYTE(NULL)
FROM dual;

输出：

TO_MULTI_BYTE(NULL)
______________________
NULL

In this example, we use the SET NULL 'NULL'; statement to display the NULL value as the string 'NULL'.

Conclusion

The Oracle TO_MULTI_BYTE() is a built-in function that converts all single-byte characters in the given parameter to their corresponding multi-byte characters and returns a value of the same data type as the parameter.

Oracle TO_MULTI_BYTE() Syntax