OrderedScatterSet
public sealed class OrderedScatterSet<E extends Object>
MutableOrderedScatterSet |
|
OrderedScatterSet is a container with a Set-like interface based on a flat hash table implementation that preserves the insertion order for iteration. The underlying implementation is designed to avoid all allocations on insertion, removal, retrieval, and iteration. Allocations may still happen on insertion when the underlying storage needs to grow to accommodate newly added elements to the set.
This implementation guarantees the order of the elements when iterating over them using forEach or the iterator provided by asSet.
Though OrderedScatterSet offers a read-only interface, it is always backed by a MutableOrderedScatterSet. Read operations alone are thread-safe. However, any mutations done through the backing MutableScatterSet while reading on another thread are not safe and the developer must protect the set from such changes during read operations.
Note: when a Set is absolutely necessary, you can use the method asSet to create a thin wrapper around an OrderedScatterSet. Please refer to asSet for more details and caveats.
| See also | |
|---|---|
MutableOrderedScatterSet |
Summary
Protected constructors |
|---|
<E extends Object> OrderedScatterSet() |
Public methods |
|
|---|---|
final boolean |
Returns true if all elements match the given |
final boolean |
any()Returns |
final boolean |
Returns true if at least one element matches the given |
final @NonNull Set<@NonNull E> |
asSet()Wraps this |
final boolean |
Returns true if the specified |
final @IntRange(from = 0) int |
count()Returns the number of elements in this set. |
final @IntRange(from = 0) int |
Returns the number of elements matching the given |
boolean |
Compares the specified object |
final @NonNull E |
first()Returns the first element in the collection. |
final @NonNull E |
Returns the first element in insertion order in the collection for which |
final E |
firstOrNull(Returns the first element in insertion order in the collection for which |
final void |
Iterates over every element stored in this set by invoking the specified |
final void |
forEachReverse(@NonNull Function1<@NonNull element, Unit> block)Iterates over every element stored in this set by invoking the specified |
final @IntRange(from = 0) int |
Returns the number of elements that can be stored in this set without requiring internal storage reallocation. |
final @IntRange(from = 0) int |
getSize()Returns the number of elements in this set. |
int |
hashCode()Returns the hash code value for this set. |
final boolean |
isEmpty()Indicates whether this set is empty. |
final boolean |
Returns |
final @NonNull String |
joinToString(Creates a String from the elements separated by |
final @NonNull E |
last()Returns the last element in the collection. |
final @NonNull E |
Returns the last element in insertion order in the collection for which |
final E |
lastOrNull(@NonNull Function1<@NonNull element, @NonNull Boolean> predicate)Returns the first element in insertion order in the collection for which |
final boolean |
none()Returns |
final @NonNull List<@NonNull E> |
toList()Returns a new list containing this set's entries, in insertion order. |
@NonNull String |
toString()Returns a string representation of this set. |
Protected constructors
Public methods
all
public final boolean all(@NonNull Function1<@NonNull element, @NonNull Boolean> predicate)
Returns true if all elements match the given predicate. If there are no elements in the set, true is returned. The order in which the predicate is called over the elements is arbitrary.
any
public final boolean any(@NonNull Function1<@NonNull element, @NonNull Boolean> predicate)
Returns true if at least one element matches the given predicate. The order in which the predicate is called over the elements is arbitrary.
asSet
public final @NonNull Set<@NonNull E> asSet()
Wraps this OrderedScatterSet with a Set interface. The Set is backed by the OrderedScatterSet, so changes to the OrderedScatterSet are reflected in the Set. If the OrderedScatterSet is modified while an iteration over the Set is in progress, the results of the iteration are undefined.
Note: while this method is useful to use this OrderedScatterSet with APIs accepting Set interfaces, it is less efficient to do so than to use OrderedScatterSet's APIs directly. While the Set implementation returned by this method tries to be as efficient as possible, the semantics of Set may require the allocation of temporary objects for access and iteration.
contains
public final boolean contains(@NonNull E element)
Returns true if the specified element is present in this hash set, false otherwise.
| Parameters | |
|---|---|
@NonNull E element |
The element to look for in this set |
count
public final @IntRange(from = 0) int count()
Returns the number of elements in this set.
count
public final @IntRange(from = 0) int count(@NonNull Function1<@NonNull element, @NonNull Boolean> predicate)
Returns the number of elements matching the given predicate.The order in which the predicate is called over the elements is arbitrary.
equals
public boolean equals(Object other)
Compares the specified object other with this hash set for equality. The two objects are considered equal if other:
-
Is a
OrderedScatterSet -
Has the same
sizeas this set -
Contains elements equal to this set's elements
first
public final @NonNull E first()
Returns the first element in the collection.
| Throws | |
|---|---|
kotlin.NoSuchElementException |
if the collection is empty |
first
public final @NonNull E first(@NonNull Function1<@NonNull element, @NonNull Boolean> predicate)
Returns the first element in insertion order in the collection for which predicate returns true.
| Parameters | |
|---|---|
@NonNull Function1<@NonNull element, @NonNull Boolean> predicate |
called with each element until it returns |
| Throws | |
|---|---|
kotlin.NoSuchElementException |
if |
firstOrNull
public final E firstOrNull(
@NonNull Function1<@NonNull element, @NonNull Boolean> predicate
)
Returns the first element in insertion order in the collection for which predicate returns true or null if there are no elements that match predicate.
forEach
public final void forEach(@NonNull Function1<@NonNull element, Unit> block)
Iterates over every element stored in this set by invoking the specified block lambda. The iteration order is the same as the insertion order. It is safe to remove the element passed to block during iteration.
forEachReverse
public final void forEachReverse(@NonNull Function1<@NonNull element, Unit> block)
Iterates over every element stored in this set by invoking the specified block lambda. The iteration order is the reverse of the insertion order. It is safe to remove the element passed to block during iteration.
getCapacity
public final @IntRange(from = 0) int getCapacity()
Returns the number of elements that can be stored in this set without requiring internal storage reallocation.
getSize
public final @IntRange(from = 0) int getSize()
Returns the number of elements in this set.
hashCode
public int hashCode()
Returns the hash code value for this set. The hash code of a set is based on the sum of the hash codes of the elements in the set, where the hash code of a null element is defined to be zero.
joinToString
public final @NonNull String joinToString(
@NonNull CharSequence separator,
@NonNull CharSequence prefix,
@NonNull CharSequence postfix,
int limit,
@NonNull CharSequence truncated,
Function1<@NonNull E, @NonNull CharSequence> transform
)
Creates a String from the elements separated by separator and using prefix before and postfix after, if supplied.
When a non-negative value of limit is provided, a maximum of limit items are used to generate the string. If the collection holds more than limit items, the string is terminated with truncated.
transform may be supplied to convert each element to a custom String.
last
public final @NonNull E last()
Returns the last element in the collection.
| Throws | |
|---|---|
kotlin.NoSuchElementException |
if the collection is empty |
last
public final @NonNull E last(@NonNull Function1<@NonNull element, @NonNull Boolean> predicate)
Returns the last element in insertion order in the collection for which predicate returns true.
| Parameters | |
|---|---|
@NonNull Function1<@NonNull element, @NonNull Boolean> predicate |
called with each element until it returns |
| Throws | |
|---|---|
kotlin.NoSuchElementException |
if |
lastOrNull
public final E lastOrNull(@NonNull Function1<@NonNull element, @NonNull Boolean> predicate)
Returns the first element in insertion order in the collection for which predicate returns true or null if there are no elements that match predicate.