org.jjoost.collections
Interface AnySet<V>

All Superinterfaces:

AnyReadSet<V>, Function<V,java.lang.Boolean>, java.lang.Iterable<V>, java.io.Serializable

All Known Subinterfaces:

MultiSet<V>, Set<V>, UnitarySet<V>

All Known Implementing Classes:

AbstractArraySet, AbstractHashSet, AbstractSet, AbstractUniqueSetAdapter, AdapterFromJDKSet, ArraySet, HashSet, InlineMultiHashSet, IterableSet, LockFreeCountingMultiHashSet, LockFreeHashSet, LockFreeInlineMultiHashSet, LockFreeLinkedCountingMultiHashSet, LockFreeLinkedInlineMultiHashSet, LockFreeLinkedNestedMultiHashSet, LockFreeLinkedScalarHashSet, LockFreeNestedMultiHashSet, MultiArraySet, NestedMultiHashSet, SerialCountingMultiHashSet, SerialHashSet, SerialInlineMultiHashSet, SerialLinkedCountingMultiHashSet, SerialLinkedHashSet, SerialLinkedInlineMultiHashSet, SerialLinkedNestedMultiHashSet, SerialNestedMultiHashSet, SynchronizedArbitrarySet, SynchronizedMultiSet, SynchronizedSet

public interface AnySet<V>
extends AnyReadSet<V>

This interface is the common ancestor of all modifiable Jjoost sets. The methods declared here make no assumptions about the number of occurences of a given value.

WARNING: Note that in a MultiSet the iterator() method will return an Iterator that enumerates every occurence of every value. If you want to get unique occurences of values, call the unique() method.

Also note that an Iterator returned by concurrent implementors of this class is permitted to return values more times than they actually ever occurred if a valid sequence of deletes and inserts happens to cause the Iterator to see the values multiple times. See the javadoc of the implementing classes to determine their behaviour in this case.

Author:

b.elliottsmith

Method Summary

boolean	add(V value) Attempt to add the value to the set, returning false if the value could not be added, and true if it was.
int	clear() Removes all values from the set and return the number of values removed.
java.util.Iterator<V>	clearAndReturn() Removes all values from the set and returns an Iterator over them.
AnySet<V>	copy() Returns a copy of the set.
V	put(V value) Insert the value into the set, returning any value that was evicted as a result or null if none (note that if the value to insert is null, the null returned cannot be used to determine if any action was taken on the set).
int	putAll(java.lang.Iterable<V> values) Performs the equivalent of a put() operation for every value provided, returning an int representing the total number of values that did not displace existing values.
V	putIfAbsent(V value) Inserts the value and returns null if an equal value does not already occur in the set; otherwise returns the first such value encountered
int	remove(V value) Removes all occurrences of values equal to the parameter from the set, as determined by the set's definition of equality and returns the number of values that were removed from the set.
int	remove(V value, int removeAtMost) Removes at most the prescribed number of values equal to the parameter from the set; which values are removed is implementation specific, and may be arbitrary.
java.lang.Iterable<V>	removeAndReturn(V value) Removes all occurrences of values equal to the parameter and returns an Iterable of the values removed.
java.lang.Iterable<V>	removeAndReturn(V value, int removeAtMost) Removes at most the prescribed number of values equal to the parameter from the set and returns them to the user; which values are removed is implementation specific, and may be arbitrary.
V	removeAndReturnFirst(V value) Removes all occurrences of values equal to the parameter from the set, as determined by the set's definition of equality, and returns the first value encountered or null if none.
V	removeAndReturnFirst(V value, int removeAtMost) Removes at most the prescribed number of values equal to the parameter from the set and returns the first one encountered to the user, or null if none; which values are removed is implementation specific, and may be arbitrary.
void	shrink() This method attempts to minimise the resource utilisation of the set.
AnySet<V>	unique() Returns an AnySet (usually a Set) representing only the unique values present in this set; if this set is already unique this method should return the set itself.

Methods inherited from interface org.jjoost.collections.AnyReadSet

all, contains, count, equality, first, isEmpty, list, permitsDuplicates, totalCount, uniqueCount

Methods inherited from interface java.lang.Iterable

iterator

Methods inherited from interface org.jjoost.util.Function

apply

Method Detail

add

boolean add(V value)

Attempt to add the value to the set, returning false if the value could not be added, and true if it was. In a MultiSet the return value will always be true, however in a Set it will be false if a value equal to the one provided (as determined by the set's definition of equality) was already present. For values inequal to null, this is equivalent to put(value) == null

Parameters:

value - value to insert

Returns:

true if the set was modified, false otherwise

put

V put(V value)

Insert the value into the set, returning any value that was evicted as a result or null if none (note that if the value to insert is null, the null returned cannot be used to determine if any action was taken on the set). In a Set any pre-existing value that is equal to the parameter as determined by the set's definition of equality will be removed from the set and returned. In a MultiSet the return value will always be null

Parameters:

value - value to insert

Returns:

value that was evicted from the set as a result of the action

putAll

int putAll(java.lang.Iterable<V> values)

Performs the equivalent of a put() operation for every value provided, returning an int representing the total number of values that did not displace existing values. In a MultiSet this will always be equal to the number of values provided, however in a Set it may be fewer.

Parameters:

values - values to insert

Returns:

number that did not displace existing values

putIfAbsent

V putIfAbsent(V value)

Inserts the value and returns null if an equal value does not already occur in the set; otherwise returns the first such value encountered

Parameters:

value - value to insert

Returns:

existing value, or null if none

remove

int remove(V value)

Removes all occurrences of values equal to the parameter from the set, as determined by the set's definition of equality and returns the number of values that were removed from the set. Equivalent to remove(value, Integer.MAX_VALUE).

Parameters:

value - remove equal to

Returns:

number removed

remove

int remove(V value,
           int removeAtMost)

Removes at most the prescribed number of values equal to the parameter from the set; which values are removed is implementation specific, and may be arbitrary. Returns the number of values actually removed as a result of the action.

Parameters:

value - remove equal to

removeAtMost - remove at most

Returns:

the number removed

removeAndReturn

java.lang.Iterable<V> removeAndReturn(V value)

Removes all occurrences of values equal to the parameter and returns an Iterable of the values removed. Equivalent to removeAndReturn(value, Integer.MAX_VALUE).

Parameters:

value - remove equal to

Returns:

values removed

removeAndReturn

java.lang.Iterable<V> removeAndReturn(V value,
                                      int removeAtMost)

Removes at most the prescribed number of values equal to the parameter from the set and returns them to the user; which values are removed is implementation specific, and may be arbitrary.

Parameters:

value - the value

removeAtMost - remove at most

Returns:

values removed

removeAndReturnFirst

V removeAndReturnFirst(V value)

Removes all occurrences of values equal to the parameter from the set, as determined by the set's definition of equality, and returns the first value encountered or null if none. Equivalent to removeAndReturnFirst(value, Integer.MAX_VALUE).

Parameters:

value - remove

Returns:

first value removed

removeAndReturnFirst

V removeAndReturnFirst(V value,
                       int removeAtMost)

Removes at most the prescribed number of values equal to the parameter from the set and returns the first one encountered to the user, or null if none; which values are removed is implementation specific, and may be arbitrary.

Parameters:

value - remove

removeAtMost - remove at most

Returns:

first value removed

clear

int clear()

Removes all values from the set and return the number of values removed. In a concurrent set this number should be a atomically determined; i.e. even if the set is no longer clear by the time this method returns, the number of values it reports to have removed should be the actual number removed.

Returns:

number removed

clearAndReturn

java.util.Iterator<V> clearAndReturn()

Removes all values from the set and returns an Iterator over them. This Iterator must be exactly equal to the set of values removed from the set by the action, however this set of values may not necessarily be determined, or the clear() completed, until the Iterator has been exhausted.

Returns:

values removed

unique

AnySet<V> unique()

Returns an AnySet (usually a Set) representing only the unique values present in this set; if this set is already unique this method should return the set itself. Changes to each set should be reflected in the other, however put() operations on the unique() set will not be supported if the underlying set is not itself unique.

Specified by:

unique in interface AnyReadSet<V>

Returns:

unique values

shrink

void shrink()

This method attempts to minimise the resource utilisation of the set. It may be a no-op.

copy

AnySet<V> copy()

Returns a copy of the set. This method may or may not return a set of the same class as the one it was called on, however must be of the same basic interface (either Set or MultiSet).