Java String codePointBefore()

1. Overview

In this String Methods series, you'll learn what is codePointBefore() method in String API and with example programs.

2. Java String codePointBefore()

codePointBefore() method returns the character (Unicode code point) before the specified index. The index refers to char values (Unicode code units) and ranges from 1 to length.

If the char value at (index - 1) is in the low-surrogate range, (index - 2) is not negative, and the char value at (index - 2) is in the high-surrogate range, then the supplementary code point value of the surrogate pair is returned. If the char value at index - 1 is an unpaired low-surrogate or a high-surrogate, the surrogate value is returned.

3. Java String codePointBefore() Syntax

public int codePointBefore​(int index)

This method takes an integer value as input and returns a Unicode or ASCII value of the previous index. 
And also the return type is an integer.

If the index is not within the range of String length then it throws IndexOutOfBoundsException. But, here it is slightly different than normal and for this method index should be in between 1 and string length.

4. Java String codePointBefore() Example

package com.javaprogramto.strings;

public class StringCodepointBeforeExample {

    public static void main(String[] args) {

        String str = "JavaProgramTo.com";

        System.out.println("Input string value : "+str);

        int codepointBefore = str.codePointBefore(2);
        System.out.println("Code point for before index 2 : "+codepointBefore);

        codepointBefore = str.codePointBefore(str.length());
        System.out.println("Code point for before index "+str.length()+": "+codepointBefore);
    }
}

Output:

Input string value : JavaProgramTo.com
Code point for before index 2 : 97
Code point for before index 17: 109

4. String codePointBefore() Throws IndexOutOfBoundsException

Look at the below program that throws an exception for index 0. Because it does look up for the value at index -1.

package com.javaprogramto.strings;

public class StringCodepointBeforeException {

    public static void main(String[] args) {

        String str = "hello world";

        System.out.println("Input string value : "+str);

        int codepointBefore = str.codePointBefore(0);
        System.out.println("Code point for before index 0 : "+codepointBefore);
    }
}

Output:

Input string value : hello world
Exception in thread "main" java.lang.StringIndexOutOfBoundsException: String index out of range: 0
	at java.base/java.lang.String.codePointBefore(String.java:756)
	at com.javaprogramto.strings.StringCodepointBeforeException.main(StringCodepointBeforeException.java:11)

5. Another example to show IndexOutOfBoundsException

Even though if you pass negative index then it produces the same IndexOutOfBoundsException at runtime.

  package com.javaprogramto.strings;
  
public class StringCodepointBeforeException {
    public static void main(String[] args) {
        String str = "hello world";

           System.out.println("Input string value : "+str);
  
            int codepointBefore = str.codePointBefore(-2);
 
            System.out.println("Code point for before index
    0 : "+codepointBefore);
  
    }
}

Output:

  
Input string value : hello world
    Exception in thread "main" java.lang.StringIndexOutOfBoundsException: String
    index out of range: -2
     at
    java.base/java.lang.String.codePointBefore(String.java:756)
     at
    com.javaprogramto.strings.StringCodepointBeforeException.main(StringCodepointBeforeException.java:11)
  

6. codePointBefore() Internal Implementation

     public int codePointBefore(int index) {
        int i = index - 1;
  
        if (i < 0 || i >= length()) {
                throw new
    StringIndexOutOfBoundsException(index);  
        }
  
        if (isLatin1()) {

                return (value[i] & 0xff);  
        }
            return StringUTF16.codePointBefore(value,
    index);
 
    }

7. Conclusion

In this article, You've seen how to get the before index value from string for a given index. This method works with surrogate points as well.

Shown the examples on codePointBefore() method and some sample programs to show how this method produces runtime exception.

As usual, all examples are over GitHub.

Ref

Code Point

IndexOutOfBoundsException