java.lang.Object | |
↳ | java.text.BreakIterator |
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 four built-in types of BreakIterator
:
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".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 BreakIterator
s uphold the following
invariants:
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()
.
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 it 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 the 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 the 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 last = wb.following(pos); int current = wb.next(); while (current != BreakIterator.DONE) { for (int p = last; p < current; p++) { if (Character.isLetter(text.charAt(p))) return last; } last = current; current = wb.next(); } return BreakIterator.DONE; }
The iterator returned by BreakIterator.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 a simple heuristic to determine which boundary is
the beginning of a word: If the characters between this boundary and the next
boundary include at least one letter (this can be an alphabetical letter, a
CJK ideograph, a Hangul syllable, a Kana character, etc.), then the text
between this boundary and the next is a word; otherwise, it's the material
between words.)
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | DONE | This constant is returned by iterate methods like previous() or
next() if they have returned all valid boundaries. |
Protected Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Default constructor, for use by subclasses.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Returns a copy of this iterator.
| |||||||||||
Returns this iterator's current position.
| |||||||||||
Sets this iterator's current position to the first boundary and returns
that position.
| |||||||||||
Sets the position of the first boundary to the one following the given
offset and returns this position.
| |||||||||||
Returns an array of locales for which custom
BreakIterator instances
are available. | |||||||||||
Returns a new instance of
BreakIterator to iterate over
characters using the given locale. | |||||||||||
Returns a new instance of
BreakIterator to iterate over
characters using the user's default locale. | |||||||||||
Returns a new instance of
BreakIterator to iterate over
line breaks using the given locale. | |||||||||||
Returns a new instance of {
BreakIterator to iterate over
line breaks using the user's default locale. | |||||||||||
Returns a new instance of
BreakIterator to iterate over
sentence-breaks using the given locale. | |||||||||||
Returns a new instance of
BreakIterator to iterate over
sentence-breaks using the default locale. | |||||||||||
Returns a
CharacterIterator which represents the text being
analyzed. | |||||||||||
Returns a new instance of
BreakIterator to iterate over
word-breaks using the default locale. | |||||||||||
Returns a new instance of
BreakIterator to iterate over
word-breaks using the given locale. | |||||||||||
Indicates whether the given offset is a boundary position.
| |||||||||||
Sets this iterator's current position to the last boundary and returns
that position.
| |||||||||||
Sets this iterator's current position to the next boundary after the
given position, and returns that position.
| |||||||||||
Sets this iterator's current position to the next boundary after the
current position, and returns this position.
| |||||||||||
Returns the position of last boundary preceding the given offset, and
sets the current position to the returned value, or
DONE if the
given offset specifies the starting position. | |||||||||||
Sets this iterator's current position to the previous boundary before the
current position and returns that position.
| |||||||||||
Sets the new text string to be analyzed, the current position will be
reset to the beginning of this new string, and the old string will be
lost.
| |||||||||||
Sets the new text to be analyzed by the given
CharacterIterator . |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
This constant is returned by iterate methods like previous()
or
next()
if they have returned all valid boundaries.
Returns a copy of this iterator.
Returns this iterator's current position.
Sets this iterator's current position to the first boundary and returns that position.
Sets the position of the first boundary to the one following the given
offset and returns this position. Returns DONE
if there is no
boundary after the given offset.
offset | the given position to be searched for. |
---|
IllegalArgumentException | if the offset is invalid. |
---|
Returns an array of locales for which custom BreakIterator
instances
are available.
Note that Android does not support user-supplied locale service providers.
Returns a new instance of BreakIterator
to iterate over
characters using the given locale.
where | the given locale. |
---|
BreakIterator
using the given locale.
Returns a new instance of BreakIterator
to iterate over
characters using the user's default locale.
See "Be wary of the default locale".
BreakIterator
using the default locale.
Returns a new instance of BreakIterator
to iterate over
line breaks using the given locale.
where | the given locale. |
---|
BreakIterator
using the given locale.NullPointerException | if where is null .
|
---|
Returns a new instance of {BreakIterator
to iterate over
line breaks using the user's default locale.
See "Be wary of the default locale".
BreakIterator
using the default locale.
Returns a new instance of BreakIterator
to iterate over
sentence-breaks using the given locale.
where | the given locale. |
---|
BreakIterator
using the given locale.NullPointerException | if where is null .
|
---|
Returns a new instance of BreakIterator
to iterate over
sentence-breaks using the default locale.
See "Be wary of the default locale".
BreakIterator
using the default locale.
Returns a CharacterIterator
which represents the text being
analyzed. Please note that the returned value is probably the internal
iterator used by this object. If the invoker wants to modify the status
of the returned iterator, it is recommended to first create a clone of
the iterator returned.
CharacterIterator
which represents the text being
analyzed.
Returns a new instance of BreakIterator
to iterate over
word-breaks using the default locale.
See "Be wary of the default locale".
BreakIterator
using the default locale.
Returns a new instance of BreakIterator
to iterate over
word-breaks using the given locale.
where | the given locale. |
---|
BreakIterator
using the given locale.NullPointerException | if where is null .
|
---|
Indicates whether the given offset is a boundary position. If this method
returns true, the current iteration position is set to the given
position; if the function returns false, the current iteration position
is set as though following(int)
had been called.
offset | the given offset to check. |
---|
true
if the given offset is a boundary position; false
otherwise.
Sets this iterator's current position to the last boundary and returns that position.
Sets this iterator's current position to the next boundary after the
given position, and returns that position. Returns DONE
if no
boundary was found after the given position.
n | the given position. |
---|
Sets this iterator's current position to the next boundary after the
current position, and returns this position. Returns DONE
if no
boundary was found after the current position.
Returns the position of last boundary preceding the given offset, and
sets the current position to the returned value, or DONE
if the
given offset specifies the starting position.
offset | the given start position to be searched for. |
---|
IllegalArgumentException | if the offset is invalid. |
---|
Sets this iterator's current position to the previous boundary before the
current position and returns that position. Returns DONE
if
no boundary was found before the current position.
Sets the new text string to be analyzed, the current position will be reset to the beginning of this new string, and the old string will be lost.
newText | the new text string to be analyzed. |
---|
Sets the new text to be analyzed by the given CharacterIterator
.
The position will be reset to the beginning of the new text, and other
status information of this iterator will be kept.
newText | the CharacterIterator referring to the text to be
analyzed.
|
---|