1/**
2*******************************************************************************
3* Copyright (C) 1996-2005, International Business Machines Corporation and    *
4* others. All Rights Reserved.                                                *
5*******************************************************************************
6*
7*******************************************************************************
8*/
9
10package libcore.icu;
11
12import java.text.CharacterIterator;
13
14/**
15* Collation element iterator JNI wrapper.
16* Iterates over the collation elements of a data string.
17* The iterator supports both forward and backwards full iteration, ie if
18* backwards iteration is performed in the midst of a forward iteration, the
19* result is undefined.
20* To perform a backwards iteration in the midst of a forward iteration,
21* reset() has to be called.
22* This will shift the position to either the start or the last character in the
23* data string depending on whether next() is called or previous().
24* <pre>
25*   RuleBasedCollator coll = Collator.getInstance();
26*   CollationElementIterator iterator = coll.getCollationElementIterator("abc");
27*   int ce = 0;
28*   while (ce != CollationElementIterator.NULLORDER) {
29*     ce = iterator.next();
30*   }
31*   iterator.reset();
32*   while (ce != CollationElementIterator.NULLORDER) {
33*     ce = iterator.previous();
34*   }
35* </pre>
36* @author syn wee quek
37* @stable ICU 2.4
38*/
39public final class CollationElementIteratorICU {
40    /**
41     * Reset the collation elements to their initial state.
42     * This will move the 'cursor' to the beginning of the text.
43     * @stable ICU 2.4
44     */
45    public void reset() {
46        NativeCollation.reset(address);
47    }
48
49    /**
50     * Get the ordering priority of the next collation element in the text.
51     * A single character may contain more than one collation element.
52     * @return next collation elements ordering, or NULLORDER if the end of the
53     *         text is reached.
54     * @stable ICU 2.4
55     */
56    public int next() {
57        return NativeCollation.next(address);
58    }
59
60    /**
61     * Get the ordering priority of the previous collation element in the text.
62     * A single character may contain more than one collation element.
63     * @return previous collation element ordering, or NULLORDER if the end of
64     *         the text is reached.
65     * @stable ICU 2.4
66     */
67    public int previous() {
68        return NativeCollation.previous(address);
69    }
70
71    /**
72     * Get the maximum length of any expansion sequences that end with the
73     * specified comparison order.
74     * @param order collation order returned by previous or next.
75     * @return maximum size of the expansion sequences ending with the collation
76     *              element or 1 if collation element does not occur at the end of
77     *              any expansion sequence
78     * @stable ICU 2.4
79     */
80    public int getMaxExpansion(int order) {
81        return NativeCollation.getMaxExpansion(address, order);
82    }
83
84    /**
85     * Set the text containing the collation elements.
86     * @param source text containing the collation elements.
87     * @stable ICU 2.4
88     */
89    public void setText(String source) {
90        NativeCollation.setText(address, source);
91    }
92
93    public void setText(CharacterIterator source) {
94        NativeCollation.setText(address, source.toString());
95    }
96
97    /**
98     * Get the offset of the current source character.
99     * This is an offset into the text of the character containing the current
100     * collation elements.
101     * @return offset of the current source character.
102     * @stable ICU 2.4
103     */
104    public int getOffset() {
105        return NativeCollation.getOffset(address);
106    }
107
108    /**
109     * Set the offset of the current source character.
110     * This is an offset into the text of the character to be processed.
111     * @param offset The desired character offset.
112     * @stable ICU 2.4
113     */
114    public void setOffset(int offset) {
115        NativeCollation.setOffset(address, offset);
116    }
117
118    /**
119     * Gets the primary order of a collation order.
120     * @param order the collation order
121     * @return the primary order of a collation order.
122     * @stable ICU 2.4
123     */
124    public static int primaryOrder(int order) {
125        return ((order & PRIMARY_ORDER_MASK_) >> PRIMARY_ORDER_SHIFT_) &
126                UNSIGNED_16_BIT_MASK_;
127    }
128
129    /**
130     * Gets the secondary order of a collation order.
131     * @param order the collation order
132     * @return the secondary order of a collation order.
133     * @stable ICU 2.4
134     */
135    public static int secondaryOrder(int order) {
136        return (order & SECONDARY_ORDER_MASK_) >> SECONDARY_ORDER_SHIFT_;
137    }
138
139    /**
140     * Gets the tertiary order of a collation order.
141     * @param order the collation order
142     * @return the tertiary order of a collation order.
143     * @stable ICU 2.4
144     */
145    public static int tertiaryOrder(int order) {
146        return order & TERTIARY_ORDER_MASK_;
147    }
148
149    public static CollationElementIteratorICU getInstance(long collatorAddress, String source) {
150        long iteratorAddress = NativeCollation.getCollationElementIterator(collatorAddress, source);
151        return new CollationElementIteratorICU(iteratorAddress);
152    }
153
154    private CollationElementIteratorICU(long address) {
155        this.address = address;
156    }
157
158    // protected methods --------------------------------------------
159
160    /**
161     * Garbage collection.
162     * Close C collator and reclaim memory.
163     * @stable ICU 2.4
164     */
165    @Override protected void finalize() throws Throwable {
166        try {
167            NativeCollation.closeElements(address);
168        } finally {
169            super.finalize();
170        }
171    }
172
173    // private data members -----------------------------------------
174
175    /**
176     * C collator
177     */
178    private final long address;
179
180    /**
181     * ICU constant primary order mask for collation elements
182     */
183    private static final int PRIMARY_ORDER_MASK_ = 0xffff0000;
184    /**
185     * ICU constant secondary order mask for collation elements
186     */
187    private static final int SECONDARY_ORDER_MASK_ = 0x0000ff00;
188    /**
189     * ICU constant tertiary order mask for collation elements
190     */
191    private static final int TERTIARY_ORDER_MASK_ = 0x000000ff;
192    /**
193     * ICU constant primary order shift for collation elements
194     */
195    private static final int PRIMARY_ORDER_SHIFT_ = 16;
196    /**
197     * ICU constant secondary order shift for collation elements
198     */
199    private static final int SECONDARY_ORDER_SHIFT_ = 8;
200    /**
201     * Unsigned 16 bit mask
202     */
203    private static final int UNSIGNED_16_BIT_MASK_ = 0x0000FFFF;
204}
205