com.jongsoft.lang.collection.Set Maven / Gradle / Ivy
The newest version!
/*
* The MIT License
*
* Copyright 2016-2019 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.Comparator;
import java.util.NoSuchElementException;
import java.util.Objects;
import java.util.function.Function;
import java.util.function.Predicate;
import java.util.function.Supplier;
/**
* 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 com.jongsoft.lang.Collections#Set(Object[])}, an implementation that uses the entities hash
* - {@link com.jongsoft.lang.Collections#SortedSet()}, a set where all elements are sorted based on a {@link java.util.Comparator}
*
*
* Single change operations
*
* Operation Description {@linkplain #append(Object)} Add element to end of the sequence {@linkplain #remove(int)} Remove an element by its index
*
* Collection based operations
*
* Operation Description
* {@linkplain #complement(Iterable)}
* {@linkplain #complement(Iterable[])}
* Creates a set with elements only contained in this
* {@linkplain #intersect(Iterable)}
* {@linkplain #intersect(Iterable[])}
* Creates a set containing elements that are both in this and the provided iterables {@linkplain #map(Function)} Create a new sequence with the mapped values {@linkplain #filter(Predicate)} Create a new set with values matching the predicate {@linkplain #reject(Predicate)} Create a new sequence without the rejected values matching the
* predicate {@linkplain #union(Iterable)} Combine this sequence of elements with the provided iterable
*
* @param the entity type contained in the set
* @since 0.0.3
*/
public interface Set extends List {
@Override
Set append(T value);
@Override
Set distinctBy(Comparator comparator);
/**
* 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);
@Override
Set filter(Predicate predicate);
@Override
default T head() {
if (size() > 0) {
return get(0);
}
throw new NoSuchElementException("Cannot get head on empty collection");
}
/**
* 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);
@Override
Set map(Function mapper);
@Override
Set orElse(Iterable other);
@Override
Set orElse(Supplier> supplier);
@Override
default Set reject(Predicate predicate) {
Objects.requireNonNull(predicate, "predicate is null");
return filter(predicate.negate());
}
@Override
Set remove(int index);
@Override
Set replace(int index, T replacement);
@Override
Set replaceIf(Predicate predicate, T replacement);
@Override
Set tail();
/**
* Transform this collection into one supported natively in Java.
*
* @return the native java collection
*/
java.util.Set toJava();
@Override
Set union(Iterable iterable);
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy