Class FrequencySortedSet<E>
 Object

 AbstractCollection<E>

 AbstractSet<E>

 FrequencySortedSet<E>

 Type Parameters:
E
 the type of elements in the set.
 All Implemented Interfaces:
Serializable
,Iterable<E>
,Collection<E>
,Comparator<E>
,Set<E>
,SortedSet<E>
public class FrequencySortedSet<E> extends AbstractSet<E> implements SortedSet<E>, Comparator<E>, Serializable
A set with elements ordered by the amount of time they were added. By default, less frequently added elements are first and most frequently added elements are last. If some elements were added the same amount of time, then the iterator will traverse them in their insertion order.An optional boolean argument in the constructor allows the construction of set in reversed order (most frequently added elements first, less frequently added last). This is similar but not identical to creating a default
FrequencySortedSet
and iterating through it in reverse order. The difference is that elements added the same amount of time will still be traversed in their insertion order.This class is not threadsafe. Synchronizations (if wanted) are caller responsibility.
 Since:
 0.8
 See Also:
 Serialized Form
Defined in the
sisutility
module


Constructor Summary
Constructors Constructor Description FrequencySortedSet()
Creates an initially empty set with less frequent elements first.FrequencySortedSet(boolean reversed)
Creates an initially empty set with the default initial capacity.FrequencySortedSet(int initialCapacity, boolean reversed)
Creates an initially empty set with the specified initial capacity.

Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
add(E element)
Adds the specified element to this set.boolean
add(E element, int occurrence)
Repetitively adds the specified element to this set.void
clear()
Removes all elements from this set.Comparator<E>
comparator()
Returns the comparator used to order the elements in this set.int
compare(E o1, E o2)
Compares the specified elements for frequency.boolean
contains(Object element)
Returnstrue
if this set contains the specified element.E
first()
Returns the first element in this set.int[]
frequencies()
Returns the frequency of all elements in this set, in iteration order.int
frequency(E element)
Returns the frequency of the specified element in this set.SortedSet<E>
headSet(E toElement)
Returns a view of the portion of this set whose elements occur with a frequency strictly less thantoElement
frequency.boolean
isEmpty()
Returnstrue
if this set is empty.Iterator<E>
iterator()
Returns an iterator over the elements in this set in frequency order.E
last()
Returns the last element in this set.boolean
remove(Object element)
Removes the specified element from this set, no matter how many time it has been added.int
size()
Returns the number of elements in this set.SortedSet<E>
subSet(E fromElement, E toElement)
Returns a view of the portion of this set whose elements occur with a frequency in the range offromElement
frequency inclusive totoElement
frequency exclusive.SortedSet<E>
tailSet(E fromElement)
Returns a view of the portion of this set whose elements occur with a frequency equal or greater thanfromElement
frequency.Object[]
toArray()
Returns the content of this set as an array.<T> T[]
toArray(T[] array)
Returns the content of this set as an array.
Methods inherited from class AbstractSet
equals, hashCode, removeAll

Methods inherited from class AbstractCollection
addAll, containsAll, retainAll, toString

Methods inherited from class Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface Collection
parallelStream, removeIf, stream, toArray

Methods inherited from interface Comparator
equals, reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong

Methods inherited from interface Set
addAll, containsAll, equals, hashCode, removeAll, retainAll

Methods inherited from interface SortedSet
spliterator




Constructor Detail

FrequencySortedSet
public FrequencySortedSet()
Creates an initially empty set with less frequent elements first.

FrequencySortedSet
public FrequencySortedSet(boolean reversed)
Creates an initially empty set with the default initial capacity. Parameters:
reversed
true
if the elements should be sorted in reverse order (most frequent element first, less frequent element last).

FrequencySortedSet
public FrequencySortedSet(int initialCapacity, boolean reversed)
Creates an initially empty set with the specified initial capacity. Parameters:
initialCapacity
 the initial capacity.reversed
true
if the elements should be sorted in reverse order (most frequent element first, less frequent element last).


Method Detail

size
public int size()
Returns the number of elements in this set. Specified by:
size
in interfaceCollection<E>
 Specified by:
size
in interfaceSet<E>
 Specified by:
size
in classAbstractCollection<E>

isEmpty
public boolean isEmpty()
Returnstrue
if this set is empty. Specified by:
isEmpty
in interfaceCollection<E>
 Specified by:
isEmpty
in interfaceSet<E>
 Overrides:
isEmpty
in classAbstractCollection<E>

add
public boolean add(E element, int occurrence) throws IllegalArgumentException
Repetitively adds the specified element to this set. Returnstrue
if this set changed as a result of this operation. Changes in element order are not notified by the returned value. Parameters:
element
 the element to add (may benull
).occurrence
 the number of time to add the given element. The default value is 1. Returns:
true
if this set changed as a result of this operation. Throws:
IllegalArgumentException
 ifoccurrence
is negative.

add
public boolean add(E element)
Adds the specified element to this set. Returnstrue
if this set changed as a result of this operation. Changes in element order are not notified by the returned value.The default implementation delegates to
add(element, 1)
. Specified by:
add
in interfaceCollection<E>
 Specified by:
add
in interfaceSet<E>
 Overrides:
add
in classAbstractCollection<E>
 Parameters:
element
 the element to add (may benull
). Returns:
true
if this set changed as a result of this operation.

contains
public boolean contains(Object element)
Returnstrue
if this set contains the specified element. Specified by:
contains
in interfaceCollection<E>
 Specified by:
contains
in interfaceSet<E>
 Overrides:
contains
in classAbstractCollection<E>
 Parameters:
element
 the element whose presence in this set is to be tested. Returns:
true
if this set contains the specified element.

remove
public boolean remove(Object element)
Removes the specified element from this set, no matter how many time it has been added. Returnstrue
if this set changed as a result of this operation. Specified by:
remove
in interfaceCollection<E>
 Specified by:
remove
in interfaceSet<E>
 Overrides:
remove
in classAbstractCollection<E>
 Parameters:
element
 the element to remove. Returns:
true
if this set changed as a result of this operation.

clear
public void clear()
Removes all elements from this set. Specified by:
clear
in interfaceCollection<E>
 Specified by:
clear
in interfaceSet<E>
 Overrides:
clear
in classAbstractCollection<E>

iterator
public Iterator<E> iterator()
Returns an iterator over the elements in this set in frequency order.

headSet
public SortedSet<E> headSet(E toElement)
Returns a view of the portion of this set whose elements occur with a frequency strictly less thantoElement
frequency. Specified by:
headSet
in interfaceSortedSet<E>
 Parameters:
toElement
 high endpoint (exclusive) of the returned set. May benull
. Returns:
 a view of the portion of this set delimited by the given endpoint.

tailSet
public SortedSet<E> tailSet(E fromElement)
Returns a view of the portion of this set whose elements occur with a frequency equal or greater thanfromElement
frequency. Specified by:
tailSet
in interfaceSortedSet<E>
 Parameters:
fromElement
 low endpoint (inclusive) of the returned set. May benull
. Returns:
 a view of the portion of this set delimited by the given endpoint.

subSet
public SortedSet<E> subSet(E fromElement, E toElement)
Returns a view of the portion of this set whose elements occur with a frequency in the range offromElement
frequency inclusive totoElement
frequency exclusive. Specified by:
subSet
in interfaceSortedSet<E>
 Parameters:
fromElement
 low endpoint (inclusive) of the returned set. May benull
.toElement
 high endpoint (exclusive) of the returned set. May benull
. Returns:
 a view of the portion of this set delimited by the given endpoints.

first
public E first() throws NoSuchElementException
Returns the first element in this set. For sets created with the default order, this is the less frequently added element. If more than one element were added with the same frequency, this is the first one that has been added to this set at this frequency.
 For sets created with the reverse order, this is the most frequently added element. If more than one element were added with the same frequency, this is the first one that has been added to this set at this frequency.
 Specified by:
first
in interfaceSortedSet<E>
 Throws:
NoSuchElementException
 if this set is empty.

last
public E last() throws NoSuchElementException
Returns the last element in this set. For sets created with the default order, this is the most frequently added element. If more than one element were added with the same frequency, this is the last one that has been added to this set at this frequency.
 For sets created with the reverse order, this is the less frequently added element. If more than one element were added with the same frequency, this is the last one that has been added to this set at this frequency.
 Specified by:
last
in interfaceSortedSet<E>
 Throws:
NoSuchElementException
 if this set is empty.

comparator
public final Comparator<E> comparator()
Returns the comparator used to order the elements in this set. For aFrequencySortedSet
, the comparator is alwaysthis
.This method is final because the
FrequencySortedSet
implementation makes assumptions on the comparator that would not hold if this method were overridden. Specified by:
comparator
in interfaceSortedSet<E>

compare
public final int compare(E o1, E o2)
Compares the specified elements for frequency. ForFrequencySortedSet
with default ordering, this method returns a positive number ifo1
has been added more frequently to this set thano2
, a negative number ifo1
has been added less frequently thano2
, and 0 otherwise. ForFrequencySortedSet
with reverse ordering, this is the converse.This method is final because the
FrequencySortedSet
implementation makes assumptions on the comparator that would not hold if this method were overridden. Specified by:
compare
in interfaceComparator<E>

frequency
public int frequency(E element)
Returns the frequency of the specified element in this set. Parameters:
element
 the element whose frequency is to be obtained. Returns:
 the frequency of the given element, or
0
if it does not occur in this set.

frequencies
public int[] frequencies()
Returns the frequency of all elements in this set, in iteration order. Returns:
 the frequency of all elements in this set.

toArray
public Object[] toArray()
Returns the content of this set as an array. Specified by:
toArray
in interfaceCollection<E>
 Specified by:
toArray
in interfaceSet<E>
 Overrides:
toArray
in classAbstractCollection<E>

toArray
public <T> T[] toArray(T[] array)
Returns the content of this set as an array. Specified by:
toArray
in interfaceCollection<E>
 Specified by:
toArray
in interfaceSet<E>
 Overrides:
toArray
in classAbstractCollection<E>
 Type Parameters:
T
 the type of the array elements. Parameters:
array
 the array where to copy the elements. Returns:
 the elements in the given array, or in a new array if the given array does not have a sufficient capacity.

