CharSequence in Java

java.lang.CharSequence

A CharSequence is a readable sequence of char values. This interface provides uniform, read-only access to many different kinds of char sequences. A char value represents a character in the BasicMultilingual Plane (BMP) or surrogate. 

This interface does not refine the general contracts of the equals and hashcode methods. The result of testing two objects that implement CharSequence for equality is, therefore, in general, undefined. Each object may be implemented by a different class, and there is no guarantee that each class will be capable of testing its instances for equality with those of the other. It is therefore inappropriate to use arbitrary CharSequence instances as elements in a set or as keys in a map.

Subinterfaces:

Name

Implementing Classes:

CharBuffer

Segment

String

StringBuffer

StringBuilder

Declaration

public interface CharSequence {

    int length();

    char charAt(int index);

    default boolean isEmpty() {
        return this.length() == 0;
    }

    CharSequence subSequence(int start, int end);

    public String toString();

    public default IntStream chars() {
        class CharIterator implements PrimitiveIterator.OfInt {
            int cur = 0;

            public boolean hasNext() {
                return cur < length();
            }

            public int nextInt() {
                if (hasNext()) {
                    return charAt(cur++);
                } else {
                    throw new NoSuchElementException();
                }
            }

            @Override
            public void forEachRemaining(IntConsumer block) {
                for (; cur < length(); cur++) {
                    block.accept(charAt(cur));
                }
            }
        }

        return StreamSupport.intStream(
                () -> Spliterators.spliterator(new CharIterator(), length(), Spliterator.ORDERED),
                Spliterator.SUBSIZED | Spliterator.SIZED | Spliterator.ORDERED, false);
    }

    public default IntStream codePoints() {
        class CodePointIterator implements PrimitiveIterator.OfInt {
            int cur = 0;

            @Override
            public void forEachRemaining(IntConsumer block) {
                final int length = length();
                int i = cur;
                try {
                    while (i < length) {
                        char c1 = charAt(i++);
                        if (!Character.isHighSurrogate(c1) || i >= length) {
                            block.accept(c1);
                        } else {
                            char c2 = charAt(i);
                            if (Character.isLowSurrogate(c2)) {
                                i++;
                                block.accept(Character.toCodePoint(c1, c2));
                            } else {
                                block.accept(c1);
                            }
                        }
                    }
                } finally {
                    cur = i;
                }
            }

            public boolean hasNext() {
                return cur < length();
            }

            public int nextInt() {
                final int length = length();

                if (cur >= length) {
                    throw new NoSuchElementException();
                }
                char c1 = charAt(cur++);
                if (Character.isHighSurrogate(c1) && cur < length) {
                    char c2 = charAt(cur);
                    if (Character.isLowSurrogate(c2)) {
                        cur++;
                        return Character.toCodePoint(c1, c2);
                    }
                }
                return c1;
            }
        }

        return StreamSupport.intStream(
                () -> Spliterators.spliteratorUnknownSize(new CodePointIterator(), Spliterator.ORDERED),
                Spliterator.ORDERED, false);
    }

    @SuppressWarnings("unchecked")
    public static int compare(CharSequence cs1, CharSequence cs2) {
        if (Objects.requireNonNull(cs1) == Objects.requireNonNull(cs2)) {
            return 0;
        }

        if (cs1.getClass() == cs2.getClass() && cs1 instanceof Comparable) {
            return ((Comparable<Object>) cs1).compareTo(cs2);
        }

        for (int i = 0, len = Math.min(cs1.length(), cs2.length()); i < len; i++) {
            char a = cs1.charAt(i);
            char b = cs2.charAt(i);
            if (a != b) {
                return a - b;
            }
        }

        return cs1.length() - cs2.length();
    }

}

Methods

1. length()

int java.lang.CharSequence.length()

Returns the length of this character sequence. The length is the number of 16-bit chars in the sequence.

Returns: the number of chars in this sequence.

2. charAt(int index)

char java.lang.CharSequence.charAt(int index)

Returns the char value at the specified index. An index ranges from zero to length() - 1. The first char value of the sequence is at index zero, the next is at index one, and so on, as for array indexing.

If the char value specified by the index is a surrogate, the surrogate value is returned. 

Parameters: index the index of the char value to be returned.

Returns: the specified char value.

Throws:

1. IndexOutOfBoundsException - if The index argument is negative or not less than length()

3. isEmpty()

boolean java.lang.CharSequence.isEmpty()

Returns true if this character sequence is empty.

Returns: true if length() is 0, otherwise false.

4. subSequence(int start, int end)

CharSequence java.lang.CharSequence.subSequence(int start, int end)

Returns a CharSequence that is a subsequence of this sequence. The subsequence starts with the char value at the specified index and ends with the char value at index end - 1.

Parameters:

1. start the start index, inclusive.

2. end the end index, exclusive.

Returns: the specified subsequence.

Throws:

1. IndexOutOfBoundsException - if the start or end is negative,if the end is greater than length(), or if the start is greater than the end

5. toString()

String java.lang.CharSequence.toString()

Returns a string containing the characters in this sequence in the same order as this sequence. The length of the string will be the length of this sequence.

Returns: a string consisting of exactly this sequence of characters.

6. chars()

IntStream java.lang.CharSequence.chars()

Returns a stream of int zero-extending the char values from this sequence. Any char which maps to a surrogate code point is passed through uninterpreted.

The stream binds to this sequence when the terminal stream operation commences (specifically, for mutable sequences the spliterator for the stream is late-binding). If the sequence is modified during that operation then the result is undefined.

Returns: an IntStream of char values from this sequence.

7. codePoints()

IntStream java.lang.CharSequence.codePoints()

Returns a stream of code point values from this sequence. Any surrogate pairs encountered in the sequence are combined as if by Character.toCodePoint and the result is passed to the stream. Any other code units, including ordinary BMP characters, unpaired surrogates, and undefined code units are zero-extended to int values which are then passed to the stream.

Returns: an IntStream of Unicode code points from this sequence.

8. compare(CharSequence cs1, CharSequence cs2)

int java.lang.CharSequence.compare(CharSequence cs1, CharSequence cs2)

Compares two CharSequence instances lexicographically.

Returns a negative value, zero, or a positive value if the first sequence is lexicographically less than, equal to, or greater than the second, respectively.

Parameters:

1. cs1 the first CharSequence.

2. cs2 the second CharSequence.

Returns: the value 0 if the two CharSequence are equal; a negative integer if the first CharSequenceis lexicographically less than the second; or a positive integer if the first CharSequence is lexicographically greater than the second.