1/* GENERATED SOURCE. DO NOT MODIFY. */
2// © 2016 and later: Unicode, Inc. and others.
3// License & terms of use: http://www.unicode.org/copyright.html#License
4/*
5 *******************************************************************************
6 * Copyright (C) 1996-2016, International Business Machines Corporation and    *
7 * others. All Rights Reserved.                                                *
8 *******************************************************************************
9 */
10package android.icu.text;
11
12/**
13 * Interface that defines an API for forward-only iteration
14 * on text objects.
15 * This is a minimal interface for iteration without random access
16 * or backwards iteration. It is especially useful for wrapping
17 * streams with converters into an object for collation or
18 * normalization.
19 *
20 * <p>Characters can be accessed in two ways: as code units or as
21 * code points.
22 * Unicode code points are 21-bit integers and are the scalar values
23 * of Unicode characters. ICU uses the type <code>int</code> for them.
24 * Unicode code units are the storage units of a given
25 * Unicode/UCS Transformation Format (a character encoding scheme).
26 * With UTF-16, all code points can be represented with either one
27 * or two code units ("surrogates").
28 * String storage is typically based on code units, while properties
29 * of characters are typically determined using code point values.
30 * Some processes may be designed to work with sequences of code units,
31 * or it may be known that all characters that are important to an
32 * algorithm can be represented with single code units.
33 * Other processes will need to use the code point access functions.
34 *
35 * <p>ForwardCharacterIterator provides next() to access
36 * a code unit and advance an internal position into the text object,
37 * similar to a <code>return text[position++]</code>.<br>
38 * It provides nextCodePoint() to access a code point and advance an internal
39 * position.
40 *
41 * <p>nextCodePoint() assumes that the current position is that of
42 * the beginning of a code point, i.e., of its first code unit.
43 * After nextCodePoint(), this will be true again.
44 * In general, access to code units and code points in the same
45 * iteration loop should not be mixed. In UTF-16, if the current position
46 * is on a second code unit (Low Surrogate), then only that code unit
47 * is returned even by nextCodePoint().
48 *
49 * Usage:
50 * <code>
51 *  public void function1(UForwardCharacterIterator it) {
52 *     int c;
53 *     while((c=it.next())!=UForwardCharacterIterator.DONE) {
54 *         // use c
55 *      }
56 *  }
57 * </code>
58 * @hide Only a subset of ICU is exposed in Android
59 *
60 */
61
62public interface UForwardCharacterIterator {
63
64    /**
65     * Indicator that we have reached the ends of the UTF16 text.
66     */
67    public static final int DONE = -1;
68    /**
69     * Returns the UTF16 code unit at index, and increments to the next
70     * code unit (post-increment semantics).  If index is out of
71     * range, DONE is returned, and the iterator is reset to the limit
72     * of the text.
73     * @return the next UTF16 code unit, or DONE if the index is at the limit
74     *         of the text.
75     */
76    public int next();
77
78    /**
79     * Returns the code point at index, and increments to the next code
80     * point (post-increment semantics).  If index does not point to a
81     * valid surrogate pair, the behavior is the same as
82     * <code>next()</code>.  Otherwise the iterator is incremented past
83     * the surrogate pair, and the code point represented by the pair
84     * is returned.
85     * @return the next codepoint in text, or DONE if the index is at
86     *         the limit of the text.
87     */
88    public int nextCodePoint();
89
90}
91