- Type Parameters:
E
- the type of elements maintained by this set
- All Superinterfaces:
Collection<E>
,Iterable<E>
,NavigableSet<E>
,PCollection<E>
,PSet<E>
,Set<E>
,SortedSet<E>
- All Known Implementing Classes:
TreePSet
An immutable, persistent set of distinct elements, with elements arranged in sorted order
(according to some
Comparator
), 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 a PSet
, but as with
any sorted set, a PSortedSet will only obey the general contract of those interfaces if its
comparator is consistent with equals. (See SortedSet
for more information.)
Every PSortedSet is a SortedSet
and more specifically a NavigableSet
, 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:
-
Method Summary
Modifier and TypeMethodDescriptionComparator
<? super E> default PSortedSet
<E> intersect
(Collection<? extends E> list) minusAll
(Collection<?> list) plusAll
(Collection<? extends E> list) default E
Deprecated.Unsupported operation.default E
pollLast()
Deprecated.Unsupported operation.Methods inherited from interface java.util.Collection
parallelStream, removeIf, stream, toArray
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
Methods inherited from interface java.util.Set
add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, remove, removeAll, retainAll, size, toArray, toArray
Methods inherited from interface java.util.SortedSet
first, last, spliterator
-
Method Details
-
comparator
Comparator<? super E> comparator()- Specified by:
comparator
in interfaceSortedSet<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 interfaceNavigableSet<E>
-
headSet
-
headSet
- Specified by:
headSet
in interfaceNavigableSet<E>
-
minus
- 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:
ClassCastException
- if the type of e is incompatible with this set (optional)IllegalArgumentException
- if e is incompatible with this set (optional)
-
minusAll
- 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:
NullPointerException
- if list is null or contains nullClassCastException
- if list contains an element whose type is incompatible with this set (optional)IllegalArgumentException
- if list contains an element that is incompatible with this set (optional)
-
intersect
-
minusFirst
PSortedSet<E> minusFirst()- Returns:
- This set, except with its first (least) element removed.
- Throws:
NoSuchElementException
- if this set is empty
-
minusLast
PSortedSet<E> minusLast()- Returns:
- This set, except with its last (greatest) element removed.
- Throws:
NoSuchElementException
- if this set is empty
-
plus
- 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:
NullPointerException
- if e is nullIllegalArgumentException
- if e is incompatible with this set (optional)
-
plusAll
- 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:
NullPointerException
- if list is null or contains nullIllegalArgumentException
- if list contains an element that is incompatible with this set (optional)
-
subSet
-
subSet
- Specified by:
subSet
in interfaceNavigableSet<E>
-
tailSet
-
tailSet
- Specified by:
tailSet
in interfaceNavigableSet<E>
-
pollFirst
Deprecated.Unsupported operation.- Specified by:
pollFirst
in interfaceNavigableSet<E>
- Throws:
UnsupportedOperationException
- always
-
pollLast
Deprecated.Unsupported operation.- Specified by:
pollLast
in interfaceNavigableSet<E>
- Throws:
UnsupportedOperationException
- always
-