/*
 * The contents of this file are subject to the Mozilla Public License Version 1.1
 * (the "License"); you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at <http://www.mozilla.org/MPL/>.
 * 
 * Software distributed under the License is distributed on an "AS IS" basis, WITHOUT
 * WARRANTY OF ANY KIND, either express or implied. See the License for the specific
 * language governing rights and limitations under the License.
 * 
 * The Original Code is the Venice Web Communities System.
 * 
 * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
 * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
 * Copyright (C) 2001-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
 * 
 * Contributor(s): 
 */
package com.silverwrist.util;

import java.util.BitSet;

/**
 * A variant of the <CODE>BitSet</CODE> that can express itself as a character string.  Each
 * character in the resulting string represents a flag that is "set."  Up to 91 flags can be
 * specified per <CODE>OptionSet</CODE>.
 *
 * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
 * @version X
 * @see java.util.BitSet
 */
public class OptionSet extends BitSet
{
  /*--------------------------------------------------------------------------------
   * Static data members
   *--------------------------------------------------------------------------------
   */

  // The alphabet to use to store individual flags.
  private static final String ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
                                    + "!#$%&()*+,-./:;<=>?@[]^_`{|}~";

  /*--------------------------------------------------------------------------------
   * Constructors
   *--------------------------------------------------------------------------------
   */

  /**
   * Creates a new <CODE>OptionSet</CODE>.  All bits are initially <CODE>false</CODE>.
   */
  public OptionSet()
  {
    super();

  } // end constructor

  /**
   * Creates an <CODE>OptionSet</CODE> whose initial size is large enough to explicitly represent bits with
   * indices in the range 0 through nbits-1. All bits are initially <CODE>false</CODE>.  The maximum
   * size of the <CODE>OptionSet</CODE> is 91.
   *
   * @param nbits The initial size of the bit set.
   * @exception java.lang.NegativeArraySizeException If the specified initial size is negative.
   */
  public OptionSet(int nbits)
  {
    super(Math.min(nbits,ALPHA.length()));

  } // end constructor

  /**
   * Creates an <CODE>OptionSet</CODE> from an array of characters representing "set" options.
   *
   * @param options The options to be set in the new <CODE>OptionSet</CODE>.
   */
  public OptionSet(char[] options)
  {
    super();  // initialize all bits to 0
    for (int i=0; i<options.length; i++)
    { // look at all the chars in the option string and set bits accordingly
      int ndx = ALPHA.indexOf(options[i]);
      if (ndx>=0)
	super.set(ndx);

    } // end for

  } // end constructor

  /**
   * Creates an <CODE>OptionSet</CODE> from a string of characters representing "set" options.
   *
   * @param options The options to be set in the new <CODE>OptionSet</CODE>.
   */
  public OptionSet(String options)
  {
    this(options.toCharArray());

  } // end constructor

  /*--------------------------------------------------------------------------------
   * Internal functions
   *--------------------------------------------------------------------------------
   */

  /**
   * Returns a <CODE>StringBuffer</CODE> representing the current state of this <CODE>OptionSet</CODE>,
   * with one character in it for each bit that is set.
   *
   * @return A <CODE>StringBuffer</CODE> containing the current state of the <CODE>OptionSet</CODE>.
   */
  private StringBuffer asStringBuffer()
  {
    StringBuffer b = new StringBuffer();
    for (int i=0; i<super.length(); i++)
      if (super.get(i))
	b.append(ALPHA.charAt(i));
    return b;

  } // end asStringBuffer

  /*--------------------------------------------------------------------------------
   * Overrides from class BitSet
   *--------------------------------------------------------------------------------
   */

  /**
   * Sets the bit specified by the index to <CODE>false</CODE>.
   *
   * @param bitIndex The index of the bit to be cleared.
   * @exception java.lang.IndexOutOfBoundsException If the specified index is negative or greater than the
   *            maximum option for an <CODE>OptionSet</CODE>.
   */
  public void clear(int bitIndex)
  {
    if (bitIndex>=ALPHA.length())
      throw new IndexOutOfBoundsException();
    super.clear(bitIndex);

  } // end clear

  /**
   * Sets the bits from the specified <CODE>fromIndex</CODE> (inclusive) to the specified <CODE>toIndex</CODE>
   * (exclusive) to <CODE>false</CODE>.
   *
   * @param fromIndex Index of the first bit to be cleared.
   * @param toIndex Index after the last bit to be cleared.
   * @exception java.lang.IndexOutOfBoundException If <CODE>fromIndex</CODE> is negative, or <CODE>fromIndex</CODE>
   *            is greater than the maximum option for an <CODE>OptionSet</CODE>, or <CODE>toIndex</CODE> is negative,
   *            or <CODE>toIndex</CODE> is greater than the maximum option for an <CODE>OptionSet</CODE>, or
   *            <CODE>fromIndex</CODE> is larger than <CODE>toIndex</CODE>.
   */
  public void clear(int fromIndex, int toIndex)
  {
    if ((fromIndex>=ALPHA.length()) || (toIndex>ALPHA.length()))
      throw new IndexOutOfBoundsException();
    super.clear(fromIndex,toIndex);

  } // end clear

  /**
   * Cloning this <CODE>OptionSet</CODE> produces a new <CODE>OptionSet</CODE> that is equal to it. The clone of the
   * option set is another option set that has exactly the same bits set to true as this option set and the same
   * current size.
   *
   * @return A clone of this option set.
   */
  public Object clone()
  {
    OptionSet rc = new OptionSet(this.size());
    for (int i=this.nextSetBit(0); i>=0; i=this.nextSetBit(i+1))
      rc.set(i);
    return rc;

  } // end clone

  /**
   * Sets the bit at the specified index to to the complement of its current value.
   *
   * @param bitIndex The index of the bit to flip.
   * @exception java.lang.IndexOutOfBoundsException If the specified index is negative or greater than the
   *            maximum option for an <CODE>OptionSet</CODE>.
   */
  public void flip(int bitIndex)
  {
    if (bitIndex>=ALPHA.length())
      throw new IndexOutOfBoundsException();
    super.flip(bitIndex);

  } // end flip

  /**
   * Sets the bits from the specified <CODE>fromIndex</CODE> (inclusive) to the specified <CODE>toIndex</CODE>
   * (exclusive) to the complement of their current values.
   *
   * @param fromIndex Index of the first bit to be flipped.
   * @param toIndex Index after the last bit to be flipped.
   * @exception java.lang.IndexOutOfBoundException If <CODE>fromIndex</CODE> is negative, or <CODE>fromIndex</CODE>
   *            is greater than the maximum option for an <CODE>OptionSet</CODE>, or <CODE>toIndex</CODE> is negative,
   *            or <CODE>toIndex</CODE> is greater than the maximum option for an <CODE>OptionSet</CODE>, or
   *            <CODE>fromIndex</CODE> is larger than <CODE>toIndex</CODE>.
   */
  public void flip(int fromIndex, int toIndex)
  {
    if ((fromIndex>=ALPHA.length()) || (toIndex>ALPHA.length()))
      throw new IndexOutOfBoundsException();
    super.flip(fromIndex,toIndex);

  } // end flip

  /**
   * Returns the value of the bit with the specified index. The value is <CODE>true</CODE> if the bit with
   * the index <CODE>bitIndex</CODE> is currently set in this <CODE>OptionSet</CODE>; otherwise, the result
   * is <CODE>false</CODE>.
   *
   * @param bitIndex The bit index.
   * @return The value of the bit with the specified index.
   * @exception java.lang.IndexOutOfBoundsException If the specified index is negative or greater than the
   *            maximum option for an <CODE>OptionSet</CODE>.
   */
  public boolean get(int bitIndex)
  {
    if (bitIndex>=ALPHA.length())
      throw new IndexOutOfBoundsException();
    return super.get(bitIndex);

  } // end get

  /**
   * Returns a new <CODE>OptionSet</CODE> composed of bits from this <CODE>OptionSet</CODE> from
   * <CODE>fromIndex</CODE> (inclusive) to <CODE>toIndex</CODE> (exclusive).
   *
   * @param fromIndex Index of the first bit to be included.
   * @param toIndex Index after the last bit to be included.
   * @return A new <CODE>OptionSet</CODE> from a range of this <CODE>OptionSet</CODE>.
   * @exception java.lang.IndexOutOfBoundException If <CODE>fromIndex</CODE> is negative, or <CODE>fromIndex</CODE>
   *            is greater than the maximum option for an <CODE>OptionSet</CODE>, or <CODE>toIndex</CODE> is negative,
   *            or <CODE>toIndex</CODE> is greater than the maximum option for an <CODE>OptionSet</CODE>, or
   *            <CODE>fromIndex</CODE> is larger than <CODE>toIndex</CODE>.
   */
  public BitSet get(int fromIndex, int toIndex)
  {
    if ((fromIndex>=ALPHA.length()) || (toIndex>ALPHA.length()))
      throw new IndexOutOfBoundsException();
    BitSet tmp = super.get(fromIndex,toIndex);
    OptionSet rc = new OptionSet(tmp.size());
    for (int i=tmp.nextSetBit(0); i>=0; i=tmp.nextSetBit(i+1))
      rc.set(i);
    return rc;

  } // end get

  /**
   * Sets the bit specified by the index to <CODE>true</CODE>.
   *
   * @param bitIndex The index of the bit to be set.
   * @exception java.lang.IndexOutOfBoundsException If the specified index is negative or greater than the
   *            maximum option for an <CODE>OptionSet</CODE>.
   */
  public void set(int bitIndex)
  {
    if (bitIndex>=ALPHA.length())
      throw new IndexOutOfBoundsException();
    super.set(bitIndex);

  } // end set

  /**
   * Sets the bit specified by the index to the specified value.
   *
   * @param bitIndex The index of the bit to be set.
   * @param value A boolean value to set.
   * @exception java.lang.IndexOutOfBoundsException If the specified index is negative or greater than the
   *            maximum option for an <CODE>OptionSet</CODE>.
   */
  public void set(int bitIndex, boolean value)
  {
    if (bitIndex>=ALPHA.length())
      throw new IndexOutOfBoundsException();
    super.set(bitIndex,value);

  } // end set

  /**
   * Sets the bits from the specified <CODE>fromIndex</CODE> (inclusive) to the specified <CODE>toIndex</CODE>
   * (exclusive) to <CODE>true</CODE>.
   *
   * @param fromIndex Index of the first bit to be set.
   * @param toIndex Index after the last bit to be set.
   * @exception java.lang.IndexOutOfBoundException If <CODE>fromIndex</CODE> is negative, or <CODE>fromIndex</CODE>
   *            is greater than the maximum option for an <CODE>OptionSet</CODE>, or <CODE>toIndex</CODE> is negative,
   *            or <CODE>toIndex</CODE> is greater than the maximum option for an <CODE>OptionSet</CODE>, or
   *            <CODE>fromIndex</CODE> is larger than <CODE>toIndex</CODE>.
   */
  public void set(int fromIndex, int toIndex)
  {
    if ((fromIndex>=ALPHA.length()) || (toIndex>ALPHA.length()))
      throw new IndexOutOfBoundsException();
    super.set(fromIndex,toIndex);

  } // end set

  /**
   * Sets the bits from the specified <CODE>fromIndex</CODE> (inclusive) to the specified <CODE>toIndex</CODE>
   * (exclusive) to the specified value.
   *
   * @param fromIndex Index of the first bit to be set.
   * @param toIndex Index after the last bit to be set.
   * @param value A boolean value to set.
   * @exception java.lang.IndexOutOfBoundException If <CODE>fromIndex</CODE> is negative, or <CODE>fromIndex</CODE>
   *            is greater than the maximum option for an <CODE>OptionSet</CODE>, or <CODE>toIndex</CODE> is negative,
   *            or <CODE>toIndex</CODE> is greater than the maximum option for an <CODE>OptionSet</CODE>, or
   *            <CODE>fromIndex</CODE> is larger than <CODE>toIndex</CODE>.
   */
  public void set(int fromIndex, int toIndex, boolean value)
  {
    if ((fromIndex>=ALPHA.length()) || (toIndex>ALPHA.length()))
      throw new IndexOutOfBoundsException();
    super.set(fromIndex,toIndex,value);

  } // end set

  /*--------------------------------------------------------------------------------
   * External operations
   *--------------------------------------------------------------------------------
   */

  /**
   * Sets the value of the specified bit in the <CODE>OptionSet</CODE> to a specified Boolean
   * value, and returns an indication of whether that value was changed.
   *
   * @param ndx The index of the bit to be assigned.
   * @param val <CODE>true</CODE> to set the corresponding bit, <CODE>false</CODE> to clear it.
   * @return <CODE>true</CODE> if the value of the bit in the <CODE>OptionSet</CODE> was changed by this
   *         operation, <CODE>false</CODE> if not.
   * @exception java.lang.IndexOutOfBoundsException If the specified index is negative or greater than the
   *            maximum option for an <CODE>OptionSet</CODE>.
   */
  public boolean assign(int ndx, boolean val)
  {
    if (ndx>=ALPHA.length())
      throw new IndexOutOfBoundsException();
    boolean old = super.get(ndx);
    super.set(ndx,val);
    return (old!=val);

  } // end assign

  /**
   * Resets the state of this <CODE>OptionSet</CODE> from an array of characters representing "set" options.
   *
   * @param options The options to be set in the new <CODE>OptionSet</CODE>.  All options not specified will
   *                be cleared.
   */
  public void assign(char[] options)
  {
    super.clear();

    for (int i=0; i<options.length; i++)
    { // look at all the chars in the option string and set bits accordingly
      int ndx = ALPHA.indexOf(options[i]);
      if (ndx>=0)
	super.set(ndx);

    } // end for

  } // end assign

  /**
   * Resets the state of this <CODE>OptionSet</CODE> from a string of characters representing "set" options.
   *
   * @param options The options to be set in the new <CODE>OptionSet</CODE>.  All options not specified will
   *                be cleared.
   */
  public void assign(String options)
  {
    if (options!=null)
      assign(options.toCharArray());

  } // end assign

  /**
   * Returns a character array representing the current state of this <CODE>OptionSet</CODE>,
   * with one character in it for each bit that is set.
   *
   * @return A character array containing the current state of the <CODE>OptionSet</CODE>.
   */
  public char[] asCharArray()
  {
    return asStringBuffer().toString().toCharArray();

  } // end asCharArray

  /**
   * Returns a string representing the current state of this <CODE>OptionSet</CODE>,
   * with one character in it for each bit that is set.
   *
   * @return A string containing the current state of the <CODE>OptionSet</CODE>.
   */
  public String asString()
  {
    return asStringBuffer().toString();

  } // end asString

  /*--------------------------------------------------------------------------------
   * External static operations
   *--------------------------------------------------------------------------------
   */

  /**
   * Returns the character associated with a specific "option index" by all <CODE>OptionSet</CODE> instances.
   *
   * @param index The index of the character to retrieve.
   * @return The character associated with that index.
   * @exception java.lang.IndexOutOfBoundsException If the specified index is out of range.
   */
  public static final char getOptionChar(int index)
  {
    if ((index<0) || (index>=ALPHA.length()))
      throw new IndexOutOfBoundsException();
    return ALPHA.charAt(index);

  } // end getOptionChar

} // end class OptionSet