org.jjoost.collections.sets.base
Class IterableSet<V>

java.lang.Object
  org.jjoost.collections.sets.base.IterableSet<V>

All Implemented Interfaces:

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

public abstract class IterableSet<V>
extends java.lang.Object
implements MultiSet<V>

See Also:

Serialized Form

Constructor Summary

IterableSet()

Method Summary

boolean	add(V val) Attempt to add the value to the set, returning false if the value could not be added, and true if it was.
java.lang.Iterable<V>	all(V value) Returns an Iterable of all values contained in the set which are equal to the parameter, as determined by the set's definition of equality.
java.lang.Boolean	apply(V v) Returns the result of applying the function to the parameter
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.
boolean	contains(V value) Returns a boolean indicating if the parameter occurs in the set at least once.
MultiSet<V>	copy() Returns a copy of the set.
int	count(V value) Returns an integer representing the number of occurrences of the value in the set
abstract Equality<? super V>	equality() Returns an object that represents the definition of equality used by this set
V	first(V value) The first value stored in the set that is equal to the provided value, as determined by any provided Equality or Comparator.
boolean	isEmpty() Indicates if the set is empty
abstract java.util.Iterator<V>	iterator()
java.util.List<V>	list(V value) Returns a List of all values contained in the set which are equal to the parameter, as determined by the set's definition of equality.
boolean	permitsDuplicates() Indicates if the set permits a value to occur more than once
V	put(V val) Insert the value into the set.
void	put(V val, int numberOfTimes) Insert the value into the set the specified number of times.
int	putAll(java.lang.Iterable<V> vals) 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 val) 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.
int	totalCount() Returns the total number of values (including duplicates) in the set
Set<V>	unique() Returns a Set representing only the unique values present in this set.
int	uniqueCount() Returns the number of unique values in the set

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

IterableSet

public IterableSet()

Method Detail

equality

public abstract Equality<? super V> equality()

Description copied from interface: AnyReadSet

Returns an object that represents the definition of equality used by this set

Specified by:

equality in interface AnyReadSet<V>

Returns:

an object representing the equality used by this set

iterator

public abstract java.util.Iterator<V> iterator()

Specified by:

iterator in interface java.lang.Iterable<V>

apply

public java.lang.Boolean apply(V v)

Description copied from interface: Function

Returns the result of applying the function to the parameter

Specified by:

apply in interface Function<V,java.lang.Boolean>

Parameters:

v - something of type domain

Returns:

the result of the function (something of type range)

clear

public int clear()

Description copied from interface: AnySet

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.

Specified by:

clear in interface AnySet<V>

Returns:

number removed

clearAndReturn

public java.util.Iterator<V> clearAndReturn()

Description copied from interface: AnySet

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.

Specified by:

clearAndReturn in interface AnySet<V>

Returns:

values removed

copy

public MultiSet<V> copy()

Description copied from interface: MultiSet

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 return a MultiSet

Specified by:

copy in interface AnySet<V>

Specified by:

copy in interface MultiSet<V>

put

public void put(V val,
                int numberOfTimes)

Description copied from interface: MultiSet

Insert the value into the set the specified number of times.

Specified by:

put in interface MultiSet<V>

Parameters:

val - the val

numberOfTimes - the number of times

add

public boolean add(V val)

Description copied from interface: AnySet

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

Specified by:

add in interface AnySet<V>

Parameters:

val - value to insert

Returns:

true if the set was modified, false otherwise

put

public V put(V val)

Description copied from interface: MultiSet

Insert the value into the set. This method will always succeed and the return value will always be null.

Specified by:

put in interface AnySet<V>

Specified by:

put in interface MultiSet<V>

Parameters:

val - the val

Returns:

null

putAll

public int putAll(java.lang.Iterable<V> vals)

Description copied from interface: AnySet

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.

Specified by:

putAll in interface AnySet<V>

Parameters:

vals - values to insert

Returns:

number that did not displace existing values

putIfAbsent

public V putIfAbsent(V val)

Description copied from interface: AnySet

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

Specified by:

putIfAbsent in interface AnySet<V>

Parameters:

val - value to insert

Returns:

existing value, or null if none

remove

public int remove(V value,
                  int removeAtMost)

Description copied from interface: AnySet

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.

Specified by:

remove in interface AnySet<V>

Parameters:

value - remove equal to

removeAtMost - remove at most

Returns:

the number removed

remove

public int remove(V value)

Description copied from interface: AnySet

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).

Specified by:

remove in interface AnySet<V>

Parameters:

value - remove equal to

Returns:

number removed

removeAndReturn

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

Description copied from interface: AnySet

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.

Specified by:

removeAndReturn in interface AnySet<V>

Parameters:

value - the value

removeAtMost - remove at most

Returns:

values removed

removeAndReturn

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

Description copied from interface: AnySet

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

Specified by:

removeAndReturn in interface AnySet<V>

Parameters:

value - remove equal to

Returns:

values removed

removeAndReturnFirst

public V removeAndReturnFirst(V value,
                              int removeAtMost)

Description copied from interface: AnySet

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.

Specified by:

removeAndReturnFirst in interface AnySet<V>

Parameters:

value - remove

removeAtMost - remove at most

Returns:

first value removed

removeAndReturnFirst

public V removeAndReturnFirst(V value)

Description copied from interface: AnySet

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).

Specified by:

removeAndReturnFirst in interface AnySet<V>

Parameters:

value - remove

Returns:

first value removed

shrink

public void shrink()

Description copied from interface: AnySet

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

Specified by:

shrink in interface AnySet<V>

all

public java.lang.Iterable<V> all(V value)

Description copied from interface: AnyReadSet

Returns an Iterable of all values contained in the set which are equal to the parameter, as determined by the set's definition of equality.

Changes to the set that happen prior to retrieving an Iterator from the Iterable should be reflected in the resulting Iterator. Changes to the set once an Iterator has been obtained may or may not be reflected in the Iterator at the discretion of the implementing class.

In a concurrent set it is acceptable for values to occur extra times if they are deleted and re-inserted in between method calls on the Iterator.

Specified by:

all in interface AnyReadSet<V>

Parameters:

value - value to look for

Returns:

matching values

contains

public boolean contains(V value)

Description copied from interface: AnyReadSet

Returns a boolean indicating if the parameter occurs in the set at least once.

Specified by:

contains in interface AnyReadSet<V>

Parameters:

value - value to look for

Returns:

true, if present

count

public int count(V value)

Description copied from interface: AnyReadSet

Returns an integer representing the number of occurrences of the value in the set

Specified by:

count in interface AnyReadSet<V>

Parameters:

value - value to look for

Returns:

number of occurrences

first

public V first(V value)

Description copied from interface: AnyReadSet

The first value stored in the set that is equal to the provided value, as determined by any provided Equality or Comparator. Returns null if no matching item is stored in the set.

Specified by:

first in interface AnyReadSet<V>

Parameters:

value - value to look for

Returns:

first matching value

isEmpty

public boolean isEmpty()

Description copied from interface: AnyReadSet

Indicates if the set is empty

Specified by:

isEmpty in interface AnyReadSet<V>

Returns:

true, if is empty

list

public java.util.List<V> list(V value)

Description copied from interface: AnyReadSet

Returns a List of all values contained in the set which are equal to the parameter, as determined by the set's definition of equality. This list should be constructed "eagerly" and should be a consistent snapshot of the values valid at some point between the method being called and it returning.

Specified by:

list in interface AnyReadSet<V>

Parameters:

value - value to look for

Returns:

matching values

permitsDuplicates

public boolean permitsDuplicates()

Description copied from interface: AnyReadSet

Indicates if the set permits a value to occur more than once

Specified by:

permitsDuplicates in interface AnyReadSet<V>

Returns:

true, if successful

totalCount

public int totalCount()

Description copied from interface: AnyReadSet

Returns the total number of values (including duplicates) in the set

Specified by:

totalCount in interface AnyReadSet<V>

Returns:

total number of values in the set

unique

public Set<V> unique()

Description copied from interface: MultiSet

Returns a Set representing only the unique values present in this set. Changes to each set should be reflected in the other, however put() operations on the unique() set are not supported.

Specified by:

unique in interface AnyReadSet<V>

Specified by:

unique in interface AnySet<V>

Specified by:

unique in interface MultiSet<V>

Returns:

unique values

uniqueCount

public int uniqueCount()

Description copied from interface: AnyReadSet

Returns the number of unique values in the set

Specified by:

uniqueCount in interface AnyReadSet<V>

Returns:

number of unique values in the set