Java String API offsetByCodePoints​() Method Example

1. Java String offsetByCodePoints​() Method Overview

offsetByCodePoints​() method returns the index within this String that is offset from the given index by codePointOffset code points.
Unpaired surrogates within the text range given by index and codePointOffset count as one code point each.

1.1 Syntax

Here is the full syntax for this method and part of java.lang package.

public int offsetByCodePoints​(int index, int codePointOffset)

Article on Java Package

1.2 Parameters

index: the index to be offset
codePointOffset: the offset in code poi

1.3 Returns

int

the index within this String

1.4 Throws

IndexOutOfBoundsException - if index is negative or larger then the length of this String.

1.5 Since

Java 1.5

2. String offsetByCodePoints​() Method Examples

We will write a example program on offsetByCodePoints​ method.

String blogName = "java-w3schools blog is a Googles blog";
int offsetIndex = blogName.offsetByCodePoints(3, 5);
System.out.println("Input String : "+blogName);
System.out.println("offset index : " + offsetIndex);

Output:

Input String : java-w3schools blog is a Googles blog
offset index : 8

3. IndexOutOfBoundsException

This method throws run time exception if the index is negative or more than string length.

If codePointOffset is positive and the substring starting with index has fewer than codePointOffset code points, or if codePointOffset is negative and the substring before index has fewer than the absolute value of codePointOffset code points.

See the below code where passing index is more than it's length. We should see abnormal when execute this program.

int offsetIndex2 = blogName.offsetByCodePoints(30, 100);

Expected exception stack trace:

Exception in thread "main" java.lang.IndexOutOfBoundsException
 at java.base/java.lang.Character.offsetByCodePoints(Character.java:8929)
 at java.base/java.lang.String.offsetByCodePoints(String.java:829)
 at com.java.w3schools.blog.string.StringOffsetByCodePoints.main(StringOffsetByCodePoints.java:18)

4. offsetByCodePoints​() Internal Code

Let us take a look this method api internal code and how it is implemented.

public int offsetByCodePoints(int index, int codePointOffset) {
    if (index < 0 || index > length()) {
        throw new IndexOutOfBoundsException();
    }
    return Character.offsetByCodePoints(this, index, codePointOffset);
}

Step 1: First, does validation on passed parameters. That is index should not be negative and not more than this string.
Step 2: Calls Character.offsetByCodePoints(this, index, codePointOffset) by passing current string, index and codePointOffset values. Character.offsetByCodePoints() method returns index.

5. Conclusion

In this quick tutorial, We've seen example program on "Java String API offsetByCodePoints​() Method" and when it will throw runtime exception if index is not in it's limits.

And also seen how offsetByCodePoints() method works internally.

Example code snippets shown in this article is available on GitHub.