VCollections.src.org.violetlib.collections.ISet Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of vcollections Show documentation
Show all versions of vcollections Show documentation
Java Immutable Collections
The newest version!
/*
* Copyright (c) 2023 Alan Snyder.
* All rights reserved.
*
* You may not use, copy or modify this file, except in compliance with the license agreement. For details see
* accompanying license terms.
*/
package org.violetlib.collections;
import java.util.Comparator;
import java.util.Iterator;
import java.util.NoSuchElementException;
import java.util.function.Function;
import java.util.function.Predicate;
import javax.annotation.CheckReturnValue;
import org.violetlib.collections.impl.Impl;
import org.violetlib.types.Option;
import org.jetbrains.annotations.*;
import org.violetlib.annotations.Immutable;
/**
An immutable set of elements. Null elements are not permitted. The iteration order may be unspecified.
@param The type of the values.
*/
public @Immutable @CheckReturnValue interface ISet
extends ICollection, IIterable
{
@NotNull Option ORDERED = Option.named("Ordered Set");
/**
Return an empty set.
*/
static @NotNull ISet empty()
{
return Impl.getEmptySet();
}
/**
Create a set containing the specified elements.
@param elements An iterator that provides the elements.
@return the set.
@throws IllegalArgumentException if the iterator returns a null value.
*/
static @NotNull ISet create(@NotNull Iterable elements)
throws IllegalArgumentException
{
return Impl.createSet(elements);
}
/**
Create a set containing the specified elements.
@param elements An array that provides the elements.
@return the set.
@throws IllegalArgumentException if the array contains a null value.
*/
static @NotNull ISet create(@NotNull V[] elements)
throws IllegalArgumentException
{
return Impl.setOf(elements);
}
static @NotNull ISet of(@NotNull V e)
{
return Impl.setOf(e);
}
@SafeVarargs
static @NotNull ISet of(V... es)
{
return Impl.setOf(es);
}
/**
Create a builder for a set. The iteration order of the set is unspecified.
@param The type of set elements.
@return the builder.
*/
static @NotNull SetBuilder builder()
{
return Impl.getSetBuilder();
}
/**
Create a builder for a set whose iteration order is defined by the order in which elements are added to the
builder.
@return the builder.
@param The type of set elements.
@param option
*/
static @NotNull SetBuilder builder(Option option)
{
return option == ORDERED ? Impl.getOrderedSetBuilder() : Impl.getSetBuilder();
}
/**
Cast a set to a specific type. This method is no more reliable than an explicit type cast, but it prevents the
warning.
*/
static @NotNull ISet cast(@NotNull ISet o)
{
@SuppressWarnings("unchecked")
ISet result = (ISet) o;
return result;
}
@Override
default boolean isEmpty()
{
return size() == 0;
}
@Override
int size();
@Override
default boolean contains(@NotNull Object target)
{
return find(e -> e.equals(target) ? true : null, false);
}
/**
Return one element of this set.
@throws NoSuchElementException if the set is empty.
*/
default @NotNull V choose()
throws NoSuchElementException
{
Iterator it = iterator();
return it.next();
}
/**
Return one element of this set, or null if the set is empty.
*/
default @Nullable V chooseOptional()
{
if (isEmpty()) {
return null;
}
Iterator it = iterator();
return it.next();
}
/**
Return the sole element of this set.
@throws NoSuchElementException if the set does not contain exactly one element.
*/
default @NotNull V element()
throws NoSuchElementException
{
Iterator it = iterator();
V element = it.next();
if (it.hasNext()) {
throw new NoSuchElementException();
}
return element;
}
/**
Return a set containing the members of this set and the specified value.
@param value The value to be included in the result.
@return A set containing the values from this set and the specified value.
*/
@NotNull ISet extending(@NotNull V value);
/**
Return a set containing the members of this set and the specified values.
@param values The values to be included in the result.
@return A set containing the values from this set and the specified values.
*/
@NotNull ISet extendingAll(@NotNull ICollection values);
/**
Return a set containing the members of this set excluding the specified value.
@param value The value to be excluded from the result.
@return A set containing the values from this set, but not the specified value.
*/
@NotNull ISet removing(@NotNull Object value);
default @NotNull ISet removingAll(@NotNull ISet values)
{
ISet result = this;
for (Object value : values) {
result = result.removing(value);
}
return result;
}
default @NotNull ISet filter(@NotNull Predicate predicate)
{
SetBuilder b = ISet.builder();
for (V v : this) {
if (predicate.test(v)) {
b.add(v);
}
}
return b.values();
}
@NotNull ISet map(@NotNull Function mapper);
/**
Return a set containing the members of this collection whose iteration order is defined by the natural sort order.
*/
default @NotNull ISet ordered()
{
IList elements = sort();
SetBuilder b = ISet.builder(ISet.ORDERED);
b.addAll(elements);
return b.values();
}
/**
Return a set containing the members of this collection whose iteration order is defined by the specified comparator.
*/
default @NotNull ISet ordered(@NotNull Comparator comp)
{
IList elements = sort(comp);
SetBuilder b = ISet.builder(ISet.ORDERED);
b.addAll(elements);
return b.values();
}
default @NotNull ISet intersecting(@NotNull ISet other)
{
return intersection(this, other);
}
static @NotNull ISet intersection(@NotNull ISet s, @NotNull ISet p)
{
boolean isChanged = false;
SetBuilder b = ISet.builder();
for (V v : s) {
if (p.contains(v)) {
b.add(v);
} else {
isChanged = true;
}
}
return isChanged ? b.values() : s;
}
}