content: /*
   * Copyright (C) 2014 The Android Open Source Project
   * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
   * under the terms of the GNU General Public License version 2 only, as
   * published by the Free Software Foundation.  Oracle designates this
   * particular file as subject to the "Classpath" exception as provided
   * by Oracle in the LICENSE file that accompanied this code.
   *
   * This code is distributed in the hope that it will be useful, but WITHOUT
   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   * version 2 for more details (a copy is included in the LICENSE file that
   * accompanied this code).
   *
   * You should have received a copy of the GNU General Public License version
   * 2 along with this work; if not, write to the Free Software Foundation,
   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   * or visit www.oracle.com if you need additional information or have any
   * questions.
   */
  
  /*
   * (C) Copyright Taligent, Inc. 1996, 1997 - All Rights Reserved
   * (C) Copyright IBM Corp. 1996-1998 - All Rights Reserved
   *
   *   The original version of this source code and documentation is copyrighted
   * and owned by Taligent, Inc., a wholly-owned subsidiary of IBM. These
   * materials are provided under terms of a License Agreement between Taligent
   * and Sun. This technology is protected by multiple US and International
   * patents. This notice and attribution to Taligent may not be removed.
   *   Taligent is a registered trademark of Taligent, Inc.
   *
   */
  
  package java.text;
  
  /**
   * The <code>CollationElementIterator</code> class is used as an iterator
   * to walk through each character of an international string. Use the iterator
   * to return the ordering priority of the positioned character. The ordering
   * priority of a character, which we refer to as a key, defines how a character
   * is collated in the given collation object.
   *
   * <p>
   * For example, consider the following in Spanish:
   * <blockquote>
   * <pre>
   * "ca" &rarr; the first key is key('c') and second key is key('a').
   * "cha" &rarr; the first key is key('ch') and second key is key('a').
   * </pre>
   * </blockquote>
   * And in German,
   * <blockquote>
   * <pre>
   * "\u00e4b" &rarr; the first key is key('a'), the second key is key('e'), and
   * the third key is key('b').
   * </pre>
   * </blockquote>
   * The key of a character is an integer composed of primary order(short),
   * secondary order(byte), and tertiary order(byte). Java strictly defines
   * the size and signedness of its primitive data types. Therefore, the static
   * functions <code>primaryOrder</code>, <code>secondaryOrder</code>, and
   * <code>tertiaryOrder</code> return <code>int</code>, <code>short</code>,
   * and <code>short</code> respectively to ensure the correctness of the key
   * value.
   *
   * <p>
   * Example of the iterator usage,
   * <blockquote>
   * <pre>
   *
   *  String testString = "This is a test";
   *  Collator col = Collator.getInstance();
   *  if (col instanceof RuleBasedCollator) {
   *      RuleBasedCollator ruleBasedCollator = (RuleBasedCollator)col;
   *      CollationElementIterator collationElementIterator = ruleBasedCollator.getCollationElementIterator(testString);
   *      int primaryOrder = CollationElementIterator.primaryOrder(collationElementIterator.next());
   *          :
   *  }
   * </pre>
   * </blockquote>
   *
   * <p>
   * <code>CollationElementIterator.next</code> returns the collation order
   * of the next character. A collation order consists of primary order,
   * secondary order and tertiary order. The data type of the collation
   * order is <strong>int</strong>. The first 16 bits of a collation order
   * is its primary order; the next 8 bits is the secondary order and the
   * last 8 bits is the tertiary order.
   *
   * <p><b>Note:</b> <code>CollationElementIterator</code> is a part of
   * <code>RuleBasedCollator</code> implementation. It is only usable
   * with <code>RuleBasedCollator</code> instances.
   *
   * @see                Collator
   * @see                RuleBasedCollator
   * @author             Helena Shih, Laura Werner, Richard Gillam
   */
  public final class CollationElementIterator
  {
      /**
       * Null order which indicates the end of string is reached by the
       * cursor.
       */
      // Android-changed: use ICU CollationElementIterator constant.
      public final static int NULLORDER = android.icu.text.CollationElementIterator.NULLORDER;
  
      // Android-removed: internal constructors.
  
      // Android-added: ICU iterator to delegate to.
      private android.icu.text.CollationElementIterator icuIterator;
  
     // Android-added: internal constructor taking an ICU CollationElementIterator.
      CollationElementIterator(android.icu.text.CollationElementIterator iterator) {
          icuIterator = iterator;
      }
  
      /**
       * Resets the cursor to the beginning of the string.  The next call
       * to next() will return the first collation element in the string.
       */
      public void reset()
      {
          // Android-changed: delegate to ICU CollationElementIterator.
          icuIterator.reset();
      }
  
      /**
       * Get the next collation element in the string.  <p>This iterator iterates
       * over a sequence of collation elements that were built from the string.
       * Because there isn't necessarily a one-to-one mapping from characters to
       * collation elements, this doesn't mean the same thing as "return the
       * collation element [or ordering priority] of the next character in the
       * string".</p>
       * <p>This function returns the collation element that the iterator is currently
       * pointing to and then updates the internal pointer to point to the next element.
       * previous() updates the pointer first and then returns the element.  This
       * means that when you change direction while iterating (i.e., call next() and
       * then call previous(), or call previous() and then call next()), you'll get
       * back the same element twice.</p>
       *
       * @return the next collation element
       */
      public int next()
      {
          // Android-changed: delegate to ICU CollationElementIterator.
          return icuIterator.next();
      }
  
      /**
       * Get the previous collation element in the string.  <p>This iterator iterates
       * over a sequence of collation elements that were built from the string.
       * Because there isn't necessarily a one-to-one mapping from characters to
       * collation elements, this doesn't mean the same thing as "return the
       * collation element [or ordering priority] of the previous character in the
       * string".</p>
       * <p>This function updates the iterator's internal pointer to point to the
       * collation element preceding the one it's currently pointing to and then
       * returns that element, while next() returns the current element and then
       * updates the pointer.  This means that when you change direction while
       * iterating (i.e., call next() and then call previous(), or call previous()
       * and then call next()), you'll get back the same element twice.</p>
       *
       * @return the previous collation element
       * @since 1.2
       */
      public int previous()
      {
          // Android-changed: delegate to ICU CollationElementIterator.
          return icuIterator.previous();
      }
  
      /**
       * Return the primary component of a collation element.
       * @param order the collation element
       * @return the element's primary component
       */
      public final static int primaryOrder(int order)
      {
          // Android-changed: delegate to ICU CollationElementIterator.
          return android.icu.text.CollationElementIterator.primaryOrder(order);
      }
      /**
       * Return the secondary component of a collation element.
       * @param order the collation element
       * @return the element's secondary component
       */
      public final static short secondaryOrder(int order)
      {
          // Android-changed: delegate to ICU CollationElementIterator.
         return (short) android.icu.text.CollationElementIterator.secondaryOrder(order);
      }
      /**
       * Return the tertiary component of a collation element.
       * @param order the collation element
       * @return the element's tertiary component
       */
      public final static short tertiaryOrder(int order)
      {
          // Android-changed: delegate to ICU CollationElementIterator.
          return (short) android.icu.text.CollationElementIterator.tertiaryOrder(order);
      }
  
      /**
       * Sets the iterator to point to the collation element corresponding to
       * the specified character (the parameter is a CHARACTER offset in the
       * original string, not an offset into its corresponding sequence of
       * collation elements).  The value returned by the next call to next()
       * will be the collation element corresponding to the specified position
       * in the text.  If that position is in the middle of a contracting
       * character sequence, the result of the next call to next() is the
       * collation element for that sequence.  This means that getOffset()
       * is not guaranteed to return the same value as was passed to a preceding
       * call to setOffset().
       *
       * @param newOffset The new character offset into the original text.
       * @since 1.2
       */
      @SuppressWarnings("deprecation") // getBeginIndex, getEndIndex and setIndex are deprecated
      public void setOffset(int newOffset)
      {
          // Android-changed: delegate to ICU CollationElementIterator.
          icuIterator.setOffset(newOffset);
      }
  
      /**
       * Returns the character offset in the original text corresponding to the next
       * collation element.  (That is, getOffset() returns the position in the text
       * corresponding to the collation element that will be returned by the next
       * call to next().)  This value will always be the index of the FIRST character
       * corresponding to the collation element (a contracting character sequence is
       * when two or more characters all correspond to the same collation element).
       * This means if you do setOffset(x) followed immediately by getOffset(), getOffset()
       * won't necessarily return x.
       *
       * @return The character offset in the original text corresponding to the collation
       * element that will be returned by the next call to next().
       * @since 1.2
       */
      public int getOffset()
      {
          // Android-changed: delegate to ICU CollationElementIterator.
          return icuIterator.getOffset();
      }
  
  
      /**
       * Return the maximum length of any expansion sequences that end
       * with the specified comparison order.
       * @param order a collation order returned by previous or next.
       * @return the maximum length of any expansion sequences ending
       *         with the specified order.
       * @since 1.2
       */
      public int getMaxExpansion(int order)
      {
          // Android-changed: delegate to ICU CollationElementIterator.
          return icuIterator.getMaxExpansion(order);
      }
  
      /**
       * Set a new string over which to iterate.
       *
       * @param source  the new source text
       * @since 1.2
       */
      public void setText(String source)
      {
          // Android-changed: delegate to ICU CollationElementIterator.
          icuIterator.setText(source);
      }
  
      /**
       * Set a new string over which to iterate.
       *
       * @param source  the new source text.
       * @since 1.2
       */
      public void setText(CharacterIterator source)
      {
          // Android-changed: delegate to ICU CollationElementIterator.
          icuIterator.setText(source);
      }
  
      // Android-removed: private helper methods and fields.
  }
  