-
- Type Parameters:
E
- the type of elements maintained by this set
- All Superinterfaces:
java.util.Collection<E>
,java.lang.Iterable<E>
,java.util.NavigableSet<E>
,PCollection<E>
,PSet<E>
,java.util.Set<E>
,java.util.SortedSet<E>
- All Known Implementing Classes:
TreePSet
public interface PSortedSet<E> extends PSet<E>, java.util.NavigableSet<E>
An immutable, persistent set of distinct elements, with elements arranged in sorted order (according to someComparator
), and with various methods to obtain specific elements or ranges of elements based on this ordering (such as the least element greater than some value, or the set of elements between two values).(Note: this is different from
OrderedPSet
, which keeps elements in the order that they were added to the set.)Null values are disallowed unless the subclass specifically supports them; attempts to add a null value will result in
NullPointerException
.Every PSortedSet is a
Set
and more specifically aPSet
, but as with any sorted set, a PSortedSet will only obey the general contract of those interfaces if its comparator is consistent with equals. (SeeSortedSet
for more information.)Every PSortedSet is a
SortedSet
and more specifically aNavigableSet
, but the implementations of PSortedSet provided by this library (pcollections) depart from the specification of those interfaces in a few ways:- headSet(...), subSet(...), and tailSet(...) are specified by SortedSet and NavigableSet to return sets with a "restricted range", and to throw IllegalArgumentException if this instance already has a restricted range and the relevant argument is outside that range. (This ensures that set.headSet(10).headSet(15) doesn't contain elements that set.headSet(10) does not, and that set.headSet(10).headSet(15).add(12) is invalid because 12 can't be added to set.headSet(10).) This library's implementations do not throw IllegalArgumentException, but rather, they ensure that an argument outside the applicable range simply has no effect; so, set.headSet(10).headSet(15) is equivalent to set.headSet(10), because set.headSet(10) already contains no elements ≥ 15. (This is also the behavior of Guava's ImmutableSortedSet. The JDK's Collections.unmodifiableSortedSet(...) and Collections.unmodifiableNavigableSet(...) are agnostic on this point, because they just delegate to the underlying set.) Other implementations are encouraged to consider doing the same, and to document their behavior in this respect. Additionally, any implementations that do use the "restricted range" concept are encouraged to document the behavior of their minus, minusAll, plus, and plusAll methods when a value is outside the restricted range.
- comparator() is specified by SortedSet to return "null if this set uses the natural ordering of its elements". This library's implementations never return null from that method; instead, when the set uses the natural ordering, the method returns a Comparator instance that implements the natural ordering. (This is also the behavior of Guava's ImmutableSortedSet.) Other implementations of PSortedSet are encouraged to consider doing the same, and to document their behavior in this case.
- pollFirst() and pollLast() are specified by NavigableSet to mutate this set, and are not specified to be optional operations. That's obviously not an option for a PSet, so PSortedSet provides default implementations of these methods that simply throw UnsupportedOperationException, which should be the right implementation for any implementation of this interface. (This is also the behavior of the JDK's Collections.unmodifiableNavigableSet(...) and Guava's ImmutableSortedSet.)
- Since:
- 3.2.0
- See Also:
SortedSet
,NavigableSet
,Collections.unmodifiableSortedSet(java.util.SortedSet)
,Collections.unmodifiableNavigableSet(java.util.NavigableSet)
,PSet
,PSortedMap
,TreePSet
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description java.util.Comparator<? super E>
comparator()
PSortedSet<E>
descendingSet()
PSortedSet<E>
headSet(E toElement)
PSortedSet<E>
headSet(E toElement, boolean inclusive)
default PSortedSet<E>
intersect(java.util.Collection<? extends E> list)
PSortedSet<E>
minus(java.lang.Object e)
PSortedSet<E>
minusAll(java.util.Collection<?> list)
PSortedSet<E>
minusFirst()
PSortedSet<E>
minusLast()
PSortedSet<E>
plus(E e)
PSortedSet<E>
plusAll(java.util.Collection<? extends E> list)
default E
pollFirst()
Deprecated.Unsupported operation.default E
pollLast()
Deprecated.Unsupported operation.PSortedSet<E>
subSet(E fromElement, boolean fromInclusive, E toElement, boolean toInclusive)
PSortedSet<E>
subSet(E fromElement, E toElement)
PSortedSet<E>
tailSet(E fromElement)
PSortedSet<E>
tailSet(E fromElement, boolean inclusive)
-
Methods inherited from interface java.util.NavigableSet
ceiling, descendingIterator, floor, higher, iterator, lower
-
Methods inherited from interface org.pcollections.PCollection
add, addAll, clear, remove, removeAll, retainAll
-
-
-
-
Method Detail
-
comparator
java.util.Comparator<? super E> comparator()
- Specified by:
comparator
in interfacejava.util.SortedSet<E>
- Returns:
- The comparator used to order the elements in this set. May be null if this set uses the natural ordering of its elements, though in that case the implementations provided by this library (pcollections) return a Comparator instance that implements the natural ordering.
-
descendingSet
PSortedSet<E> descendingSet()
- Specified by:
descendingSet
in interfacejava.util.NavigableSet<E>
-
headSet
PSortedSet<E> headSet(E toElement)
-
headSet
PSortedSet<E> headSet(E toElement, boolean inclusive)
- Specified by:
headSet
in interfacejava.util.NavigableSet<E>
-
minus
PSortedSet<E> minus(java.lang.Object e)
- Specified by:
minus
in interfacePCollection<E>
- Specified by:
minus
in interfacePSet<E>
- Parameters:
e
-- Returns:
- This set, except with e removed (if e is an element of this set).
- Throws:
java.lang.ClassCastException
- if the type of e is incompatible with this set (optional)java.lang.IllegalArgumentException
- if e is incompatible with this set (optional)
-
minusAll
PSortedSet<E> minusAll(java.util.Collection<?> list)
- Specified by:
minusAll
in interfacePCollection<E>
- Specified by:
minusAll
in interfacePSet<E>
- Parameters:
list
-- Returns:
- This set, except with the elements of list removed (if they are elements of this set).
- Throws:
java.lang.NullPointerException
- if list is null or contains nulljava.lang.ClassCastException
- if list contains an element whose type is incompatible with this set (optional)java.lang.IllegalArgumentException
- if list contains an element that is incompatible with this set (optional)
-
intersect
default PSortedSet<E> intersect(java.util.Collection<? extends E> list)
-
minusFirst
PSortedSet<E> minusFirst()
- Returns:
- This set, except with its first (least) element removed.
- Throws:
java.util.NoSuchElementException
- if this set is empty
-
minusLast
PSortedSet<E> minusLast()
- Returns:
- This set, except with its last (greatest) element removed.
- Throws:
java.util.NoSuchElementException
- if this set is empty
-
plus
PSortedSet<E> plus(E e)
- Specified by:
plus
in interfacePCollection<E>
- Specified by:
plus
in interfacePSet<E>
- Parameters:
e
-- Returns:
- This set, except with e added (unless e is already an element of this set).
- Throws:
java.lang.NullPointerException
- if e is nulljava.lang.IllegalArgumentException
- if e is incompatible with this set (optional)
-
plusAll
PSortedSet<E> plusAll(java.util.Collection<? extends E> list)
- Specified by:
plusAll
in interfacePCollection<E>
- Specified by:
plusAll
in interfacePSet<E>
- Parameters:
list
-- Returns:
- This set, except with the elements of list added (unless they are already elements of this set).
- Throws:
java.lang.NullPointerException
- if list is null or contains nulljava.lang.IllegalArgumentException
- if list contains an element that is incompatible with this set (optional)
-
subSet
PSortedSet<E> subSet(E fromElement, E toElement)
-
subSet
PSortedSet<E> subSet(E fromElement, boolean fromInclusive, E toElement, boolean toInclusive)
- Specified by:
subSet
in interfacejava.util.NavigableSet<E>
-
tailSet
PSortedSet<E> tailSet(E fromElement)
-
tailSet
PSortedSet<E> tailSet(E fromElement, boolean inclusive)
- Specified by:
tailSet
in interfacejava.util.NavigableSet<E>
-
pollFirst
@Deprecated default E pollFirst()
Deprecated.Unsupported operation.- Specified by:
pollFirst
in interfacejava.util.NavigableSet<E>
- Throws:
java.lang.UnsupportedOperationException
- always
-
-