What is CharUtils.toChar in Java?

toChar is a static method of the CharUtils class that converts a string into a character object.

The first character of the given string is returned.

The returned value is of the primitive data type: char.

There are two variations of this method.

First variation

The first variation of the method takes a string as an argument.

The method throws an exception if the input string is empty or null.

Second variation

The second variation of the method takes a string as well as a default character as an argument.

The default character is returned in case the given string is empty or null.

How to import `CharUtils`

CharUtils is defined in the Apache Commons Lang package. Apache Commons Lang can be added to the Maven project by adding the following dependency to the pom.xml file.

<dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>3.12.0</version>
</dependency>

For other versions of the commons-lang package, refer to the Maven Repository.

We can import the CharUtils class as follows:

import org.apache.commons.lang3.CharUtils;

Syntax

public static char toChar(String str)

public static char toChar( String str, char defaultValue)

Parameters

str: string to convert to a character

If we use the second form of the method instead:

defaultValue: the character to return if the given string is empty or null

Return value

The function returns the first character of the string or the default character (in case it is specified and the input string is null).

Code

import org.apache.commons.lang3.CharUtils;
public class main {
    public static void main(String[] args) {
        String str = "23A";
        System.out.printf("The output of CharUtils.toChar() for the string - '%s' is %s", str, CharUtils.toChar(str, 'X'));
        System.out.println();
        str = null;
        System.out.printf("The output of CharUtils.toChar() for the string - '%s' is %s", str, CharUtils.toChar(str, 'X'));
        System.out.println();
        str = null;
        System.out.printf("The output of CharUtils.toChar() for the string - '%s' is %s", str, CharUtils.toChar(str));
        System.out.println();
    }
}

Expected output

The output of CharUtils.toChar() for the string - '23A' is 2
The output of CharUtils.toChar() for the string - 'null' is X
Exception in thread "main" java.lang.NullPointerException: The String must not be empty
	at java.base/java.util.Objects.requireNonNull(Objects.java:347)
	at org.apache.commons.lang3.Validate.notEmpty(Validate.java:388)
	at org.apache.commons.lang3.CharUtils.toChar(CharUtils.java:178)
	at Main.main(Main.java:15)

Explanation

str = "23A"

Here, the overloaded method that takes in a default value is used. The method returns 2 as 2 is the first character of the given string.
str = null

Here, the overloaded method that takes in a default value is used. The method returns the default value passed i.e "X" as the given string points to a null reference.
str = null

Here, the method that takes only the input string is used. The method throws an exception indicating that the input string cannot be null or empty.