jdk/src/share/classes/java/text/CharacterIterator.java
author naoto
Tue, 31 Aug 2010 11:27:10 -0700
changeset 6489 9e7015635425
parent 5506 202f599c92aa
child 18156 edb590d448c5
permissions -rw-r--r--
4700857: RFE: separating user locale and user interface locale Reviewed-by: okutsu
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
/*
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     2
 * Copyright (c) 1996, 2000, Oracle and/or its affiliates. All rights reserved.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    10
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
 * accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    20
 *
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    23
 * questions.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    24
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    25
90ce3da70b43 Initial load
duke
parents:
diff changeset
    26
/*
90ce3da70b43 Initial load
duke
parents:
diff changeset
    27
 * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved
90ce3da70b43 Initial load
duke
parents:
diff changeset
    28
 * (C) Copyright IBM Corp. 1996 - 1998 - All Rights Reserved
90ce3da70b43 Initial load
duke
parents:
diff changeset
    29
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    30
 * The original version of this source code and documentation
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
 * is copyrighted and owned by Taligent, Inc., a wholly-owned
90ce3da70b43 Initial load
duke
parents:
diff changeset
    32
 * subsidiary of IBM. These materials are provided under terms
90ce3da70b43 Initial load
duke
parents:
diff changeset
    33
 * of a License Agreement between Taligent and Sun. This technology
90ce3da70b43 Initial load
duke
parents:
diff changeset
    34
 * is protected by multiple US and International patents.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
 * This notice and attribution to Taligent may not be removed.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
 * Taligent is a registered trademark of Taligent, Inc.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
package java.text;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
/**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
 * This interface defines a protocol for bidirectional iteration over text.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
 * The iterator iterates over a bounded sequence of characters.  Characters
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
 * are indexed with values beginning with the value returned by getBeginIndex() and
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
 * continuing through the value returned by getEndIndex()-1.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
 * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
 * Iterators maintain a current character index, whose valid range is from
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
 * getBeginIndex() to getEndIndex(); the value getEndIndex() is included to allow
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
 * handling of zero-length text ranges and for historical reasons.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
 * The current index can be retrieved by calling getIndex() and set directly
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
 * by calling setIndex(), first(), and last().
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
 * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
 * The methods previous() and next() are used for iteration. They return DONE if
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
 * they would move outside the range from getBeginIndex() to getEndIndex() -1,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
 * signaling that the iterator has reached the end of the sequence. DONE is
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
 * also returned by other methods to indicate that the current index is
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
 * outside this range.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
 * <P>Examples:<P>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
 * Traverse the text from start to finish
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
 * <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
 * public void traverseForward(CharacterIterator iter) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
 *     for(char c = iter.first(); c != CharacterIterator.DONE; c = iter.next()) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
 *         processChar(c);
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
 *     }
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
 * }
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
 * </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
 * Traverse the text backwards, from end to start
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
 * <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
 * public void traverseBackward(CharacterIterator iter) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
 *     for(char c = iter.last(); c != CharacterIterator.DONE; c = iter.previous()) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
 *         processChar(c);
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
 *     }
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
 * }
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
 * </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
 * Traverse both forward and backward from a given position in the text.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
 * Calls to notBoundary() in this example represents some
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
 * additional stopping criteria.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
 * <pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
 * public void traverseOut(CharacterIterator iter, int pos) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
 *     for (char c = iter.setIndex(pos);
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
 *              c != CharacterIterator.DONE && notBoundary(c);
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
 *              c = iter.next()) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
 *     }
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
 *     int end = iter.getIndex();
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
 *     for (char c = iter.setIndex(pos);
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
 *             c != CharacterIterator.DONE && notBoundary(c);
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
 *             c = iter.previous()) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
 *     }
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
 *     int start = iter.getIndex();
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
 *     processSection(start, end);
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
 * }
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
 * </pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
 * @see StringCharacterIterator
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
 * @see AttributedCharacterIterator
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
public interface CharacterIterator extends Cloneable
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
{
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
     * Constant that is returned when the iterator has reached either the end
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
     * or the beginning of the text. The value is '\\uFFFF', the "not a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
     * character" value which should not occur in any valid Unicode string.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
    public static final char DONE = '\uFFFF';
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
     * Sets the position to getBeginIndex() and returns the character at that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
     * position.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
     * @return the first character in the text, or DONE if the text is empty
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
     * @see #getBeginIndex()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
    public char first();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
     * Sets the position to getEndIndex()-1 (getEndIndex() if the text is empty)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
     * and returns the character at that position.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
     * @return the last character in the text, or DONE if the text is empty
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
     * @see #getEndIndex()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
    public char last();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
     * Gets the character at the current position (as returned by getIndex()).
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
     * @return the character at the current position or DONE if the current
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
     * position is off the end of the text.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
     * @see #getIndex()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
    public char current();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
     * Increments the iterator's index by one and returns the character
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
     * at the new index.  If the resulting index is greater or equal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
     * to getEndIndex(), the current index is reset to getEndIndex() and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
     * a value of DONE is returned.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
     * @return the character at the new position or DONE if the new
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
     * position is off the end of the text range.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
    public char next();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
     * Decrements the iterator's index by one and returns the character
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
     * at the new index. If the current index is getBeginIndex(), the index
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
     * remains at getBeginIndex() and a value of DONE is returned.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
     * @return the character at the new position or DONE if the current
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
     * position is equal to getBeginIndex().
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
    public char previous();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
     * Sets the position to the specified position in the text and returns that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
     * character.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
     * @param position the position within the text.  Valid values range from
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
     * getBeginIndex() to getEndIndex().  An IllegalArgumentException is thrown
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
     * if an invalid value is supplied.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
     * @return the character at the specified position or DONE if the specified position is equal to getEndIndex()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
    public char setIndex(int position);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
     * Returns the start index of the text.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
     * @return the index at which the text begins.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
    public int getBeginIndex();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
     * Returns the end index of the text.  This index is the index of the first
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
     * character following the end of the text.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
     * @return the index after the last character in the text
90ce3da70b43 Initial load
duke
parents:
diff changeset
   178
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
    public int getEndIndex();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   180
90ce3da70b43 Initial load
duke
parents:
diff changeset
   181
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   182
     * Returns the current index.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
     * @return the current index.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   184
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   185
    public int getIndex();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   186
90ce3da70b43 Initial load
duke
parents:
diff changeset
   187
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
     * Create a copy of this iterator
90ce3da70b43 Initial load
duke
parents:
diff changeset
   189
     * @return A copy of this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   190
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   191
    public Object clone();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   192
90ce3da70b43 Initial load
duke
parents:
diff changeset
   193
}