Java - Character toChars() Method

---

---

The Java Character toChars() method converts the specified character (Unicode code point) to its UTF-16 representation stored in a char array.

The Unicode code points are divided into two categories: Basic Multilingual Plane (BMP) characters and Supplementary characters. The BMP characters are ordinary characters that are already represented in 16-bit Unicode representation while supplementary characters are not.

If the specified code point is a BMP value, the resulting char array has the same value as codePoint. If the specified code point is a supplementary code point, the resulting char array has the corresponding surrogate pair.

This method occurs in two polymorphic forms with different parameters.

Syntax

Following is the syntax for Java Character toChars() method

public static char[] toChars(int codePoint)
(or)
public static int toChars(int codePoint, char[] dst, int dstIndex)

Parameters

• codePoint − a Unicode code point

• dst − an array of char in which the codePoint's UTF-16 value is stored

• dstIndex − the start index into the dst array where the converted value is stored

Return Value

This method returns a char array having codePoint's UTF-16 representation.

Example

The following example shows the usage of Java Character toChars(int codePoint) method.

package com.tutorialspoint;
import java.lang.*;
public class CharacterDemo {
   public static void main(String[] args) {

      // create a char array ch
      char ch[];

      // create an int primitive cp and assign value
      int cp = 0x006e;

      // assign result of toChars on cp to ch
      ch = Character.toChars(cp);
      String str = "Char array having cp's UTF-16 representation is ";
      System.out.print( str );

      // use a for loop to print ch
      for (int i = 0; i < ch.length; i++) {
         System.out.print( ch[i] );
      }
   }
}

Output

Let us compile and run the above program, this will produce the following result −

Char array having cp's UTF-16 representation is n

Example

The following example shows the usage of Java Character toChars(int codePoint, char[] dst, int dstIndex) method.

package com.tutorialspoint;
import java.lang.*;
public class CharacterDemo {
   public static void main(String[] args) {

      // create an int primitive cp and assign value
      int cp = 0x0036;

      // create an int primitive res
      int res;

      /**
       *  create a char array dst and assign UTF-16 value of cp
       *  to it using toChars method
       */
      char dst[] = Character.toChars(cp);

      // check if cp is BMP or supplementary code point using toChars
      res = Character.toChars(cp, dst, 0);
      String str1 = "It is a BMP code point";
      String str2 = "It is a is a supplementary code point";

      // print res value
      if ( res == 1 ) {
         System.out.println( str1 );
      } else if ( res == 2 ) {
         System.out.println( str2 );
      }
   }
}

Output

Let us compile and run the above program, this will produce the following result −

It is a BMP code point

Example

The example program given below shows a scenario in which the method throws an IllegalArgument Exception

import java.lang.*;
public class Demo {
   public static void main(String[] args) {
      char ch[];
      int cp = 0x2388211;
      ch = Character.toChars(cp);
      System.out.print("Char array having cp's UTF-16 representation is ");
      for (int i = 0; i < ch.length; i++) {
         System.out.println(ch[i]);
      }
   }
}

Exception

The program given above is first compiled and run, to produce the following output result. It throws an exception as the input given to the method is a non-valid Unicode code point.

Exception in thread "main" java.lang.IllegalArgumentException: Not a valid Unicode code point: 0x2388211
        at java.base/java.lang.Character.toChars(Character.java:8573)
        at Demo.main(Demo.java:9)

Example

Let us see another scenario where the method throws a NullPointer Exception.

import java.lang.*;
public class Demo {
   public static void main(String[] args) {
      int cp = 0x1271;
      int res;      
      res = Character.toChars(cp, null, 0);      
      if ( res == 1 ) {
         System.out.println("It is a BMP code point");
      } else if ( res == 2 ) {
         System.out.println("It is a is a supplementary code point");
      }
   }
}

Exception

Let us compile and run the given program above, the output is obtained as follows – a NullPointerException is thrown −

Exception in thread "main" java.lang.NullPointerException
        at java.base/java.lang.Character.toChars(Character.java:8537)
        at Demo.main(Demo.java:11)