International Components for Unicode for Java (icu4j) 74.2 · com.ibm.icu.text.BreakIterator

ICU Enhancement

This class is ICU's replacement for java.text.BreakIterator.

ICU

Methods, fields, and other functionality specific to ICU are labeled 'ICU'.

A class that locates boundaries in text. This class defines a protocol for objects that break up a piece of natural-language text according to a set of criteria. Instances or subclasses of BreakIterator can be provided, for example, to break a piece of text into words, sentences, or logical characters according to the conventions of some language or group of languages. We provide five built-in types of BreakIterator:

getTitleInstance() returns a BreakIterator that locates boundaries between title breaks.
getSentenceInstance() returns a BreakIterator that locates boundaries between sentences. This is useful for triple-click selection, for example.
getWordInstance() returns a BreakIterator that locates boundaries between words. This is useful for double-click selection or "find whole words" searches. This type of BreakIterator makes sure there is a boundary position at the beginning and end of each legal word. (Numbers count as words, too.) Whitespace and punctuation are kept separate from real words.
getLineInstance() returns a BreakIterator that locates positions where it is legal for a text editor to wrap lines. This is similar to word breaking, but not the same: punctuation and whitespace are generally kept with words (you don't want a line to start with whitespace, for example), and some special characters can force a position to be considered a line-break position or prevent a position from being a line-break position.
getCharacterInstance() returns a BreakIterator that locates boundaries between logical characters. Because of the structure of the Unicode encoding, a logical character may be stored internally as more than one Unicode code point. (A with an umlaut may be stored as an a followed by a separate combining umlaut character, for example, but the user still thinks of it as one character.) This iterator allows various processes (especially text editors) to treat as characters the units of text that a user would think of as characters, rather than the units of text that the computer sees as "characters".

The text boundary positions are found according to the rules described in Unicode Standard Annex #29, Text Boundaries, and Unicode Standard Annex #14, Line Breaking Properties. These are available at http://www.unicode.org/reports/tr14/ and http://www.unicode.org/reports/tr29/.

BreakIterator's interface follows an "iterator" model (hence the name), meaning it has a concept of a "current position" and methods like first(), last(), next(), and previous() that update the current position. All BreakIterators uphold the following invariants:

The beginning and end of the text are always treated as boundary positions.
The current position of the iterator is always a boundary position (random- access methods move the iterator to the nearest boundary position before or after the specified position, not to the specified position).
DONE is used as a flag to indicate when iteration has stopped. DONE is only returned when the current position is the end of the text and the user calls next(), or when the current position is the beginning of the text and the user calls previous().
Break positions are numbered by the positions of the characters that follow them. Thus, under normal circumstances, the position before the first character is 0, the position after the first character is 1, and the position after the last character is 1 plus the length of the string.
The client can change the position of an iterator, or the text it analyzes, at will, but cannot change the behavior. If the user wants different behavior, he must instantiate a new iterator.

BreakIterator accesses the text it analyzes through a CharacterIterator, which makes it possible to use BreakIterator to analyze text in any text-storage vehicle that provides a CharacterIterator interface

Note

Some types of BreakIterator can take a long time to create, and instances of BreakIterator are not currently cached by the system. For optimal performance, keep instances of BreakIterator around as long as makes sense. For example, when word-wrapping a document, don't create and destroy a new BreakIterator for each line. Create one break iterator for the whole document (or whatever stretch of text you're wrapping) and use it to do the whole job of wrapping the text.

Examples:

Creating and using text boundaries

public static void main(String args[]) {
     if (args.length == 1) {
         String stringToExamine = args[0];
         //print each word in order
         BreakIterator boundary = BreakIterator.getWordInstance();
         boundary.setText(stringToExamine);
         printEachForward(boundary, stringToExamine);
         //print each sentence in reverse order
         boundary = BreakIterator.getSentenceInstance(Locale.US);
         boundary.setText(stringToExamine);
         printEachBackward(boundary, stringToExamine);
         printFirst(boundary, stringToExamine);
         printLast(boundary, stringToExamine);
     }
}

Print each element in order

public static void printEachForward(BreakIterator boundary, String source) {
    int start = boundary.first();
    for (int end = boundary.next();
         end != BreakIterator.DONE;
         start = end, end = boundary.next()) {
         System.out.println(source.substring(start,end));
    }
}

Print each element in reverse order

public static void printEachBackward(BreakIterator boundary, String source) {
    int end = boundary.last();
    for (int start = boundary.previous();
         start != BreakIterator.DONE;
         end = start, start = boundary.previous()) {
        System.out.println(source.substring(start,end));
    }
}

Print first element

public static void printFirst(BreakIterator boundary, String source) {
    int start = boundary.first();
    int end = boundary.next();
    System.out.println(source.substring(start,end));
}

Print last element

public static void printLast(BreakIterator boundary, String source) {
    int end = boundary.last();
    int start = boundary.previous();
    System.out.println(source.substring(start,end));
}

Print the element at a specified position

public static void printAt(BreakIterator boundary, int pos, String source) {
    int end = boundary.following(pos);
    int start = boundary.previous();
    System.out.println(source.substring(start,end));
}

Find the next word

public static int nextWordStartAfter(int pos, String text) {
    BreakIterator wb = BreakIterator.getWordInstance();
    wb.setText(text);
    int wordStart = wb.following(pos);
    for (;;) {
        int wordLimit = wb.next();
        if (wordLimit == BreakIterator.DONE) {
            return BreakIterator.DONE;
        }
        int wordStatus = wb.getRuleStatus();
        if (wordStatus != BreakIterator.WORD_NONE) {
            return wordStart;
        }
        wordStart = wordLimit;
     }
}
The iterator returned by getWordInstance is unique in that the break positions it returns don't represent both the start and end of the thing being iterated over. That is, a sentence-break iterator returns breaks that each represent the end of one sentence and the beginning of the next. With the word-break iterator, the characters between two boundaries might be a word, or they might be the punctuation or whitespace between two words. The above code uses getRuleStatus to identify and ignore boundaries associated with punctuation or other non-word characters.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	BreakIterator.BreakIteratorCache
pack-priv abstract static class	BreakIterator.BreakIteratorServiceShim

Field Summary

Modifier and Type	Field and Description
private ULocale	actualLocale The locale containing data used to construct this object, or null.
private static final boolean	DEBUG
public static final int	DONE DONE is returned by previous() and next() after all valid boundaries have been returned.
private static final CacheValue<?>[]	iterCache
public static final int	KIND_CHARACTER ICU
private static final int	KIND_COUNT
public static final int	KIND_LINE ICU
public static final int	KIND_SENTENCE ICU
public static final int	KIND_TITLE ICU
public static final int	KIND_WORD ICU
private static BreakIterator.BreakIteratorServiceShim	shim
private ULocale	validLocale The most specific locale containing any resource data, or null.
public static final int	WORD_IDEO Tag value for words containing ideographic characters, lower limit
public static final int	WORD_IDEO_LIMIT Tag value for words containing ideographic characters, upper limit
public static final int	WORD_KANA Tag value for words containing kana characters, lower limit
public static final int	WORD_KANA_LIMIT Tag value for words containing kana characters, upper limit
public static final int	WORD_LETTER Tag value for words that contain letters, excluding hiragana, katakana or ideographic characters, lower limit.
public static final int	WORD_LETTER_LIMIT Tag value for words containing letters, upper limit
public static final int	WORD_NONE Tag value for "words" that do not fit into any of other categories.
public static final int	WORD_NONE_LIMIT Upper bound for tags for uncategorized words.
public static final int	WORD_NUMBER Tag value for words that appear to be numbers, lower limit.
public static final int	WORD_NUMBER_LIMIT Tag value for words that appear to be numbers, upper limit.

Access	Constructor and Description
protected	BreakIterator() Default constructor.

Method Summary

Modifier and Type	Method and Description
public Object	Returns: The clone. clone() Overrides java.lang.Object.clone. Clone method.
public abstract int	Returns: The iterator's current position. current() Return the iterator's current position.
public abstract int	Returns: The character offset of the beginning of the stretch of text being broken. first() Set the iterator to the first boundary position.
public abstract int	Returns: The position of the first boundary position following "offset" (whether or not "offset" itself is a boundary position), or DONE if "offset" is the past-the-end offset. following(int The character position to start searching from. offset) Sets the iterator's current iteration position to be the first boundary position following the specified position.
public static synchronized Locale[]	Returns: An array of Locales. All of the locales in the array can be used when creating a BreakIterator. getAvailableLocales() Returns a list of locales for which BreakIterators can be used.
public static synchronized ULocale[]	Returns: An array of Locales. All of the locales in the array can be used when creating a BreakIterator. getAvailableULocales() ICU
public static BreakIterator	getBreakInstance(ULocale where, int kind) Deprecated This API is ICU internal only. Returns a particular kind of BreakIterator for a locale.
public static BreakIterator	Returns: A new instance of BreakIterator that locates logical-character boundaries. getCharacterInstance() Returns a new instance of BreakIterator that locates logical-character boundaries.
public static BreakIterator	Returns: A new instance of BreakIterator that locates logical-character boundaries. getCharacterInstance(Locale A Locale specifying the language of the text being analyzed. where) Returns a new instance of BreakIterator that locates logical-character boundaries.
public static BreakIterator	Returns: A new instance of BreakIterator that locates logical-character boundaries. getCharacterInstance(ULocale A Locale specifying the language of the text being analyzed. where) ICU
public static BreakIterator	Returns: A new instance of BreakIterator that locates legal line-wrapping positions. getLineInstance() Returns a new instance of BreakIterator that locates legal line- wrapping positions.
public static BreakIterator	Returns: A new instance of BreakIterator that locates legal line-wrapping positions. getLineInstance(Locale A Locale specifying the language of the text being broken. where) Returns a new instance of BreakIterator that locates legal line- wrapping positions.
public static BreakIterator	Returns: A new instance of BreakIterator that locates legal line-wrapping positions. getLineInstance(ULocale A Locale specifying the language of the text being broken. where) ICU
public final ULocale	Returns: the information specified by type, or null if this object was not constructed from locale data. getLocale(ULocale.Type type of information requested, either `com.ibm.icu.util.ULocale#VALID_LOCALE` or `com.ibm.icu.util.ULocale#ACTUAL_LOCALE`. type) ICU
public int	Returns: The status from the break rule that determined the boundary at the current iteration position. getRuleStatus() For RuleBasedBreakIterators, return the status tag from the break rule that determined the boundary at the current iteration position.
public int	Returns: The number of rule status values from rules that determined the the boundary at the current iteration position. In the event that the array is too small, the return value is the total number of status values that were available, not the reduced number that were actually returned. getRuleStatusVec(int[] an array to be filled in with the status values. fillInArray) For RuleBasedBreakIterators, get the status (tag) values from the break rule(s) that determined the the boundary at the current iteration position.
public static BreakIterator	Returns: A new instance of BreakIterator that locates sentence boundaries. getSentenceInstance() Returns a new instance of BreakIterator that locates sentence boundaries.
public static BreakIterator	Returns: A new instance of BreakIterator that locates sentence boundaries. getSentenceInstance(Locale A Locale specifying the language of the text being analyzed. where) Returns a new instance of BreakIterator that locates sentence boundaries.
public static BreakIterator	Returns: A new instance of BreakIterator that locates sentence boundaries. getSentenceInstance(ULocale A Locale specifying the language of the text being analyzed. where) ICU
private static BreakIterator.BreakIteratorServiceShim	getShim()
public abstract CharacterIterator	Returns: A CharacterIterator over the text being analyzed. getText() Returns a CharacterIterator over the text being analyzed.
public static BreakIterator	Returns: A new instance of BreakIterator that locates title boundaries. getTitleInstance() Deprecated ICU 64 Use `getWordInstance` instead. ICU
public static BreakIterator	Returns: A new instance of BreakIterator that locates title boundaries. getTitleInstance(Locale A Locale specifying the language of the text being analyzed. where) Deprecated ICU 64 Use `getWordInstance` instead. ICU
public static BreakIterator	Returns: A new instance of BreakIterator that locates title boundaries. getTitleInstance(ULocale A Locale specifying the language of the text being analyzed. where) Deprecated ICU 64 Use `getWordInstance` instead. ICU
public static BreakIterator	Returns: An instance of BreakIterator that locates word boundaries. getWordInstance() Returns a new instance of BreakIterator that locates word boundaries.
public static BreakIterator	Returns: An instance of BreakIterator that locates word boundaries. getWordInstance(Locale A locale specifying the language of the text to be analyzed. where) Returns a new instance of BreakIterator that locates word boundaries.
public static BreakIterator	Returns: An instance of BreakIterator that locates word boundaries. getWordInstance(ULocale A locale specifying the language of the text to be analyzed. where) ICU
public boolean	Returns: True if "offset" is a boundary position. isBoundary(int the offset to check. offset) Return true if the specified position is a boundary position.
public abstract int	Returns: The character offset of the end of the stretch of text being broken. last() Set the iterator to the last boundary position.
public abstract int	Returns: The position of the boundary n boundaries from the current iteration position, or DONE if moving n boundaries causes the iterator to advance off either end of the text. next(int The number of boundaries to advance over (if positive, moves forward; if negative, moves backwards). n) Move the iterator by the specified number of steps in the text.
public abstract int	Returns: The position of the first boundary position following the iteration position. next() Advances the iterator forward one boundary.
public int	Returns: The position of the last boundary position preceding "offset" (whether of not "offset" itself is a boundary position), or DONE if "offset" is the starting offset of the iterator. preceding(int The character position to start searching from. offset) Sets the iterator's current iteration position to be the last boundary position preceding the specified position.
public abstract int	Returns: The position of the last boundary position preceding the iteration position. previous() Move the iterator backward one boundary.
public static Object	Returns: a registry key that can be used to unregister this instance registerInstance(BreakIterator the BreakIterator instance to adopt. iter, Locale the Locale for which this instance is to be registered locale, int the type of iterator for which this instance is to be registered kind) ICU
public static Object	Returns: a registry key that can be used to unregister this instance registerInstance(BreakIterator the BreakIterator instance to adopt. iter, ULocale the Locale for which this instance is to be registered locale, int the type of iterator for which this instance is to be registered kind) ICU
pack-priv final void	setLocale(ULocale the most specific locale containing any resource data, or null valid, ULocale the locale containing data used to construct this object, or null actual) Set information about the locales that were used to create this object.
public void	setText(String A String containing the text to analyze with this BreakIterator. newText) Sets the iterator to analyze a new piece of text.
public void	setText(CharSequence A CharSequence containing the text to analyze with this BreakIterator. newText) Sets the iterator to analyze a new piece of text.
public abstract void	setText(CharacterIterator A CharacterIterator referring to the text to analyze with this BreakIterator (the iterator's current position is ignored, but its other state is significant). newText) Sets the iterator to analyze a new piece of text.
public static boolean	Returns: true if the iterator for the key was successfully unregistered unregister(Object the registry key returned by a previous call to registerInstance key) ICU

Inherited from java.lang.Object:: equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

actualLocale back to summary

actualLocale	back to summary
private ULocale actualLocale The locale containing data used to construct this object, or null. See Also `com.ibm.icu.util.ULocale`

private ULocale actualLocale

The locale containing data used to construct this object, or null.

See Also: com.ibm.icu.util.ULocale

DEBUG	back to summary
private static final boolean DEBUG

DONE	back to summary
public static final int DONE DONE is returned by previous() and next() after all valid boundaries have been returned. ICU Status Stable since ICU 2.0.

DONE

Modifier and Type	Method and Description
pack-priv BreakIterator	createBreakInstance()
pack-priv ULocale	getLocale()

Modifier and Type	Method and Description
public abstract BreakIterator	createBreakIterator(ULocale l, int k)
public abstract Locale[]	getAvailableLocales()
public abstract ULocale[]	getAvailableULocales()
public abstract Object	registerInstance(BreakIterator iter, ULocale l, int k)
public abstract boolean	unregister(Object key)

public abstract Class BreakIterator

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class BreakIterator.BreakIteratorCache

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv abstract Class BreakIterator.BreakIteratorServiceShim

Constructor Summary

Method Summary

Constructor Detail

Method Detail