Interface PSortedSet<E>

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

public interface PSortedSet<E> extends PSet<E>, NavigableSet<E>
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: