IMMUTABLE_TREE_R0: ImmSet.java

package org.sophie2.base.commons.util;

import java.util.Comparator;
import java.util.Set;

/**
 * Interface that provides necessary functionality for immutable set
 * 
 * @author stefan
 * 
 * @param <E>
 *                      Elements type parameter.
 */
public interface ImmSet<E> extends ImmCollection<E>{
        /**
         * Puts element in the set.
         * 
         * @param element
         * @return A new {@link ImmSet} that includes the element argument, if it
         *         doesn't already contains it.
         */
        ImmSet<E> put(E element);

        /**
         * Checks if this <code>ImmList</code> contains the passed
         * <var>element</var>.
         * 
         * @param element
         * @return True if this <code>ImmList</code> contains the element false
         *         otherwise.
         */
        boolean contains(E element);

        /**
         * Removes element from the set.
         * 
         * @param element
         * @return A new {@link ImmSet} that excludes the element argument, if it
         *         does already contains it.
         */
    ImmSet<E> remove(E element);

        /**
         * Get {@link Set} from the <code>ImmCollection</code>.
         * 
         * @return A {@link Set} view of the current <code>ImmCollection</code>.
         */
        Set<E> asSet();
        
        /**
         * Gives sub {@link ImmSet} of the current <code>ImmSet</code> (including)
         * <var>begin</var> element and (excluding) <var>end</var> element.
         * 
         * @param begin
         * @param end
         * @return new {@link ImmSet} containing elements in the given range.
         */
        ImmSet<E> subSet(E begin, E end);

        /**
         * Gets the {@link Comparator} used to arrange elements in the set.
         * 
         * @return {@link Comparator}.
         */
        Comparator<E> getComparator();
}