org.openide.util

Class CharSequences

java.lang.Object

org.openide.util.CharSequences

public final class CharSequences
extends Object

Efficiently store strings in memory. This class provides useful static methods to create and work with memory efficient CharSequence implementations for strings using just a subsets of UTF characters.

Often the strings we deal with are based on simple English alphabet. Keeping them in memory as char[] isn't really efficient as they may fit in simple byte[]. This utility class does such compression behind the scene. Use the here-in provided methods and your strings will be stored as efficiently as possible. As can be seen from the following example, many languages benefit from the compaction:

CharSequence englishText = CharSequences.create("English Text");
assertTrue("English text can be compacted", CharSequences.isCompact(englishText));

CharSequence russianText = CharSequences.create("\u0420\u0443\u0441\u0441\u043A\u0438\u0439 \u0422\u0435\u043A\u0441\u0442");
assertTrue("Russian text can be compacted", CharSequences.isCompact(russianText));

CharSequence germanText = CharSequences.create("Schl\u00FCssel");
assertTrue("German text can be compacted", CharSequences.isCompact(germanText));

CharSequence czechText = CharSequences.create("\u017Dlu\u0165ou\u010Dk\u00FD k\u016F\u0148");
assertTrue("Czech text can be compacted", CharSequences.isCompact(czechText));

To compare two sequences use dedicated CharSequences.comparator() which understands the compacted representation and uses it, prior to falling back to char by char comparision:

String h1 = "Hello World!";
CharSequence h2 = CharSequences.create(h1);
CharSequence h3 = CharSequences.create(h1.toCharArray(), 0, h1.length());

assertNotSame("Compacted into a new object #1", h1, h2);
assertNotSame("Compacted into a new object #2", h1, h3);
assertNotSame("Compacted into a new object #3", h2, h3);

assertEquals("Content remains the same #1", 0, CharSequences.comparator().compare(h1, h2));
assertEquals("Content remains the same #2", 0, CharSequences.comparator().compare(h2, h3));
assertEquals("Content remains the same #3", 0, CharSequences.comparator().compare(h3, h1));

Use CharSequences.indexOf(java.lang.CharSequence, java.lang.CharSequence) method to search the compacted strings efficiently:

CharSequence horseCarriesPepsi = CharSequences.create("K\u016F\u0148 veze Pepsi.");
int findPepsi = CharSequences.indexOf(horseCarriesPepsi, "Pepsi");
assertEquals("Pepsi found in the sentence", 9, findPepsi);
CharSequence pepsi = horseCarriesPepsi.subSequence(findPepsi, findPepsi + 5);
assertTrue("It is still compacted", CharSequences.isCompact(pepsi));
assertEquals(0, CharSequences.comparator().compare("Pepsi", pepsi));

This library is available on Maven central. Use it with following co-ordinates:

<dependency>
    <groupId>org.netbeans.api</groupId>
    <artifactId>org-openide-util</artifactId>
    <version>RELEASE110</version>
</dependency>

Since:

8.3

Method Summary

Modifier and Type	Method and Description
static Comparator<CharSequence>	comparator() Provides optimized char sequences comparator.
static CharSequence	create(char[] buf, int start, int count) Creates new CharSequence instance representing the chars in the array.
static CharSequence	create(CharSequence s) Creates new CharSequence instance representing the content of another sequence or String efficiently.
static CharSequence	empty() Returns object to represent empty sequence "".
static int	indexOf(CharSequence text, CharSequence seq) Implementation of String.indexOf(String) for character sequences.
static int	indexOf(CharSequence text, CharSequence seq, int fromIndex) Implementation of String.indexOf(String,int) for character sequences.
static boolean	isCompact(CharSequence cs) Predicate to check if provides char sequence is based on compact implementation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static CharSequence create(char[] buf,
                                  int start,
                                  int count)

Creates new CharSequence instance representing the chars in the array. The sequence contains its own copy of the array content represented in an efficient (e.g. byte[]) way.

Parameters:

buf - buffer to copy the characters from

start - starting offset in the buf array

count - number of characters to copy

Returns:

immutable char sequence

create

public static CharSequence create(CharSequence s)

Creates new CharSequence instance representing the content of another sequence or String efficiently.

CharSequence englishText = CharSequences.create("English Text");
assertTrue("English text can be compacted", CharSequences.isCompact(englishText));

CharSequence russianText = CharSequences.create("\u0420\u0443\u0441\u0441\u043A\u0438\u0439 \u0422\u0435\u043A\u0441\u0442");
assertTrue("Russian text can be compacted", CharSequences.isCompact(russianText));

CharSequence germanText = CharSequences.create("Schl\u00FCssel");
assertTrue("German text can be compacted", CharSequences.isCompact(germanText));

CharSequence czechText = CharSequences.create("\u017Dlu\u0165ou\u010Dk\u00FD k\u016F\u0148");
assertTrue("Czech text can be compacted", CharSequences.isCompact(czechText));

Parameters:

s - existing string or sequence of chars

Returns:

immutable char sequence efficiently representing the data

comparator

public static Comparator<CharSequence> comparator()

Provides optimized char sequences comparator.

String h1 = "Hello World!";
CharSequence h2 = CharSequences.create(h1);
CharSequence h3 = CharSequences.create(h1.toCharArray(), 0, h1.length());

assertNotSame("Compacted into a new object #1", h1, h2);
assertNotSame("Compacted into a new object #2", h1, h3);
assertNotSame("Compacted into a new object #3", h2, h3);

assertEquals("Content remains the same #1", 0, CharSequences.comparator().compare(h1, h2));
assertEquals("Content remains the same #2", 0, CharSequences.comparator().compare(h2, h3));
assertEquals("Content remains the same #3", 0, CharSequences.comparator().compare(h3, h1));

Returns:

comparator for CharSequence objects

empty

public static CharSequence empty()

Returns object to represent empty sequence "".

Returns:

char sequence to represent empty sequence

isCompact

public static boolean isCompact(CharSequence cs)

Predicate to check if provides char sequence is based on compact implementation.

Parameters:

cs - char sequence object to check

Returns:

true if compact implementation, false otherwise

indexOf

public static int indexOf(CharSequence text,
                          CharSequence seq)

Implementation of String.indexOf(String) for character sequences.

CharSequence horseCarriesPepsi = CharSequences.create("K\u016F\u0148 veze Pepsi.");
int findPepsi = CharSequences.indexOf(horseCarriesPepsi, "Pepsi");
assertEquals("Pepsi found in the sentence", 9, findPepsi);
CharSequence pepsi = horseCarriesPepsi.subSequence(findPepsi, findPepsi + 5);
assertTrue("It is still compacted", CharSequences.isCompact(pepsi));
assertEquals(0, CharSequences.comparator().compare("Pepsi", pepsi));

Parameters:

text - the text to search

seq - the sequence to find in the text

Returns:

the index of the first occurrence of the specified substring, or -1 if there is no such occurrence

indexOf

public static int indexOf(CharSequence text,
                          CharSequence seq,
                          int fromIndex)

Implementation of String.indexOf(String,int) for character sequences.

Parameters:

text - the text to search

seq - the sequence to find in the text

fromIndex - the index to start searching from

Returns:

the index of the first occurrence of the specified substring, or -1 if there is no such occurrence