com.jongsoft.lang.collection.Set Maven / Gradle / Ivy

Go to download
/*
 * The MIT License
 *
 * Copyright 2016-2018 Jong Soft.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
package com.jongsoft.lang.collection;

import java.util.NoSuchElementException;
import java.util.Objects;
import java.util.function.Function;
import java.util.function.Predicate;

import com.jongsoft.lang.API;

/**
 * The set is an extension of the {@link Collection} interface that guarantees only unique elements are contained within the set.
 * How uniqueness is guaranteed varies pending the implementing class.
 *
 * Currently the following implementations are supported:
 * 
 *     {@link API#Set(Object[])}, an implementation that uses the entities hash
 *     {@link API#SortedSet()}, a set where all elements are sorted based on a {@link java.util.Comparator}
 * 
 *
 * @param  the entity type contained in the set
 * @since 0.0.3
 */
public interface Set extends List {

    @Override
    Set append(T value);

    @Override
    Set remove(int index);

    @Override
    default T head() {
        if (size() > 0) {
            return get(0);
        }

        throw new NoSuchElementException("Cannot get head on empty collection");
    }

    @Override
    Set tail();

    @Override
    Set filter(Predicate predicate);

    @Override
    default Set reject(Predicate predicate) {
        Objects.requireNonNull(predicate, "predicate is null");
        return filter(predicate.negate());
    }

    @Override
     Set map(Function mapper);

    /**
     * Transform this collection into one supported natively in Java.
     *
     * @return the native java collection
     */
    java.util.Set toJava();

    /**
     * Create a set that contains all elements that are contained in both {@code this} and the provided {@code iterable}.
     *
     * 
     * The union of two sets A and B is the set of elements which are in A, in B, or in both A and B, but not containing duplicate
     * elements.
     * 
     *
     * Example:
     * {@code  // the example would be a Set(1, 2, 3, 4)
     *   Set result = Set(1, 2, 3).union(Set(3, 4));
     * }
     *
     * @param iterable  the iterable to perform the union with
     * @return  the product of the union operation
     */
    Set union(Iterable iterable);

    /**
     * Creates a set that contains only the elements that are in both {@code this} and the provided {@code iterable}.
     *
     * Example:
     * {@code  // the example would be a Set(3)
     *   Set result = Set(1, 2, 3).intersect(Set(3, 4));
     * }
     *
     * @param iterable  the iterable to perform the intersects with
     * @return  the product of the intersect operation
     */
    @SuppressWarnings("unchecked")
    default Set intersect(Iterable iterable) {
        return intersect(new Iterable[] {iterable});
    }

    /**
     * Creates a set that contains only the elements that are in all collections and {@code this}.
     *
     * 
     * We say that A intersects (meets) B at an element x if x belongs to A and B. We say that A intersects (meets) B
     * if A intersects B at some element. A intersects B if their intersection is inhabited.
     * 
     *
     * Example:
     * {@code  // the example would be a Set(3)
     *   Set result = Set(1, 2, 3).intersect(Set(3, 4));
     * }
     *
     * @param iterables the set of iterables the intersection should be calculated on
     * @return the product of the intersect operation
     */
    Set intersect(Iterable...iterables);

    /**
     * Creates a new set that contains elements that are only in {@code this}, but not contained within {@code iterable}.
     *
     * Example:
     * {@code  // the example would be a Set(1, 2)
     *   Set result = Set(1, 2, 3).complement(Set(3, 4));
     * }
     *
     * @param iterable  the iterable to perform the complement with
     * @return  the product of the complement operation
     */
    @SuppressWarnings("unchecked")
    default Set complement(Iterable iterable) {
        return complement(new Iterable[] {iterable});
    }

    /**
     * Creates a new set that contains elements that are only in {@code this}, but not contained within any of the {@code iterables}.
     *
     * Example:
     * {@code  // the example would be a Set(1, 2)
     *   Set result = Set(1, 2, 3).complement(Set(3, 4));
     * }
     *
     * @param iterables  the iterables to perform the complement with
     * @return  the product of the complement operation
     */
    Set complement(Iterable...iterables);

}