/* CollationElementIterator.java -- Walks through collation elements
   Copyright (C) 1998, 1999 Free Software Foundation, Inc.

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
 
GNU Classpath 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 for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA.

As a special exception, if you link this library with other files to
produce an executable, this library does not by itself cause the
resulting executable to be covered by the GNU General Public License.
This exception does not however invalidate any other reasons why the
executable file might be covered by the GNU General Public License. */


package java.text;

/**
  * This class walks through the character collation elements of a 
  * <code>String</code> as defined by the collation rules in an instance of 
  * <code>RuleBasedCollator</code>.  There is no public constructor for
  * this class.  An instance is created by calling the
  * <code>getCollationElementIterator</code> method on 
  * <code>RuleBasedCollator</code>.
  *
  * @author Aaron M. Renn (arenn@urbanophile.com)
  */
public final class CollationElementIterator
{

/*
 * Static Variables
 */

/**
  * This is a constant value that is returned to indicate that the end of 
  * the string was encountered.
  */
public static final int NULLORDER = -1;

/*************************************************************************/

/*
 * Instance Variables
 */

/**
  * This is the RuleBasedCollator this object was created from.
  */
private RuleBasedCollator rbc;

/**
  * This is the String that is being iterated over.
  */
private String str;

/**
  * This is the index into the String where we are currently scanning.
  */
private int pos;

/*************************************************************************/

/*
 * Static Methods
 */

/**
  * This method returns the primary order value for the given collation
  * value.
  *
  * @param value The collation value returned from <code>next()</code> or <code>previous()</code>.
  *
  * @return The primary order value of the specified collation value.  This is the high 16 bits.
  */
public static final int
primaryOrder(int value)
{
  return((int)((value & 0xFFFF0000L) >> 16));
}

/*************************************************************************/

/**
  * This method returns the secondary order value for the given collation
  * value.
  *
  * @param value The collation value returned from <code>next()</code> or <code>previous()</code>.
  *
  * @return The secondary order value of the specified collation value.  This is the bits 8-15.
  */
public static final int
secondaryOrder(int value)
{
  return((value & 0xFF00) >> 8);
}

/*************************************************************************/

/**
  * This method returns the tertiary order value for the given collation
  * value.
  *
  * @param value The collation value returned from <code>next()</code> or <code>previous()</code>.
  *
  * @return The tertiary order value of the specified collation value.  This is the low eight bits.
  */
public static final int
tertiaryOrder(int value)
{
  return(value & 0xFF);
}

/*************************************************************************/

/*
 * Constructors
 */

/**
  * This method initializes a new instance of <code>CollationElementIterator</code>
  * to iterate over the specified <code>String</code> using the rules in the
  * specified <code>RuleBasedCollator</code>.
  *
  * @param rbc The <code>RuleBasedCollation</code> used for calculating collation values
  * @param str The <code>String</code> to iterate over.
  */
CollationElementIterator(RuleBasedCollator rbc, String str)
{
  this.rbc = rbc;
  this.str = str;
}

/*************************************************************************/

/*
 * Instance Methods
 */

/**
  * This method sets the <code>String</code> that it is iterating over
  * to the specified <code>String</code>.
  *
  * @param The new <code>String</code> to iterate over.
  */
public void
setText(String str)
{
  this.str = str;
  pos = 0;
}

/*************************************************************************/

/**
  * This method sets the <code>String</code> that it is iterating over
  * to the <code>String</code> represented by the specified
  * <code>CharacterIterator</code>.
  *
  * @param ci The <code>CharacterIterator</code> containing the new <code>String</code> to iterate over.
  */
public void
setText(CharacterIterator ci)
{
  StringBuffer sb = new StringBuffer("");

  // For now assume we read from the beginning of the string.
  char c = ci.first();
  while (c != CharacterIterator.DONE)
    {
      sb.append(c);
      c = ci.next();
    }

  setText(sb.toString());
}

/*************************************************************************/

/**
  * This method returns the current offset into the <code>String</code>
  * that is being iterated over.
  *
  * @return The iteration index position.
  */
public int
getOffset()
{
  return(pos);
}

/*************************************************************************/

/**
  * This method sets the iteration index position into the current
  * <code>String</code> to the specified value.  This value must not
  * be negative and must not be greater than the last index position
  * in the <code>String</code>.
  *
  * @param offset The new iteration index position.
  *
  * @exception IllegalArgumentException If the new offset is not valid.
  */
public void
setOffset(int offset)
{
  if (offset < 0)
    throw new IllegalArgumentException("Negative offset: " + offset);

  if ((str.length() > 0) && (offset > 0))
    throw new IllegalArgumentException("Offset too large: " + offset);
  else if (offset > (str.length() - 1))
    throw new IllegalArgumentException("Offset too large: " + offset);

  pos = offset;
}    

/*************************************************************************/

/**
  * This method returns the maximum length of any expansion sequence that
  * ends with the specified collation order value.  (Whatever that means).
  *
  * @param value The collation order value
  *
  * @param The maximum length of an expansion sequence.
  */
public int
getMaxExpansion(int value)
{
  //************ Implement me!!!!!!!!!
  return(5);
}

/*************************************************************************/

/**
  * This method resets the internal position pointer to read from the
  * beginning of the <code>String again.
  */
public void
reset()
{
  pos = 0;
}

/*************************************************************************/

/**
  * This method returns the collation ordering value of the next character
  * in the string.  This method will return <code>NULLORDER</code> if the
  * end of the string was reached.
  *
  * @return The collation ordering value.
  */
public int
next()
{
  ++pos;
  if (pos == str.length())
    return(NULLORDER);

  String s = str.charAt(pos) + "";
  return(rbc.getCollationElementValue(s));
}

/*************************************************************************/

/**
  * This method returns the collation ordering value of the previous character
  * in the string.  This method will return <code>NULLORDER</code> if the
  * beginning of the string was reached.
  *
  * @return The collation ordering value.
  */
public int
previous()
{
  --pos;
  if (pos < 0)
    return(NULLORDER);

  String s = str.charAt(pos) + "";
  return(rbc.getCollationElementValue(s));
}

} // class CollationElementIterator