String codePointAt() method - Syntax and Examples

Learn about the Java String codePointAt() method. Understand its syntax, parameters, return value, and how to use it with detailed examples.

This reference explains String codePointAt() method - Syntax and Examples through its syntax, examples and boundaries. Use the linked course lessons when the surrounding Java concepts are unfamiliar.

The codePointAt() method in Java's String class is a powerful tool for retrieving characters from a string as code points. Unlike the older charAt() method, which deals with Unicode *characters*, codePointAt() handles *code points*. This distinction becomes vital when dealing with characters outside the Basic Multilingual Plane (BMP) – that is, those represented by more than one Java character.

    public int codePointAt(int index)
    
  

The codePointAt() method returns an int representing the Unicode code point at the specified index.

This example demonstrates how to retrieve a single code point from a string using its index. We'll use a simple ASCII string for clarity.

    String str = "Hello";
int codePoint = str.codePointAt(0);
System.out.println("Code point at index 0: " + codePoint);
    
  

Code point at index 0: 72
    

Explanation: The method retrieves the first character ('H') from the string 'Hello' and converts it to its corresponding Unicode code point, which is 72.

This example highlights a key difference between codePointAt() and charAt(). We will use the emoji '😀' (grinning face), which is outside the Basic Multilingual Plane and requires a surrogate pair to represent.

    String str = "😀"; // String containing a single Unicode code point outside BMP
int codePoint = str.codePointAt(0);
System.out.println("Code Point: " + codePoint);
char charAt = str.charAt(0);
System.out.println("Char At :" + charAt);
    
  

Code Point: 128512
Char At :�
    

Explanation: The code point for '😀' is 128512. The `charAt()` method returns a surrogate character (represented as � in some environments) because it's only dealing with characters, not the full code points.

This example demonstrates how to iterate over all code points within a string. This is crucial when strings contain characters outside BMP, as a single 'character' (as returned by `charAt()`) may actually represent two Java characters.

    String str = "Hello 😀 World";
int startIndex = 0;
while (startIndex < str.length()) {
  int codePoint = str.codePointAt(startIndex);
  System.out.println("Index: " + startIndex + ", Code Point: " + codePoint);
  // Advance the index correctly for code points outside BMP.
  startIndex += Character.charCount(codePoint);
}
    
  

Index: 0, Code Point: 72
Index: 1, Code Point: 101
Index: 2, Code Point: 108
Index: 3, Code Point: 108
Index: 4, Code Point: 111
Index: 5, Code Point: 32
Index: 6, Code Point: 87
Index: 7, Code Point: 111
Index: 8, Code Point: 114
Index: 9, Code Point: 108
Index: 10, Code Point: 100
Index: 11, Code Point: 32
Index: 12, Code Point: 128512
Index: 14, Code Point: 87
Index: 15, Code Point: 111
Index: 16, Code Point: 114
Index: 17, Code Point: 108
Index: 18, Code Point: 100
    

Explanation: The code iterates through the string. For each iteration, it retrieves the code point at the current starting index and prints its value along with the index. Importantly, `Character.charCount(codePoint)` is used to correctly advance the startIndex by the number of Java characters (surrogate pairs) that represent the current code point. Without this adjustment, the loop would skip over characters outside BMP.

This example demonstrates how to handle a possible `IndexOutOfBoundsException` if the provided index is invalid (e.g., negative or greater than or equal to the string length).

    String str = "abc";
int index = 5;

try {
  int codePoint = str.codePointAt(index);
  System.out.println("Code point at index " + index + ": " + codePoint);
} catch (IndexOutOfBoundsException e) {
  System.err.println("Error: Index out of bounds!" + e.getMessage());
}
    
  

Error: Index out of bounds!
    

Explanation: The try-catch block attempts to retrieve the code point at index 5, which is beyond the boundaries of the string 'abc'. Because of this, an `IndexOutOfBoundsException` is thrown, and the catch block prints an error message.

Check the example’s types, inputs and documented behavior before copying it into an application. Some APIs require external libraries, files or platform services; consult their setup notes.

Related explanations: Java Data Types - Primitive and Non-Primitive, Java Class - Blueprint of Objects, Exceptions in Java Introduction.

Supporting documentation: Official Java learning guide.