Java String codePointAt() method
Syntax and Examples

Introduction

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.

Syntax

    
public int codePointAt(int index)
    
  

Parameters

Parameter	Description
index	The index of the code point to retrieve. It must be a non-negative integer less than the length of the string.

Return Value

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

Examples

Example 1: Basic Usage

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.

Example 2: Working with Characters Outside BMP

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.

Example 3: Iterating Through 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.

Example 4: Handling Index Out Of Bounds

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.