org.dishevelled.venn.VennModel Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of dsh-venn Show documentation
Lightweight components for venn diagrams.
There is a newer version: 1.2
/*

    dsh-venn  Lightweight components for venn diagrams.
    Copyright (c) 2009-2013 held jointly by the individual authors.

    This library is free software; you can redistribute it and/or modify it
    under the terms of the GNU Lesser General Public License as published
    by the Free Software Foundation; either version 3 of the License, or (at
    your option) any later version.

    This library is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; with out even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
    License for more details.

    You should have received a copy of the GNU Lesser General Public License
    along with this library;  if not, write to the Free Software Foundation,
    Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA.

    > http://www.fsf.org/licensing/licenses/lgpl.html
    > http://www.opensource.org/licenses/lgpl-license.php

*/
package org.dishevelled.venn;

import java.util.Set;

/**
 * Venn diagram model.
 *
 * @param  value type
 * @author  Michael Heuer
 */
public interface VennModel
{

    /**
     * Return the number of sets in this venn model.
     *
     * @return the number of sets in this venn model
     */
    int size();

    /**
     * Return the set at the specified index in this venn model.
     *
     * @param index index
     * @return the set at the specified index in this venn model
     * @throws IndexOutOfBoundsException if index is out of bounds
     */
    Set get(int index);

    /**
     * Return an immutable set view of the union of the sets in this venn model.
     *
     * @return an immutable set view of the union of the sets in this venn model
     */
    Set union();

    /**
     * Return an immutable set view of the intersection of the sets in this venn model.
     *
     * @return an immutable set view of the intersection of the sets in this venn model
     */
    Set intersection();

    /**
     * Return an immutable set view of the elements exclusive to the sets in this venn model
     * identified by the specified indices.  For example, for n = 3
     *      * VennModel<String> vennModel = ...;
     * Set<String> first = vennModel.get(0);
     * Set<String> second = vennModel.get(1);
     * Set<String> third = vennModel.get(2);
     * Set<String> firstOnly = vennModel.exclusiveTo(0);
     * Set<String> firstSecond = vennModel.exclusiveTo(0, 1);
     * Set<String> intersection = vennModel.exclusiveTo(0, 1, 2);
     * 
     * 
     * This is equivalent to the difference of the intersection of the sets in this venn model
     * identified by the specified indices and the union of the remainder sets in this venn model.
     * 
     *
     * @param index first index
     * @param additional variable number of additional indices, if any
     * @return an immutable set view of the elements exclusive to the sets in this venn model
     *    identified by the specified indices
     * @throws IndexOutOfBoundsException if index or any of additional
     *    are out of bounds, or if too many indices are specified
     */
    Set exclusiveTo(int index, int... additional);
}