Java String codePointAt() Method

What You’ll Learn

The codePointAt() method returns the full Unicode code point at a string index. It goes beyond charAt() by correctly handling emoji and other characters that need two char values in Java’s UTF-16 storage.

Definition and Usage

In Java, strings are stored internally as UTF-16 code units. Most letters and symbols fit in one char, but supplementary characters (including many emoji) use a surrogate pair of two char values. The codePointAt(int index) method in java.lang.String reads the complete Unicode character that begins at the given index.

If the character at index is a high surrogate and the next code unit is a low surrogate, Java combines them and returns the supplementary code point. Otherwise it returns the char at that index widened to an int.

📝 Syntax

The codePointAt() method is declared in the String class:

public int codePointAt(int index)

Parameters

• index — the index of the first UTF-16 code unit of the character. Must be between 0 and length() - 1 inclusive.

Return Value

Returns the Unicode code point at the specified index as an int (range 0x0 to 0x10FFFF).

Exceptions

Throws StringIndexOutOfBoundsException if index is negative or greater than or equal to the string length.

Examples Gallery

These programs run in Java 8+. They progress from a simple ASCII lookup to emoji handling and comparison with charAt().

public class CodePointAtExample {
    public static void main(String[] args) {
        String sampleString = "Hello, Java!";

        int codePoint = sampleString.codePointAt(7);

        System.out.println("Code point at index 7: " + codePoint);
        System.out.println("As character: " + (char) codePoint);
    }
}

Code point at index 7: 74
As character: J

public class EmojiCodePoint {
    public static void main(String[] args) {
        String text = "Hi 😀";

        System.out.println("String length (char count): " + text.length());
        System.out.println("Code point at index 3: " + text.codePointAt(3));
        System.out.println("Hex: U+" + Integer.toHexString(text.codePointAt(3)).toUpperCase());
    }
}

String length (char count): 5
Code point at index 3: 128512
Hex: U+1F600

public class CompareMethods {
    public static void main(String[] args) {
        String text = "A😀B";
        int emojiStart = 1;

        char half = text.charAt(emojiStart);
        int full  = text.codePointAt(emojiStart);

        System.out.println("charAt(1):      " + (int) half);
        System.out.println("codePointAt(1): " + full);
    }
}

charAt(1):      55357
codePointAt(1): 128512

public class CodePointHex {
    public static void main(String[] args) {
        String word = "Java";

        for (int i = 0; i < word.length(); i++) {
            int cp = word.codePointAt(i);
            System.out.println("Index " + i + ": U+" +
                String.format("%04X", cp) + " ('" + (char) cp + "')");
        }
    }
}

Index 0: U+004A ('J')
Index 1: U+0061 ('a')
Index 2: U+0076 ('v')
Index 3: U+0061 ('a')

public class CodePointLoop {
    public static void main(String[] args) {
        String text = "Go😀";

        for (int i = 0; i < text.length(); ) {
            int cp = text.codePointAt(i);
            System.out.println("Code point: " + cp);
            i += Character.charCount(cp);
        }
    }
}

Code point: 71
Code point: 111
Code point: 128512

🚀 Common Use Cases

• Emoji and international text — read complete characters regardless of UTF-16 storage.
• Character validation — check whether a code point is a letter, digit, or symbol using Character utility methods.
• Custom parsers — walk strings by real character count instead of raw char count.
• Debugging encoding — print hex code points to trace unexpected symbols in user input.
• Building on charAt() — upgrade ASCII-only logic when your app must support global audiences.

📝 Notes

• The index parameter refers to a UTF-16 code unit position, not a byte offset in the file or network stream.
• Valid indexes run from 0 to length() - 1. An invalid index throws StringIndexOutOfBoundsException.
• A Unicode code point identifies one abstract character; many code points have the same visual appearance in different languages.
• For BMP characters (most everyday text), codePointAt(i) equals (int) str.charAt(i).
• When looping, use Character.charCount(codePointAt(i)) to skip surrogate pairs correctly.

⚡ Optimization

codePointAt() runs in constant time (O(1)) for a single lookup, with a small extra cost when checking surrogate pairs. For heavy text processing across an entire string, consider codePoints() (Java 8+) or codePointCount() to work at the Unicode level without manual index arithmetic. For simple ASCII-only paths, charAt() remains slightly leaner and perfectly adequate.

💡 Best Practices