/*
 * @(#)QuickTreeSet.java    2.3  27 November 2003
 *
 * Copyright 2004
 * College of Computer and Information Science
 * Northeastern University
 * Boston, MA  02115
 *
 * The Java Power Tools software may be used for educational
 * purposes as long as this copyright notice is retained intact
 * at the top of all source files.
 *
 * To discuss possible commercial use of this software, 
 * contact Richard Rasala at Northeastern University, 
 * College of Computer and Information Science,
 * 617-373-2462 or rasala@ccs.neu.edu.
 *
 * The Java Power Tools software has been designed and built
 * in collaboration with Viera Proulx and Jeff Raab.
 *
 * Should this software be modified, the words "Modified from 
 * Original" must be included as a comment below this notice.
 *
 * All publication rights are retained.  This software or its 
 * documentation may not be published in any media either
 * in whole or in part without explicit permission.
 *
 * This software was created with support from Northeastern 
 * University and from NSF grant DUE-9950829.
 */

package edu.neu.ccs.quick;

import java.util.*;

/**
 * <P><CODE>QuickTreeSet</CODE> extends <CODE>TreeSet</CODE> by
 * adding two constructors and three methods <CODE>addItems</CODE>,
 * <CODE>setItems</CODE>, and <CODE>removeItems</CODE> that handle
 * an array of <CODE>Object</CODE> at once.</P>
 *
 * <P>All constructors of the original <CODE>TreeSet</CODE> class
 * are provided as well.</P>
 *
 * <P>No changes are made to the internal data structure.</P>
 
 * <P> The only inherited methods that are overridden are those that
 * will throw an exception on <CODE>null</CODE> arguments.  In this
 * class, such methods will handle <CODE>null</CODE> in a sensible
 * fashion.</P>
 *
 * @author  Richard Rasala
 * @version 2.3
 * @since   2.3
 */
public class QuickTreeSet extends TreeSet {
    
    /** A constructor that delegates to class <CODE>TreeSet</CODE>. */
    public QuickTreeSet() { }
    
    
    /** A constructor that delegates to class <CODE>TreeSet</CODE>. */
    public QuickTreeSet(Collection c) {
        super(c);
    }
    
    
    /** A constructor that delegates to class <CODE>TreeSet</CODE>. */
    public QuickTreeSet(Comparator c) {
        super(c);
    }
    
    
    /** A constructor that delegates to class <CODE>TreeSet</CODE>. */
    public QuickTreeSet(SortedSet s) {
        super(s);
    }
    
    
    /**
     * <P>Constructor that adds the given array of items one-by-one
     * to the tree set.</P>
     *
     * @param items the array of items to add to this tree set
     * @see #addItems(Object[])
     * @see #QuickTreeSet(Comparator, Object[])
     */
    public QuickTreeSet(Object[] items) {
        addItems(items);
    }
    
    
    /**
     * <P>Constructor that sets the <CODE>Comparator</CODE> and then
     * adds the given array of items one-by-one to the tree set.</P>
     *
     * @param c the comparator
     * @param items the array of items to add to this tree set
     * @see #addItems(Object[])
     * @see #QuickTreeSet(Object[])
     */
    public QuickTreeSet(Comparator c, Object[] items) {
        super(c);
        addItems(items);
    }
    
    /**
     * <P>Adds the element to the set if it is not present.</P>
     *
     * <P>If the element is <CODE>null</CODE>, then simply returns
     * <CODE>false</CODE>.</P>
     * 
     * @param  element the element to be added to the set
     * @return true if the element is non-null and the set did not already
     *         contain the element
     * @see TreeSet#add(Object)
     */
    public boolean add(Object element) {
        if (element == null)
            return false;
        
        return super.add(element);
    }
    
    
    /**
     * <P>Removes the element from the set if it is present.</P>
     *
     * <P>If the element is <CODE>null</CODE>, then simply returns
     * <CODE>false</CODE>.</P>
     * 
     * @param  element the element to be removed from the set
     * @return true if the element is non-null and the set contained the
     *         element
     * @see TreeSet#remove(Object)
     */
    public boolean remove(Object element) {
        if (element == null)
            return false;
        
        return super.remove(element);
    }
    
    
    /**
     * <P>Returns <CODE>true</CODE> if the set contains the element.</P>
     *
     * <P>If the element is <CODE>null</CODE>, then simply returns
     * <CODE>false</CODE>.</P>
     * 
     * @param  element the element to test for membership in the set
     * @return true if the element is non-null and is in the set
     * @see TreeSet#contains(Object)
     */
    public boolean contains(Object element) {
        if (element == null)
            return false;
        
        return super.contains(element);
    }
    
    
    /**
     * <P>Returns a view of the portion of this set whose elements are strictly
     * less than the element. The returned sorted set is backed by this set, so
     * changes in the returned sorted set are reflected in this set, and
     * vice-versa.</P>
     *
     * <P>The sorted set returned by this method will throw an
     * <CODE>IllegalArgumentException</CODE> if the user attempts to insert an
     * element greater than or equal to the given element.</P>
     *
     * <P>If element is <CODE>null</CODE>, then simply returns <CODE>null</CODE>.</P>
     * 
     * @param  element strict upper bound for the elements in the returned set
     * @return the subset of elements strictly less than the given element
     * @see TreeSet#headSet(Object)
     */
    public SortedSet headSet(Object element) {
        if (element == null)
            return null;
        
        return super.headSet(element);
    }
    
    
    /**
     * <P>Returns a view of the portion of this set whose elements are greater
     * than or equal to the element. The returned sorted set is backed by this
     * set, so changes in the returned sorted set are reflected in this set,
     * and vice-versa.</P>
     *
     * <P>The sorted set returned by this method will throw an
     * <CODE>IllegalArgumentException</CODE> if the user attempts to insert an
     * element less than the given element.</P>
     *
     * <P>If element is <CODE>null</CODE>, then simply returns <CODE>null</CODE>.</P>
     * 
     * @param  element lower bound for the elements in the returned set
     * @return the subset of elements greater than or equal to the given element
     * @see TreeSet#tailSet(Object)
     */
    public SortedSet tailSet(Object element) {
        if (element == null)
            return null;
        
        return super.tailSet(element);
    }
    
    
    /**
     * <P>Returns a view of the portion of this set whose elements are greater
     * than or equal to the element lower and strictly less than the element
     * upper. The returned sorted set is backed by this set, so changes in the
     * returned sorted set are reflected in this set, and vice-versa.</P>
     *
     * <P>The sorted set returned by this method will throw an
     * <CODE>IllegalArgumentException</CODE> if the user attempts to insert an
     * element less than lower or greater than or equal to upper.</P>
     *
     * <P>If either lower or upper is <CODE>null</CODE>, then simply returns
     * <CODE>null</CODE>.</P>
     * 
     * @param  lower the lower bound for the elements in the returned set
     * @param  upper the strict upper bound for the elements in the returned set
     * @return the subset of elements greater than or equal to lower and
     *         less than upper
     * @see TreeSet#subSet(Object, Object)
     */
    public SortedSet subSet(Object lower, Object upper) {
        if ((lower == null) || (upper == null))
            return null;
        
        return super.subSet(lower, upper);
    }
    
    
    /**
     * <P>Method that adds the given array of items one-by-one to the tree set.</P>
     *
     * <P>If <CODE>items</CODE> is <CODE>null</CODE>, then does nothing.</P>
     *
     * <P>Ignores individual <CODE>null</CODE> items.</P>
     *
     * @param items the array of items to add to this tree set
     * @see #QuickTreeSet(Object[])
     * @see #QuickTreeSet(Comparator, Object[])
     * @see #setItems(Object[])
     * @see #removeItems(Object[])
     */
    public void addItems(Object[] items) {
        if (items == null)
            return;
        
        int length = items.length;
        
        for (int i = 0; i < length; i++)
            add(items[i]);
    }
    
    
    /**
     * <P>Method that first clears this tree set of any existing items and
     * then adds the given array of items one-by-one to the tree set.</P>
     *
     * <P>If <CODE>items</CODE> is <CODE>null</CODE>, then this method
     * is equivalent to the inherited method <CODE>clear</CODE>.</P>
     *
     * <P>Ignores individual <CODE>null</CODE> items.</P>
     *
     * @param items the array of items to add to this tree set after clearance
     * @see #addItems(Object[])
     * @see #removeItems(Object[])
     */
    public void setItems(Object[] items) {
        clear();
        addItems(items);
    }
    
    
    /**
     * <P>Method that removes the given array of items one-by-one from the
     * tree set.</P>
     *
     * <P>If <CODE>items</CODE> is <CODE>null</CODE>, then does nothing.</P>
     *
     * <P>Ignores individual <CODE>null</CODE> items.</P>
     *
     * @param items the array of items to remove from this tree set
     * @see #addItems(Object[])
     * @see #setItems(Object[])
     */
    public void removeItems(Object[] items) {
        if (items == null)
            return;
        
        int length = items.length;
        
        for (int i = 0; i < length; i++)
            remove(items[i]);
    }
    
}