Package org.apache.sis.util.collection

# Class CodeListSet<E extends CodeList<E>>

Object
AbstractCollection<E>
AbstractSet<E>
CodeListSet<E>

Type Parameters:
  `E` - the type of code list elements in the set.

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `Iterable<E>`, `Collection<E>`, `Set<E>`, `CheckedContainer<E>`

public class CodeListSet<E extends CodeList<E>> extends AbstractSet<E> implements CheckedContainer<E>, Cloneable, Serializable
A specialized `Set` implementation for use with `CodeList` values. All elements in a `CodeListSet` are of the same `CodeList` class, which must be final. Iterators traverse the elements in the order in which the code list constants are declared.

## Implementation note

`CodeListSet` is implemented internally by bit vectors for compact and efficient storage. All bulk operations (`addAll`, `removeAll`, `containsAll`) are very quick if their argument is also a `CodeListSet` instance.

## Usage example

The following example creates a set of `AxisDirection`s for a (x,y,z) coordinate system:

>     CodeListSet<AxisDirection> codes = new CodeListSet<>(AxisDirection.class);
>     Collections.addAll(codes, AxisDirection.EAST, AxisDirection.NORTH, AxisDirection.UP),

Since:
  0.3
See Also:
  - `EnumSet`
  - Serialized Form

Defined in the `sis-utility` module

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CodeListSet(Class<E> elementType)`
  Creates an initially empty set for code lists of the given type.
  `CodeListSet(Class<E> elementType, boolean fill)`
  Creates set for code lists of the given type.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E element)`
  Adds the specified code list element in this set.
  `boolean`
  `addAll(Collection<? extends E> c)`
  Adds all elements of the given collection to this set.
  `void`
  `clear()`
  Removes all elements from this set.
  `CodeListSet<E>`
  `clone()`
  Returns a new set of the same class containing the same elements than this set.
  `boolean`
  `contains(Object object)`
  Returns `true` if this set contains the given element.
  `boolean`
  `containsAll(Collection<?> c)`
  Returns `true` if this set contains all the elements of the given collection.
  `Class<E>`
  `getElementType()`
  Returns the type of code list elements in this set.
  `boolean`
  `isEmpty()`
  Returns `true` if this set does not contains any element.
  `Iterator<E>`
  `iterator()`
  Returns an iterator over the elements in this set.
  `boolean`
  `remove(Object object)`
  Removes the specified code list element from this set.
  `boolean`
  `removeAll(Collection<?> c)`
  Adds all elements of the given collection from this set.
  `boolean`
  `retainAll(Collection<?> c)`
  Retains only the elements of the given collection in this set.
  `int`
  `size()`
  Returns the number of elements in this set.

  ### Methods inherited from class AbstractSet

  `equals, hashCode`

  ### Methods inherited from class AbstractCollection

  `toArray, toArray, toString`

  ### Methods inherited from class Object

  `finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface Collection

  `parallelStream, removeIf, stream, toArray`

  ### Methods inherited from interface Iterable

  `forEach`

  ### Methods inherited from interface Set

  `spliterator, toArray, toArray`

- ## Constructor Details

  - ### CodeListSet

    public CodeListSet(Class<E> elementType) throws IllegalArgumentException
    Creates an initially empty set for code lists of the given type. The given `CodeList` type shall be final.
    Parameters:
      `elementType` - the type of code list elements to be included in this set.
    Throws:
      `IllegalArgumentException` - if the given class is not final.

  - ### CodeListSet

    public CodeListSet(Class<E> elementType, boolean fill) throws IllegalArgumentException
    Creates set for code lists of the given type. If the `fill` argument is `false`, then the new set will be initially empty. Otherwise the new set will be filled with all code list elements of the given type that are known at construction time. Note that if new code list elements are created after the invocation of this `CodeListSet` constructor, then those new elements will not be in this set.
    Parameters:
      `elementType` - the type of code list elements to be included in this set.
      `fill` - `true` for filling the set with all known elements of the given type, or `false` for leaving the set empty.
    Throws:
      `IllegalArgumentException` - if the given class is not final.

- ## Method Details

  - ### getElementType

    public Class<E> getElementType()
    Returns the type of code list elements in this set.
    Specified by:
      `getElementType` in interface `CheckedContainer<E extends CodeList<E>>`
    Returns:
      the type of code list elements in this set.

  - ### clear

    public void clear()
    Removes all elements from this set.
    Specified by:
      `clear` in interface `Collection<E extends CodeList<E>>`
    Specified by:
      `clear` in interface `Set<E extends CodeList<E>>`
    Overrides:
      `clear` in class `AbstractCollection<E extends CodeList<E>>`

  - ### isEmpty

    public boolean isEmpty()
    Returns `true` if this set does not contains any element.
    Specified by:
      `isEmpty` in interface `Collection<E extends CodeList<E>>`
    Specified by:
      `isEmpty` in interface `Set<E extends CodeList<E>>`
    Overrides:
      `isEmpty` in class `AbstractCollection<E extends CodeList<E>>`
    Returns:
      `true` if this set is empty.

  - ### size

    public int size()
    Returns the number of elements in this set.
    Specified by:
      `size` in interface `Collection<E extends CodeList<E>>`
    Specified by:
      `size` in interface `Set<E extends CodeList<E>>`
    Specified by:
      `size` in class `AbstractCollection<E extends CodeList<E>>`
    Returns:
      the number of elements in this set.

  - ### add

    public boolean add(E element)
    Adds the specified code list element in this set.
    Specified by:
      `add` in interface `Collection<E extends CodeList<E>>`
    Specified by:
      `add` in interface `Set<E extends CodeList<E>>`
    Overrides:
      `add` in class `AbstractCollection<E extends CodeList<E>>`
    Parameters:
      `element` - the code list element to add in this set.
    Returns:
      `true` if this set has been modified as a consequence of this method call.

  - ### remove

    public boolean remove(Object object)
    Removes the specified code list element from this set. This methods does nothing if the given argument is `null` or is not an instance of the code list class specified at construction time.
    Specified by:
      `remove` in interface `Collection<E extends CodeList<E>>`
    Specified by:
      `remove` in interface `Set<E extends CodeList<E>>`
    Overrides:
      `remove` in class `AbstractCollection<E extends CodeList<E>>`
    Parameters:
      `object` - the code list element to remove from this set.
    Returns:
      `true` if this set has been modified as a consequence of this method call.

  - ### contains

    public boolean contains(Object object)
    Returns `true` if this set contains the given element. This methods returns `false` if the given argument is `null` or is not an instance of the code list class specified at construction time.
    Specified by:
      `contains` in interface `Collection<E extends CodeList<E>>`
    Specified by:
      `contains` in interface `Set<E extends CodeList<E>>`
    Overrides:
      `contains` in class `AbstractCollection<E extends CodeList<E>>`
    Parameters:
      `object` - the element to test for presence in this set.
    Returns:
      `true` if the given object is contained in this set.

  - ### containsAll

    public boolean containsAll(Collection<?> c)
    Returns `true` if this set contains all the elements of the given collection.
    Specified by:
      `containsAll` in interface `Collection<E extends CodeList<E>>`
    Specified by:
      `containsAll` in interface `Set<E extends CodeList<E>>`
    Overrides:
      `containsAll` in class `AbstractCollection<E extends CodeList<E>>`
    Parameters:
      `c` - the collection to be checked for containment in this set.
    Returns:
      `true` if this set contains all elements of the given collection.

  - ### addAll

    public boolean addAll(Collection<? extends E> c) throws IllegalArgumentException
    Adds all elements of the given collection to this set.
    Specified by:
      `addAll` in interface `Collection<E extends CodeList<E>>`
    Specified by:
      `addAll` in interface `Set<E extends CodeList<E>>`
    Overrides:
      `addAll` in class `AbstractCollection<E extends CodeList<E>>`
    Parameters:
      `c` - the collection containing elements to be added to this set.
    Returns:
      `true` if this set changed as a result of this method call.
    Throws:
      `IllegalArgumentException`

  - ### removeAll

    public boolean removeAll(Collection<?> c)
    Adds all elements of the given collection from this set.
    Specified by:
      `removeAll` in interface `Collection<E extends CodeList<E>>`
    Specified by:
      `removeAll` in interface `Set<E extends CodeList<E>>`
    Overrides:
      `removeAll` in class `AbstractSet<E extends CodeList<E>>`
    Parameters:
      `c` - the collection containing elements to be removed from this set.
    Returns:
      `true` if this set changed as a result of this method call.

  - ### retainAll

    public boolean retainAll(Collection<?> c)
    Retains only the elements of the given collection in this set.
    Specified by:
      `retainAll` in interface `Collection<E extends CodeList<E>>`
    Specified by:
      `retainAll` in interface `Set<E extends CodeList<E>>`
    Overrides:
      `retainAll` in class `AbstractCollection<E extends CodeList<E>>`
    Parameters:
      `c` - the collection containing elements to retain in this set.
    Returns:
      `true` if this set changed as a result of this method call.

  - ### iterator

    public Iterator<E> iterator()
    Returns an iterator over the elements in this set. The instance returned by this implementation will iterate over a snapshot of this `CodeListSet` content at the time this method has been invoked. Changes in this `CodeListSet` made after this method call will not affect the values returned by the iterator.
    Specified by:
      `iterator` in interface `Collection<E extends CodeList<E>>`
    Specified by:
      `iterator` in interface `Iterable<E extends CodeList<E>>`
    Specified by:
      `iterator` in interface `Set<E extends CodeList<E>>`
    Specified by:
      `iterator` in class `AbstractCollection<E extends CodeList<E>>`
    Returns:
      an iterator over the elements in this set.

  - ### clone

    public CodeListSet<E> clone()
    Returns a new set of the same class containing the same elements than this set.
    Overrides:
      `clone` in class `Object`
    Returns:
      a clone of this set.