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

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### 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 Detail

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