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