Package org.apache.sis.util.collection

## 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 thread-safe. Synchronizations (if wanted) are caller responsibility.

  Since:
    0.8
  See Also:
    Serialized Form

  Defined in the `sis-utility` 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)` | Returns `true` 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 than `toElement` frequency.
    `boolean` | `isEmpty()` | Returns `true` 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 of `fromElement` frequency inclusive to `toElement` 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 than `fromElement` 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 Iterable

      `forEach`

    - ### 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 interface `Collection<E>`
      Specified by:
        `size` in interface `Set<E>`
      Specified by:
        `size` in class `AbstractCollection<E>`

    - #### isEmpty

          public boolean isEmpty()

      Returns `true` if this set is empty.
      Specified by:
        `isEmpty` in interface `Collection<E>`
      Specified by:
        `isEmpty` in interface `Set<E>`
      Overrides:
        `isEmpty` in class `AbstractCollection<E>`

    - #### add

          public boolean add​(E element,
                             int occurrence)
                      throws IllegalArgumentException

      Repetitively adds the specified element to this set. Returns `true` 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 be `null`).
        `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` - if `occurrence` is negative.

    - #### add

          public boolean add​(E element)

      Adds the specified element to this set. Returns `true` 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 interface `Collection<E>`
      Specified by:
        `add` in interface `Set<E>`
      Overrides:
        `add` in class `AbstractCollection<E>`
      Parameters:
        `element` - the element to add (may be `null`).
      Returns:
        `true` if this set changed as a result of this operation.

    - #### contains

          public boolean contains​(Object element)

      Returns `true` if this set contains the specified element.
      Specified by:
        `contains` in interface `Collection<E>`
      Specified by:
        `contains` in interface `Set<E>`
      Overrides:
        `contains` in class `AbstractCollection<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. Returns `true` if this set changed as a result of this operation.
      Specified by:
        `remove` in interface `Collection<E>`
      Specified by:
        `remove` in interface `Set<E>`
      Overrides:
        `remove` in class `AbstractCollection<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 interface `Collection<E>`
      Specified by:
        `clear` in interface `Set<E>`
      Overrides:
        `clear` in class `AbstractCollection<E>`

    - #### iterator

          public Iterator<E> iterator()

      Returns an iterator over the elements in this set in frequency order.
      Specified by:
        `iterator` in interface `Collection<E>`
      Specified by:
        `iterator` in interface `Iterable<E>`
      Specified by:
        `iterator` in interface `Set<E>`
      Specified by:
        `iterator` in class `AbstractCollection<E>`

    - #### headSet

          public SortedSet<E> headSet​(E toElement)

      Returns a view of the portion of this set whose elements occur with a frequency strictly less than `toElement` frequency.
      Specified by:
        `headSet` in interface `SortedSet<E>`
      Parameters:
        `toElement` - high endpoint (exclusive) of the returned set. May be `null`.
      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 than `fromElement` frequency.
      Specified by:
        `tailSet` in interface `SortedSet<E>`
      Parameters:
        `fromElement` - low endpoint (inclusive) of the returned set. May be `null`.
      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 of `fromElement` frequency inclusive to `toElement` frequency exclusive.
      Specified by:
        `subSet` in interface `SortedSet<E>`
      Parameters:
        `fromElement` - low endpoint (inclusive) of the returned set. May be `null`.
        `toElement` - high endpoint (exclusive) of the returned set. May be `null`.
      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 interface `SortedSet<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 interface `SortedSet<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 a `FrequencySortedSet`, the comparator is always `this`.

      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 interface `SortedSet<E>`

    - #### compare

          public final int compare​(E o1,
                                   E o2)

      Compares the specified elements for frequency. For `FrequencySortedSet` with default ordering, this method returns a positive number if `o1` has been added more frequently to this set than `o2`, a negative number if `o1` has been added less frequently than `o2`, and 0 otherwise. For `FrequencySortedSet` 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 interface `Comparator<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 interface `Collection<E>`
      Specified by:
        `toArray` in interface `Set<E>`
      Overrides:
        `toArray` in class `AbstractCollection<E>`

    - #### toArray

          public <T> T[] toArray​(T[] array)

      Returns the content of this set as an array.
      Specified by:
        `toArray` in interface `Collection<E>`
      Specified by:
        `toArray` in interface `Set<E>`
      Overrides:
        `toArray` in class `AbstractCollection<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.