Package cds.utils

## Class TextualSearchList<E>

- java.lang.Object
- - java.util.AbstractCollection<E>
  - - java.util.AbstractList<E>
    - - java.util.ArrayList<E>
      - - cds.utils.TextualSearchList<E>

- Type Parameters:
    `E` - Type of object to manage in this list.
  All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Cloneable`, `java.lang.Iterable<E>`, `java.util.Collection<E>`, `java.util.List<E>`, `java.util.RandomAccess`
  Direct Known Subclasses:
    `SearchColumnList`, `SearchTableList`

      public class TextualSearchList<E>
      extends java.util.ArrayList<E>

  A TextualSearchList is an `ArrayList` with a textual search capability.

  The interest of this class lies in the fact that objects can be searched with or without case sensitivity on their textual key thanks to `get(String, boolean)`.

  The textual key is extracted by an object implementing the `TextualSearchList.KeyExtractor` instance. If no `TextualSearchList.KeyExtractor` instance is given at initialization, the string returned by the `toString()` function will be used as key.

  WARNING: The extracted key MUST be CASE-SENSITIVE and UNIQUE !

  Version:
    1.4 (09/2017)
  Author:
    Grégory Mantelet (CDS;ARI)
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `protected static class` | `TextualSearchList.DefaultKeyExtractor<E>` | Default implementation of `TextualSearchList.KeyExtractor`.
    `static interface` | `TextualSearchList.KeyExtractor<E>` | Lets extract an unique textual key (case-sensitive) from a given type of object.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.util.HashMap<java.lang.String,​java.util.ArrayList<E>>` | `csMap` | Map which associates objects of type E with its textual string (case-sensitive).
    `TextualSearchList.KeyExtractor<E>` | `keyExtractor` | Object to use to extract an unique textual string.
    `protected java.util.HashMap<java.lang.String,​java.util.ArrayList<E>>` | `ncsMap` | Map which associates objects of type E with their lower-case textual string.

    - ### Fields inherited from class java.util.AbstractList

      `modCount`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TextualSearchList()` | Builds an empty TextualSearchList.
    `TextualSearchList​(int initialCapacity)` | Builds an empty TextualSearchList with an initial capacity.
    `TextualSearchList​(int initialCapacity, TextualSearchList.KeyExtractor<E> keyExtractor)` | Builds an empty TextualSearchList with an initial capacity.
    `TextualSearchList​(TextualSearchList.KeyExtractor<E> keyExtractor)` | Builds an empty TextualSearchList.
    `TextualSearchList​(java.util.Collection<? extends E> c)` | Builds a TextualSearchList filled with the objects of the given collection.
    `TextualSearchList​(java.util.Collection<? extends E> c, TextualSearchList.KeyExtractor<E> keyExtractor)` | Builds a TextualSearchList filled with the objects of the given collection.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `add​(int index, E obj)` | Adds the given object at the given position in this list.
    `boolean` | `add​(E obj)` | Adds the given object at the end of this list.
    `boolean` | `addAll​(int index, java.util.Collection<? extends E> c)` | Appends all the objects of the given collection in this list after the given position.
    `boolean` | `addAll​(java.util.Collection<? extends E> c)` | Appends all the objects of the given collection in this list.
    `void` | `clear()` |
    `boolean` | `contains​(java.lang.Object o)` | Returns true if this list contains the specified element.
    `java.util.List<E>` | `get​(java.lang.String key)` | Searches (CASE-INSENSITIVE) the object which has the given key.
    `java.util.List<E>` | `get​(java.lang.String key, boolean caseSensitive)` | Searches of all the object which has the given key.
    `E` | `remove​(int index)` |
    `boolean` | `remove​(java.lang.Object obj)` |
    `protected void` | `removeRange​(int fromIndex, int toIndex)` |
    `E` | `set​(int index, E obj)` | Replaces the element at the specified position in this list with the specified element.

    - ### Methods inherited from class java.util.ArrayList

      `clone, ensureCapacity, equals, forEach, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, removeAll, removeIf, replaceAll, retainAll, size, sort, spliterator, subList, toArray, toArray, trimToSize`

    - ### Methods inherited from class java.util.AbstractCollection

      `containsAll, toString`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface java.util.Collection

      `parallelStream, stream, toArray`

    - ### Methods inherited from interface java.util.List

      `containsAll`

- - ### Field Detail

    - #### keyExtractor

          public final TextualSearchList.KeyExtractor<E> keyExtractor

      Object to use to extract an unique textual string.

    - #### csMap

          protected final java.util.HashMap<java.lang.String,​java.util.ArrayList<E>> csMap

      Map which associates objects of type E with its textual string (case-sensitive).

    - #### ncsMap

          protected final java.util.HashMap<java.lang.String,​java.util.ArrayList<E>> ncsMap

      Map which associates objects of type E with their lower-case textual string.

  - ### Constructor Detail

    - #### TextualSearchList

          public TextualSearchList()

      Builds an empty TextualSearchList.

      Note: the key of inserted objects will be the string returned by their `toString()` function.

      See Also:
        `TextualSearchList(KeyExtractor)`

    - #### TextualSearchList

          public TextualSearchList​(TextualSearchList.KeyExtractor<E> keyExtractor)

      Builds an empty TextualSearchList.
      Parameters:
        `keyExtractor` - The object to use to extract a textual key from objects to insert.
      See Also:
        `ArrayList()`

    - #### TextualSearchList

          public TextualSearchList​(int initialCapacity)

      Builds an empty TextualSearchList with an initial capacity.

      Note: the key of inserted objects will be the string returned by their `toString()` function.

      Parameters:
        `initialCapacity` - Initial capacity of this list.
      See Also:
        `TextualSearchList(int, KeyExtractor)`

    - #### TextualSearchList

          public TextualSearchList​(int initialCapacity,
                                   TextualSearchList.KeyExtractor<E> keyExtractor)

      Builds an empty TextualSearchList with an initial capacity.
      Parameters:
        `initialCapacity` - Initial capacity of this list.
        `keyExtractor` - The object to use to extract a textual key from objects to insert.
      See Also:
        `ArrayList(int)`

    - #### TextualSearchList

          public TextualSearchList​(java.util.Collection<? extends E> c)

      Builds a TextualSearchList filled with the objects of the given collection.

      Note: the key of inserted objects will be the string returned by their `toString()` function.

      Parameters:
        `c` - Collection to copy into this list.

    - #### TextualSearchList

          public TextualSearchList​(java.util.Collection<? extends E> c,
                                   TextualSearchList.KeyExtractor<E> keyExtractor)

      Builds a TextualSearchList filled with the objects of the given collection.
      Parameters:
        `c` - Collection to copy into this list.
        `keyExtractor` - The object object to use to extract a textual key from objects to insert.
      See Also:
        `addAll(Collection)`

  - ### Method Detail

    - #### contains

          public boolean contains​(java.lang.Object o)

      Returns true if this list contains the specified element. More formally, returns true if and only if this list contains at least one element e such that (keyExtractor.getKey(o).equals(keyExtractor.getKey(e))).
      Specified by:
        `contains` in interface `java.util.Collection<E>`
      Specified by:
        `contains` in interface `java.util.List<E>`
      Overrides:
        `contains` in class `java.util.ArrayList<E>`
      Since:
        1.1
      See Also:
        `ArrayList.contains(java.lang.Object)`, `getKey(Object)`

    - #### get

          public final java.util.List<E> get​(java.lang.String key)

      Searches (CASE-INSENSITIVE) the object which has the given key.
      Parameters:
        `key` - Textual key of the object to search.
      Returns:
        The corresponding object or `null`.

    - #### get

          public java.util.List<E> get​(java.lang.String key,
                                       boolean caseSensitive)

      Searches of all the object which has the given key.
      Parameters:
        `key` - Textual key of the object to search.
        `caseSensitive` - true to consider the case of the key, false otherwise.
      Returns:
        All the objects whose the key is the same as the given one.

    - #### add

          public boolean add​(E obj)
                      throws java.lang.NullPointerException,
                             java.lang.IllegalArgumentException

      Adds the given object at the end of this list.
      Specified by:
        `add` in interface `java.util.Collection<E>`
      Specified by:
        `add` in interface `java.util.List<E>`
      Overrides:
        `add` in class `java.util.ArrayList<E>`
      Parameters:
        `obj` - Object to add (different from NULL).
      Throws:
        `java.lang.NullPointerException` - If the given object or its extracted key is `null`.
        `java.lang.IllegalArgumentException` - If the extracted key is already used by another object in this list.
      See Also:
        `ArrayList.add(java.lang.Object)`

    - #### add

          public void add​(int index,
                          E obj)
                   throws java.lang.NullPointerException,
                          java.lang.IllegalArgumentException,
                          java.lang.IndexOutOfBoundsException

      Adds the given object at the given position in this list.
      Specified by:
        `add` in interface `java.util.List<E>`
      Overrides:
        `add` in class `java.util.ArrayList<E>`
      Parameters:
        `index` - Index at which the given object must be added.
        `obj` - Object to add (different from NULL).
      Throws:
        `java.lang.NullPointerException` - If the given object or its extracted key is `null`.
        `java.lang.IllegalArgumentException` - If the extracted key is already used by another object in this list.
        `java.lang.IndexOutOfBoundsException` - If the given index is negative or greater than the size of this list.
      See Also:
        `ArrayList.add(int, java.lang.Object)`

    - #### addAll

          public boolean addAll​(java.util.Collection<? extends E> c)
                         throws java.lang.NullPointerException,
                                java.lang.IllegalArgumentException

      Appends all the objects of the given collection in this list.
      Specified by:
        `addAll` in interface `java.util.Collection<E>`
      Specified by:
        `addAll` in interface `java.util.List<E>`
      Overrides:
        `addAll` in class `java.util.ArrayList<E>`
      Parameters:
        `c` - Collection of objects to add.
      Returns:
        `true` if this list changed as a result of the call, `false` otherwise.
      Throws:
        `java.lang.NullPointerException` - If an object to add or its extracted key is `null`.
        `java.lang.IllegalArgumentException` - If the extracted key is already used by another object in this list.
      See Also:
        `ArrayList.addAll(java.util.Collection)`, `add(Object)`

    - #### addAll

          public boolean addAll​(int index,
                                java.util.Collection<? extends E> c)
                         throws java.lang.NullPointerException,
                                java.lang.IllegalArgumentException,
                                java.lang.IndexOutOfBoundsException

      Appends all the objects of the given collection in this list after the given position.
      Specified by:
        `addAll` in interface `java.util.List<E>`
      Overrides:
        `addAll` in class `java.util.ArrayList<E>`
      Parameters:
        `index` - Position from which objects of the given collection must be added.
        `c` - Collection of objects to add.
      Returns:
        `true` if this list changed as a result of the call, `false` otherwise.
      Throws:
        `java.lang.NullPointerException` - If an object to add or its extracted key is `null`.
        `java.lang.IllegalArgumentException` - If the extracted key is already used by another object in this list.
        `java.lang.IndexOutOfBoundsException` - If the given index is negative or greater than the size of this list.
      See Also:
        `ArrayList.addAll(int, java.util.Collection)`, `add(int, Object)`

    - #### set

          public E set​(int index,
                       E obj)
                throws java.lang.NullPointerException,
                       java.lang.IllegalArgumentException

      Replaces the element at the specified position in this list with the specified element.
      Specified by:
        `set` in interface `java.util.List<E>`
      Overrides:
        `set` in class `java.util.ArrayList<E>`
      Parameters:
        `index` - Position of the object to replace.
        `obj` - Object to be stored at the given position (different from NULL).
      Returns:
        Replaced object.
      Throws:
        `java.lang.NullPointerException` - If the object to add or its extracted key is `null`.
        `java.lang.IllegalArgumentException` - If the extracted key is already used by another object in this list.
        `java.lang.IndexOutOfBoundsException` - If the given index is negative or greater than the size of this list.
      See Also:
        `ArrayList.set(int, java.lang.Object)`

    - #### clear

          public void clear()

      Specified by:
        `clear` in interface `java.util.Collection<E>`
      Specified by:
        `clear` in interface `java.util.List<E>`
      Overrides:
        `clear` in class `java.util.ArrayList<E>`

    - #### remove

          public E remove​(int index)

      Specified by:
        `remove` in interface `java.util.List<E>`
      Overrides:
        `remove` in class `java.util.ArrayList<E>`

    - #### remove

          public boolean remove​(java.lang.Object obj)

      Specified by:
        `remove` in interface `java.util.Collection<E>`
      Specified by:
        `remove` in interface `java.util.List<E>`
      Overrides:
        `remove` in class `java.util.ArrayList<E>`

    - #### removeRange

          protected void removeRange​(int fromIndex,
                                     int toIndex)
                              throws java.lang.IndexOutOfBoundsException

      Overrides:
        `removeRange` in class `java.util.ArrayList<E>`
      Throws:
        `java.lang.IndexOutOfBoundsException`