PCollections 4.0.2 · org.pcollections.PSortedSet · APIdia, the JavaDoc alternative

An immutable, persistent set of distinct elements, with elements arranged in sorted order (according to some java.util.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 java.util.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 java.util.SortedSet for more information.)

Every PSortedSet is a java.util.SortedSet and more specifically a java.util.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.)

Method Summary

Modifier and Type	Method and Description
public Comparator<? super 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. comparator() Redeclares java.util.SortedSet.comparator. Returns the comparator used to order the elements in this set, or `null` if this set uses the natural ordering of its elements.
public PSortedSet<E>	descendingSet() Redeclares java.util.NavigableSet.descendingSet. Returns a reverse order view of the elements contained in this set.
public PSortedSet<E>	headSet(E high endpoint (exclusive) of the returned set toElement) Redeclares java.util.NavigableSet.headSet. Returns a view of the portion of this set whose elements are strictly less than `toElement`.
public PSortedSet<E>	headSet(E high endpoint of the returned set toElement, boolean `true` if the high endpoint is to be included in the returned view inclusive) Redeclares java.util.NavigableSet.headSet. Returns a view of the portion of this set whose elements are less than (or equal to, if `inclusive` is true) `toElement`.
public default PSortedSet<E>	intersect(Collection<? extends E> list) Overrides default org.pcollections.PSet.intersect.
public PSortedSet<E>	Returns: This set, except with e removed (if e is an element of this set). minus(Object e) Redeclares org.pcollections.PSet.minus.
public PSortedSet<E>	Returns: This set, except with the elements of list removed (if they are elements of this set). minusAll(Collection<?> list) Redeclares org.pcollections.PSet.minusAll.
public PSortedSet<E>	Returns: This set, except with its first (least) element removed. minusFirst()
public PSortedSet<E>	Returns: This set, except with its last (greatest) element removed. minusLast()
public PSortedSet<E>	Returns: This set, except with e added (unless e is already an element of this set). plus(E e) Redeclares org.pcollections.PSet.plus.
public PSortedSet<E>	Returns: This set, except with the elements of list added (unless they are already elements of this set). plusAll(Collection<? extends E> list) Redeclares org.pcollections.PSet.plusAll.
public default E	pollFirst() Implements java.util.NavigableSet.pollFirst. Deprecated Unsupported operation. Retrieves and removes the first (lowest) element, or returns `null` if this set is empty (optional operation).
public default E	pollLast() Implements java.util.NavigableSet.pollLast. Deprecated Unsupported operation. Retrieves and removes the last (highest) element, or returns `null` if this set is empty (optional operation).
public PSortedSet<E>	subSet(E low endpoint (inclusive) of the returned set fromElement, E high endpoint (exclusive) of the returned set toElement) Redeclares java.util.NavigableSet.subSet. Returns a view of the portion of this set whose elements range from `fromElement`, inclusive, to `toElement`, exclusive.
public PSortedSet<E>	subSet(E low endpoint of the returned set fromElement, boolean `true` if the low endpoint is to be included in the returned view fromInclusive, E high endpoint of the returned set toElement, boolean `true` if the high endpoint is to be included in the returned view toInclusive) Redeclares java.util.NavigableSet.subSet. Returns a view of the portion of this set whose elements range from `fromElement` to `toElement`.
public PSortedSet<E>	tailSet(E low endpoint (inclusive) of the returned set fromElement) Redeclares java.util.NavigableSet.tailSet. Returns a view of the portion of this set whose elements are greater than or equal to `fromElement`.
public PSortedSet<E>	tailSet(E low endpoint of the returned set fromElement, boolean `true` if the low endpoint is to be included in the returned view inclusive) Redeclares java.util.NavigableSet.tailSet. Returns a view of the portion of this set whose elements are greater than (or equal to, if `inclusive` is true) `fromElement`.

Inherited from java.util.NavigableSet:: ceiling descendingIterator floor higher iterator lower removeFirst removeLast reversed

Method Detail

comparator back to summary

comparator	back to summary
public Comparator<? super E> comparator() Redeclares java.util.SortedSet.comparator. Doc from java.util.SortedSet.comparator. Returns the comparator used to order the elements in this set, or `null` if this set uses the natural ordering of its elements. Returns:Comparator<? super E> 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. Annotations @Override

public Comparator<? super E> comparator()

Redeclares java.util.SortedSet.comparator.

Doc from java.util.SortedSet.comparator.

Returns the comparator used to order the elements in this set, or null if this set uses the natural ordering of its elements.

Returns:Comparator<? super E>

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.

Annotations

@Override

descendingSet back to summary

descendingSet	back to summary
public PSortedSet<E> descendingSet() Redeclares java.util.NavigableSet.descendingSet. Doc from java.util.NavigableSet.descendingSet. Returns a reverse order view of the elements contained in this set. The descending set is backed by this set, so changes to the set are reflected in the descending set, and vice-versa. If either set is modified while an iteration over either set is in progress (except through the iterator's own `remove` operation), the results of the iteration are undefined. The returned set has an ordering equivalent to `Collections.reverseOrder(comparator())`. The expression `s.descendingSet().descendingSet()` returns a view of `s` essentially equivalent to `s`. Returns:PSortedSet<E> a reverse order view of this set Annotations @Override

public PSortedSet<E> descendingSet()

Redeclares java.util.NavigableSet.descendingSet.

Doc from java.util.NavigableSet.descendingSet.

Returns a reverse order view of the elements contained in this set. The descending set is backed by this set, so changes to the set are reflected in the descending set, and vice-versa. If either set is modified while an iteration over either set is in progress (except through the iterator's own remove operation), the results of the iteration are undefined.

The returned set has an ordering equivalent to Collections.reverseOrder(comparator()). The expression s.descendingSet().descendingSet() returns a view of s essentially equivalent to s.

Returns:PSortedSet<E>

a reverse order view of this set

Annotations

@Override

headSet back to summary

headSet	back to summary
public PSortedSet<E> headSet(E toElement) Redeclares java.util.NavigableSet.headSet. Doc from java.util.NavigableSet.headSet. Returns a view of the portion of this set whose elements are strictly less than `toElement`. The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports. The returned set will throw an `IllegalArgumentException` on an attempt to insert an element outside its range. Equivalent to `headSet(toElement, false)`. Parameters toElement:E Doc from java.util.SortedSet.headSet. high endpoint (exclusive) of the returned set Returns:PSortedSet<E> Doc from java.util.SortedSet.headSet. a view of the portion of this set whose elements are strictly less than `toElement` Annotations @Override

public PSortedSet<E> headSet(E toElement)

Redeclares java.util.NavigableSet.headSet.

Doc from java.util.NavigableSet.headSet.

Returns a view of the portion of this set whose elements are strictly less than toElement. The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports.

The returned set will throw an IllegalArgumentException on an attempt to insert an element outside its range.

Equivalent to headSet(toElement, false).

Parameters

toElement:E

Doc from java.util.SortedSet.headSet.

high endpoint (exclusive) of the returned set

Returns:PSortedSet<E>

Doc from java.util.SortedSet.headSet.

a view of the portion of this set whose elements are strictly less than toElement

Annotations

@Override

headSet back to summary

headSet	back to summary
public PSortedSet<E> headSet(E toElement, boolean inclusive) Redeclares java.util.NavigableSet.headSet. Doc from java.util.NavigableSet.headSet. Returns a view of the portion of this set whose elements are less than (or equal to, if `inclusive` is true) `toElement`. The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports. The returned set will throw an `IllegalArgumentException` on an attempt to insert an element outside its range. Parameters toElement:E high endpoint of the returned set inclusive:boolean `true` if the high endpoint is to be included in the returned view Returns:PSortedSet<E> a view of the portion of this set whose elements are less than (or equal to, if `inclusive` is true) `toElement` Annotations @Override

public PSortedSet<E> headSet(E toElement, boolean inclusive)

Redeclares java.util.NavigableSet.headSet.

Doc from java.util.NavigableSet.headSet.

Returns a view of the portion of this set whose elements are less than (or equal to, if inclusive is true) toElement. The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports.

The returned set will throw an IllegalArgumentException on an attempt to insert an element outside its range.

Parameters

toElement:E: high endpoint of the returned set
inclusive:boolean: true if the high endpoint is to be included in the returned view

Returns:PSortedSet<E>

a view of the portion of this set whose elements are less than (or equal to, if inclusive is true) toElement

Annotations

@Override

intersect back to summary

intersect	back to summary
public default PSortedSet<E> intersect(Collection<? extends E> list) Overrides default org.pcollections.PSet.intersect. Returns:PSortedSet<E> Doc from org.pcollections.PSet.intersect. the equivalent of `this.minusAll(this.minusAll(list))`. Annotations @Override

public default PSortedSet<E> intersect(Collection<? extends E> list)

Overrides default org.pcollections.PSet.intersect.

Returns:PSortedSet<E>

Doc from org.pcollections.PSet.intersect.

the equivalent of this.minusAll(this.minusAll(list)).

Annotations

@Override

minus	back to summary
public PSortedSet<E> minus(Object e) Redeclares org.pcollections.PSet.minus. Returns:PSortedSet<E> This set, except with e removed (if e is an element of this set). Annotations @Override Exceptions ClassCastException: if the type of e is incompatible with this set (optional) IllegalArgumentException: if e is incompatible with this set (optional)

minus

back to summary

public PSortedSet<E> minus(Object e)

Redeclares org.pcollections.PSet.minus.

Returns:PSortedSet<E>

This set, except with e removed (if e is an element of this set).

Annotations

@Override

Exceptions

ClassCastException:: if the type of e is incompatible with this set (optional)
IllegalArgumentException:: if e is incompatible with this set (optional)

minusAll	back to summary
public PSortedSet<E> minusAll(Collection<?> list) Redeclares org.pcollections.PSet.minusAll. Returns:PSortedSet<E> This set, except with the elements of list removed (if they are elements of this set). Annotations @Override Exceptions NullPointerException: if list is null or contains null ClassCastException: 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)

minusAll

back to summary

public PSortedSet<E> minusAll(Collection<?> list)

Redeclares org.pcollections.PSet.minusAll.

Returns:PSortedSet<E>

This set, except with the elements of list removed (if they are elements of this set).

Annotations

@Override

Exceptions

NullPointerException:: if list is null or contains null
ClassCastException:: 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)

minusFirst	back to summary
public PSortedSet<E> minusFirst() Returns:PSortedSet<E> This set, except with its first (least) element removed. Exceptions NoSuchElementException: if this set is empty

minusLast	back to summary
public PSortedSet<E> minusLast() Returns:PSortedSet<E> This set, except with its last (greatest) element removed. Exceptions NoSuchElementException: if this set is empty

plus	back to summary
public PSortedSet<E> plus(E e) Redeclares org.pcollections.PSet.plus. Returns:PSortedSet<E> This set, except with e added (unless e is already an element of this set). Annotations @Override Exceptions NullPointerException: if e is null IllegalArgumentException: if e is incompatible with this set (optional)

plus

back to summary

public PSortedSet<E> plus(E e)

Redeclares org.pcollections.PSet.plus.

Returns:PSortedSet<E>

This set, except with e added (unless e is already an element of this set).

Annotations

@Override

Exceptions

NullPointerException:: if e is null
IllegalArgumentException:: if e is incompatible with this set (optional)

plusAll	back to summary
public PSortedSet<E> plusAll(Collection<? extends E> list) Redeclares org.pcollections.PSet.plusAll. Returns:PSortedSet<E> This set, except with the elements of list added (unless they are already elements of this set). Annotations @Override Exceptions NullPointerException: if list is null or contains null IllegalArgumentException: if list contains an element that is incompatible with this set (optional)

plusAll

back to summary

public PSortedSet<E> plusAll(Collection<? extends E> list)

Redeclares org.pcollections.PSet.plusAll.

Returns:PSortedSet<E>

This set, except with the elements of list added (unless they are already elements of this set).

Annotations

@Override

Exceptions

NullPointerException:: if list is null or contains null
IllegalArgumentException:: if list contains an element that is incompatible with this set (optional)

pollFirst back to summary

pollFirst	back to summary
public default E pollFirst() Implements java.util.NavigableSet.pollFirst. Doc from java.util.NavigableSet.pollFirst. Deprecated Unsupported operation. Retrieves and removes the first (lowest) element, or returns `null` if this set is empty (optional operation). Returns:E the first element, or `null` if this set is empty Annotations @Deprecated @Override Exceptions UnsupportedOperationException: always

public default E pollFirst()

Implements java.util.NavigableSet.pollFirst.

Doc from java.util.NavigableSet.pollFirst.

Deprecated

Unsupported operation.

Retrieves and removes the first (lowest) element, or returns null if this set is empty (optional operation).

Returns:E

the first element, or null if this set is empty

Annotations

@Deprecated
@Override

Exceptions

UnsupportedOperationException:: always

pollLast back to summary

pollLast	back to summary
public default E pollLast() Implements java.util.NavigableSet.pollLast. Doc from java.util.NavigableSet.pollLast. Deprecated Unsupported operation. Retrieves and removes the last (highest) element, or returns `null` if this set is empty (optional operation). Returns:E the last element, or `null` if this set is empty Annotations @Deprecated @Override Exceptions UnsupportedOperationException: always

public default E pollLast()

Implements java.util.NavigableSet.pollLast.

Doc from java.util.NavigableSet.pollLast.

Deprecated

Unsupported operation.

Retrieves and removes the last (highest) element, or returns null if this set is empty (optional operation).

Returns:E

the last element, or null if this set is empty

Annotations

@Deprecated
@Override

Exceptions

UnsupportedOperationException:: always

subSet back to summary

subSet	back to summary
public PSortedSet<E> subSet(E fromElement, E toElement) Redeclares java.util.NavigableSet.subSet. Doc from java.util.NavigableSet.subSet. Returns a view of the portion of this set whose elements range from `fromElement`, inclusive, to `toElement`, exclusive. (If `fromElement` and `toElement` are equal, the returned set is empty.) The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports. The returned set will throw an `IllegalArgumentException` on an attempt to insert an element outside its range. Equivalent to `subSet(fromElement, true, toElement, false)`. Parameters fromElement:E Doc from java.util.SortedSet.subSet. low endpoint (inclusive) of the returned set toElement:E Doc from java.util.SortedSet.subSet. high endpoint (exclusive) of the returned set Returns:PSortedSet<E> Doc from java.util.SortedSet.subSet. a view of the portion of this set whose elements range from `fromElement`, inclusive, to `toElement`, exclusive Annotations @Override

public PSortedSet<E> subSet(E fromElement, E toElement)

Redeclares java.util.NavigableSet.subSet.

Doc from java.util.NavigableSet.subSet.

Returns a view of the portion of this set whose elements range from fromElement, inclusive, to toElement, exclusive. (If fromElement and toElement are equal, the returned set is empty.) The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports.

The returned set will throw an IllegalArgumentException on an attempt to insert an element outside its range.

Equivalent to subSet(fromElement, true, toElement, false).

Parameters

fromElement:E

Doc from java.util.SortedSet.subSet.

low endpoint (inclusive) of the returned set

toElement:E

Doc from java.util.SortedSet.subSet.

high endpoint (exclusive) of the returned set

Returns:PSortedSet<E>

Doc from java.util.SortedSet.subSet.

a view of the portion of this set whose elements range from fromElement, inclusive, to toElement, exclusive

Annotations

@Override

subSet back to summary

subSet	back to summary
public PSortedSet<E> subSet(E fromElement, boolean fromInclusive, E toElement, boolean toInclusive) Redeclares java.util.NavigableSet.subSet. Doc from java.util.NavigableSet.subSet. Returns a view of the portion of this set whose elements range from `fromElement` to `toElement`. If `fromElement` and `toElement` are equal, the returned set is empty unless `fromInclusive` and `toInclusive` are both true. The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports. The returned set will throw an `IllegalArgumentException` on an attempt to insert an element outside its range. Parameters fromElement:E low endpoint of the returned set fromInclusive:boolean `true` if the low endpoint is to be included in the returned view toElement:E high endpoint of the returned set toInclusive:boolean `true` if the high endpoint is to be included in the returned view Returns:PSortedSet<E> a view of the portion of this set whose elements range from `fromElement`, inclusive, to `toElement`, exclusive Annotations @Override

public PSortedSet<E> subSet(E fromElement, boolean fromInclusive, E toElement, boolean toInclusive)

Redeclares java.util.NavigableSet.subSet.

Doc from java.util.NavigableSet.subSet.

Returns a view of the portion of this set whose elements range from fromElement to toElement. If fromElement and toElement are equal, the returned set is empty unless fromInclusive and toInclusive are both true. The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports.

The returned set will throw an IllegalArgumentException on an attempt to insert an element outside its range.

Parameters

fromElement:E: low endpoint of the returned set
fromInclusive:boolean: true if the low endpoint is to be included in the returned view
toElement:E: high endpoint of the returned set
toInclusive:boolean: true if the high endpoint is to be included in the returned view

Returns:PSortedSet<E>

a view of the portion of this set whose elements range from fromElement, inclusive, to toElement, exclusive

Annotations

@Override

tailSet back to summary

tailSet	back to summary
public PSortedSet<E> tailSet(E fromElement) Redeclares java.util.NavigableSet.tailSet. Doc from java.util.NavigableSet.tailSet. Returns a view of the portion of this set whose elements are greater than or equal to `fromElement`. The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports. The returned set will throw an `IllegalArgumentException` on an attempt to insert an element outside its range. Equivalent to `tailSet(fromElement, true)`. Parameters fromElement:E Doc from java.util.SortedSet.tailSet. low endpoint (inclusive) of the returned set Returns:PSortedSet<E> Doc from java.util.SortedSet.tailSet. a view of the portion of this set whose elements are greater than or equal to `fromElement` Annotations @Override

public PSortedSet<E> tailSet(E fromElement)

Redeclares java.util.NavigableSet.tailSet.

Doc from java.util.NavigableSet.tailSet.

Returns a view of the portion of this set whose elements are greater than or equal to fromElement. The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports.

The returned set will throw an IllegalArgumentException on an attempt to insert an element outside its range.

Equivalent to tailSet(fromElement, true).

Parameters

fromElement:E

Doc from java.util.SortedSet.tailSet.

low endpoint (inclusive) of the returned set

Returns:PSortedSet<E>

Doc from java.util.SortedSet.tailSet.

a view of the portion of this set whose elements are greater than or equal to fromElement

Annotations

@Override

tailSet back to summary

tailSet	back to summary
public PSortedSet<E> tailSet(E fromElement, boolean inclusive) Redeclares java.util.NavigableSet.tailSet. Doc from java.util.NavigableSet.tailSet. Returns a view of the portion of this set whose elements are greater than (or equal to, if `inclusive` is true) `fromElement`. The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports. The returned set will throw an `IllegalArgumentException` on an attempt to insert an element outside its range. Parameters fromElement:E low endpoint of the returned set inclusive:boolean `true` if the low endpoint is to be included in the returned view Returns:PSortedSet<E> a view of the portion of this set whose elements are greater than or equal to `fromElement` Annotations @Override

public PSortedSet<E> tailSet(E fromElement, boolean inclusive)

Redeclares java.util.NavigableSet.tailSet.

Doc from java.util.NavigableSet.tailSet.

Returns a view of the portion of this set whose elements are greater than (or equal to, if inclusive is true) fromElement. The returned set is backed by this set, so changes in the returned set are reflected in this set, and vice-versa. The returned set supports all optional set operations that this set supports.

The returned set will throw an IllegalArgumentException on an attempt to insert an element outside its range.

Parameters

fromElement:E: low endpoint of the returned set
inclusive:boolean: true if the low endpoint is to be included in the returned view

Returns:PSortedSet<E>

a view of the portion of this set whose elements are greater than or equal to fromElement

Annotations

@Override

public Interface PSortedSet<E>

Method Summary

Method Detail