javaslang.collection.Set Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of javaslang Show documentation
Javaslang is a Java standard library extension built for Java 8 and above.
The newest version!
/*     / \____  _    _  ____   ______  / \ ____  __    _______
 *    /  /    \/ \  / \/    \ /  /\__\/  //    \/  \  //  /\__\   JΛVΛSLΛNG
 *  _/  /  /\  \  \/  /  /\  \\__\\  \  //  /\  \ /\\/ \ /__\ \   Copyright 2014-2016 Javaslang, http://javaslang.io
 * /___/\_/  \_/\____/\_/  \_/\__\/__/\__\_/  \_//  \__/\_____/   Licensed under the Apache License, Version 2.0
 */
package javaslang.collection;

import javaslang.Function1;
import javaslang.Tuple2;
import javaslang.Tuple3;
import javaslang.control.Option;

import java.util.Comparator;
import java.util.Spliterator;
import java.util.Spliterators;
import java.util.function.BiFunction;
import java.util.function.Consumer;
import java.util.function.Function;
import java.util.function.Predicate;

/**
 * An immutable {@code Set} interface.
 * 
 * CAUTION: The Javaslang {@code Set} implementations generally support {@code null} elements. However {@code SortedSet}
 * implementations require an element {@code Comparator}, which may not support {@code null} elements.
 * 

 * Examples:
 *
 * 
{@code Set addNull(Set set) {
 *
 *     // CAUTION: Do not expect a Set to accept null values in general!
 *     return set.add(null);
 *
 * }
 *
 * void test() {
 *
 *     // ok
 *     addNull(HashSet.of(1));
 *
 *     // ok
 *     addNull(TreeSet.of(nullsFirst(naturalOrder()), 1));
 *
 *     // ok
 *     addNull(TreeSet.empty());
 *
 *     // throws NPE!
 *     addNull(TreeSet.of(1));
 *
 * }}
 *
 * 
 * Basic operations:
 *
 * 

 * {@link #add(Object)}
 * {@link #addAll(Iterable)}
 * {@link #diff(Set)}
 * {@link #intersect(Set)}
 * {@link #remove(Object)}
 * {@link #removeAll(Iterable)}
 * {@link #union(Set)}
 * 
 *
 * Conversion:
 *
 * 
 * {@link #toJavaSet()}
 * 
 *
 * @param  Component type
 * @author Daniel Dietrich, Ruslan Sennov
 * @since 2.0.0
 */
public interface Set extends Traversable, Function1 {

    long serialVersionUID = 1L;

    /**
     * Narrows a widened {@code Set} to {@code Set}
     * by performing a type-safe cast. This is eligible because immutable/read-only
     * collections are covariant.
     *
     * @param set A {@code Set}.
     * @param  Component type of the {@code Set}.
     * @return the given {@code set} instance as narrowed type {@code Set}.
     */
    @SuppressWarnings("unchecked")
    static  Set narrow(Set set) {
        return (Set) set;
    }

    /**
     * Add the given element to this set, if it is not already contained.
     *
     * @param element The element to be added.
     * @return A new set containing all elements of this set and also {@code element}.
     */
    Set add(T element);

    /**
     * Adds all of the given elements to this set, if not already contained.
     *
     * @param elements The elements to be added.
     * @return A new set containing all elements of this set and the given {@code elements}, if not already contained.
     */
    Set addAll(Iterable elements);

    /**
     * Tests if a given {@code element} is contained in this {@code Set}.
     * 
     * This method is equivalent to {@link #contains(Object)}.
     *
     * @param element the element to test for membership.
     * @return {@code true} if the given {@code element} is contained, {@code false} otherwise.
     */
    @Override
    default Boolean apply(T element) {
        return contains(element);
    }

    /**
     * Calculates the difference between this set and another set.
     * 

     * See also {@link #removeAll(Iterable)}.
     *
     * @param that Elements to be removed from this set.
     * @return A new Set containing all elements of this set which are not located in {@code that} set.
     */
    Set diff(Set that);

    /**
     * Computes the intersection between this set and another set.
     * 

     * See also {@link #retainAll(Iterable)}.
     *
     * @param that the set to intersect with.
     * @return A new Set consisting of all elements that are both in this set and in the given set {@code that}.
     */
    Set intersect(Set that);

    /**
     * Removes a specific element from this set, if present.
     *
     * @param element The element to be removed from this set.
     * @return A new set consisting of the elements of this set, without the given {@code element}.
     */
    Set remove(T element);

    /**
     * Removes all of the given elements from this set, if present.
     *
     * @param elements The elements to be removed from this set.
     * @return A new set consisting of the elements of this set, without the given {@code elements}.
     */
    Set removeAll(Iterable elements);

    /**
     * Converts this Javaslang {@code Set} to a {@code java.util.Set} while preserving characteristics
     * like insertion order ({@code LinkedHashSet}) and sort order ({@code SortedSet}).
     *
     * @return a new {@code java.util.Set} instance
     */
    @Override
    java.util.Set toJavaSet();

    /**
     * Adds all of the elements of {@code that} set to this set, if not already present.
     * 
     * See also {@link #addAll(Iterable)}.
     *
     * @param that The set to form the union with.
     * @return A new set that contains all distinct elements of this and {@code that} set.
     */
    Set union(Set that);

    // -- Adjusted return types of Traversable methods

    @Override
    boolean contains(T element);

    @Override
    Set distinct();

    @Override
    Set distinctBy(Comparator comparator);

    @Override
     Set distinctBy(Function keyExtractor);

    @Override
    Set drop(int n);

    @Override
    Set dropRight(int n);

    @Override
    Set dropUntil(Predicate predicate);

    @Override
    Set dropWhile(Predicate predicate);

    @Override
    Set filter(Predicate predicate);

    @Override
     Set flatMap(Function> mapper);

    @Override
     Map> groupBy(Function classifier);

    @Override
    Iterator> grouped(int size);

    @Override
    Set init();

    @Override
    Option> initOption();

    @Override
    default boolean isDistinct() {
        return true;
    }

    @Override
    Iterator iterator();

    @Override
    int length();

    @Override
     Set map(Function mapper);

    @Override
    Tuple2, ? extends Set> partition(Predicate predicate);

    @Override
    Set peek(Consumer action);

    @Override
    Set replace(T currentElement, T newElement);

    @Override
    Set replaceAll(T currentElement, T newElement);

    @Override
    Set retainAll(Iterable elements);

    @Override
    Set scan(T zero, BiFunction operation);

    @Override
     Set scanLeft(U zero, BiFunction operation);

    @Override
     Set scanRight(U zero, BiFunction operation);

    @Override
    Iterator> sliding(int size);

    @Override
    Iterator> sliding(int size, int step);

    @Override
    Tuple2, ? extends Set> span(Predicate predicate);

    @Override
    default Spliterator spliterator() {
        return Spliterators.spliterator(iterator(), length(), Spliterator.ORDERED | Spliterator.IMMUTABLE);
    }

    @Override
    Set tail();

    @Override
    Option> tailOption();

    @Override
    Set take(int n);

    @Override
    Set takeRight(int n);

    @Override
    Set takeUntil(Predicate predicate);

    @Override
    Set takeWhile(Predicate predicate);

    @Override
     Tuple2, ? extends Set> unzip(Function> unzipper);

    @Override
     Tuple3, ? extends Set, ? extends Set> unzip3(Function> unzipper);

    @Override
     Set> zip(Iterable that);

    @Override
     Set zipWith(Iterable that, BiFunction mapper);

    @Override
     Set> zipAll(Iterable that, T thisElem, U thatElem);

    @Override
    Set> zipWithIndex();

    @Override
     Set zipWithIndex(BiFunction mapper);
}