# Class Containers

Object
Static
Containers

public final class Containers extends Static
Static methods working on `Collection` or `CheckedContainer` objects. Unless otherwise noted in the javadoc, every collections returned by the methods in this class implement the `CheckedContainer` interface.

Since:
  0.3

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <E extends Comparable<E>>
  int`
  `compare(Iterator<E> it1, Iterator<? extends E> it2)`
  Compares element-by-element the values provided by two iterators, in iteration order.
  `static <SK,SV,K,V>
  Map<K,V>`
  `derivedMap(Map<SK,SV> storage, ObjectConverter<SK,K> keyConverter, ObjectConverter<SV,V> valueConverter)`
  Returns a map whose keys and values are derived on-the-fly from the given map.
  `static <S,E> Set<E>`
  `derivedSet(Set<S> storage, ObjectConverter<S,E> converter)`
  Returns a set whose elements are derived on-the-fly from the given set.
  `static int`
  `hashMapCapacity(int count)`
  Returns the capacity to give to the `HashMap` and `HashSet` constructors for holding the given number of elements.
  `static boolean`
  `isNullOrEmpty(Collection<?> collection)`
  Returns `true` if the given collection is either null or empty.
  `static boolean`
  `isNullOrEmpty(Map<?,?> map)`
  Returns `true` if the given map is either null or empty.
  `static <T> T`
  `property(Map<?,?> properties, Object key, Class<T> type)`
  Returns the value mapped to the given key cast to the given type, or `null` if the map is null or does not contain a value for the key.
  `static <E> List<? extends E>`
  `unmodifiableList(E... array)`
  Returns an unmodifiable view of the given array.
  `static <E> List<? extends E>`
  `unmodifiableList(E[] array, int lower, int upper)`
  Returns an unmodifiable view of a subregion of the given array.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### isNullOrEmpty

    public static boolean isNullOrEmpty(Collection<?> collection)
    Returns `true` if the given collection is either null or empty. If this method returns `false`, then the given collection is guaranteed to be non-null and to contain at least one element.

    This is a convenience method for classes implementing the lazy instantiation pattern. In such cases, null collections (i.e. collections not yet instantiated) are typically considered as empty.

    Parameters:
      `collection` - the collection to test, or `null`.
    Returns:
      `true` if the given collection is null or empty, or `false` otherwise.

  - ### isNullOrEmpty

    public static boolean isNullOrEmpty(Map<?,?> map)
    Returns `true` if the given map is either null or empty. If this method returns `false`, then the given map is guaranteed to be non-null and to contain at least one element.

    This is a convenience method for classes implementing the lazy instantiation pattern. In such cases, null maps (i.e. maps not yet instantiated) are typically considered as empty.

    Parameters:
      `map` - the map to test, or `null`.
    Returns:
      `true` if the given map is null or empty, or `false` otherwise.

  - ### unmodifiableList

    @SafeVarargs public static <E> List<? extends E> unmodifiableList(E... array)
    Returns an unmodifiable view of the given array. A direct reference to the given array is retained (i.e. the array is not cloned). Consequently, the given array shall not be modified after construction if the returned list is intended to be immutable.

    The returned list implements the `CheckedContainer` interface. The value returned by its `CheckedContainer​.getElementType()` method is inferred from the array component type. Because arrays in the Java language are covariant (at the contrary of collections), the list type have to be `<? extends E>` instead of `<E>`.

    Type Parameters:
      `E` - the base type of elements in the list.
    Parameters:
      `array` - the array to wrap, or `null` if none.
    Returns:
      the given array wrapped in an unmodifiable list, or `null` if the given array was null.
    See Also:
      - `Arrays​.asList(Object[])`

  - ### unmodifiableList

    public static <E> List<? extends E> unmodifiableList(E[] array, int lower, int upper)
    Returns an unmodifiable view of a subregion of the given array. A direct reference to the given array is retained (i.e. the array is not cloned). Consequently, the specified sub-region of the given array shall not be modified after construction if the returned list is intended to be immutable.

    The returned list implements the `CheckedContainer` interface. The value returned by its `CheckedContainer​.getElementType()` method is inferred from the array component type. Because arrays in the Java language are covariant (at the contrary of collections), the list type have to be `<? extends E>` instead of `<E>`.

    Type Parameters:
      `E` - the type of elements in the list.
    Parameters:
      `array` - the array to wrap (cannot be null).
      `lower` - low endpoint (inclusive) of the sublist.
      `upper` - high endpoint (exclusive) of the sublist.
    Returns:
      the given array wrapped in an unmodifiable list.
    Throws:
      `IndexOutOfBoundsException` - if the lower or upper value are out of bounds.

  - ### derivedSet

    public static <S,E> Set<E> derivedSet(Set<S> storage, ObjectConverter<S,E> converter)
    Returns a set whose elements are derived on-the-fly from the given set. Conversions from the original elements to the derived elements are performed when needed by invoking the `ObjectConverter​.apply(Object)` method on the given converter. Those conversions are repeated every time a `Set` method is invoked; there is no cache. Consequently, any change in the original set is immediately visible in the derived set, and conversely.

    The `Set​.add(E)` method is supported only if the given converter is invertible. An invertible converter is not mandatory for other `Set` operations. However, `contains` and `remove` operations are likely to be faster if the inverse converter is available.

    The derived set may contain fewer elements than the original set if some elements are not convertible. Non-convertible elements are S values for which `converter​.apply(S)` returns `null`. As a consequence of this sentinel value usage, the derived set cannot contain `null` elements.

    The returned set can be serialized if the given set and converter are serializable. The returned set is not synchronized by itself, but is nevertheless thread-safe if the given set (including its iterator) and converter are thread-safe.

    Type Parameters:
      `S` - the type of elements in the storage (original) set.
      `E` - the type of elements in the derived set.
    Parameters:
      `storage` - the storage set containing the original elements, or `null`.
      `converter` - the converter from the elements in the storage set to the elements in the derived set.
    Returns:
      a view over the `storage` set containing all elements converted by the given converter, or `null` if `storage` was null.
    See Also:
      - `ObjectConverters​.derivedSet(Set, ObjectConverter)`

  - ### derivedMap

    public static <SK,SV,K,V> Map<K,V> derivedMap(Map<SK,SV> storage, ObjectConverter<SK,K> keyConverter, ObjectConverter<SV,V> valueConverter)
    Returns a map whose keys and values are derived on-the-fly from the given map. Conversions from the original entries to the derived entries are performed when needed by invoking the `ObjectConverter​.apply(Object)` method on the given converters. Those conversions are repeated every time a `Map` method is invoked; there is no cache. Consequently, any change in the original map is immediately visible in the derived map, and conversely.

    The `Map​.put(K,V)` method is supported only if the given converters are invertible. An invertible converter is not mandatory for other `Map` operations like `Map​.get(Object)`, but some of them may be faster if the inverse converters are available.

    The derived map may contain fewer entries than the original map if some keys are not convertible. A key K is non-convertible if `keyConverter​.apply(K)` returns `null`. As a consequence of this sentinel key usage, the derived map cannot contain `null` keys. It may contain `null` values however.

    The returned map can be serialized if the given map and converters are serializable. The returned map is not thread-safe.

    The returned map does not implement the `CheckedContainer` interface since `Map` is not a `Collection` sub-type, but the derived map key set and entry set do.

    Type Parameters:
      `SK` - the type of keys in the storage map.
      `SV` - the type of values in the storage map.
      `K` - the type of keys in the derived map.
      `V` - the type of values in the derived map.
    Parameters:
      `storage` - the storage map containing the original entries, or `null`.
      `keyConverter` - the converter from the keys in the storage map to the keys in the derived map.
      `valueConverter` - the converter from the values in the storage map to the values in the derived map.
    Returns:
      a view over the `storage` map containing all entries converted by the given converters, or `null` if `storage` was null.
    See Also:
      - `ObjectConverters​.derivedMap(Map, ObjectConverter, ObjectConverter)`
      - `ObjectConverters​.derivedKeys(Map, ObjectConverter, Class)`
      - `ObjectConverters​.derivedValues(Map, Class, ObjectConverter)`

  - ### property

    public static <T> T property(Map<?,?> properties, Object key, Class<T> type) throws IllegalArgumentException
    Returns the value mapped to the given key cast to the given type, or `null` if the map is null or does not contain a value for the key. If the mapped value is non-null but cannot be cast to the given type, then this method throws an `IllegalArgumentException` with a message of the form Property ‘`key`’ does not accept instances of ‘`value​.class`’..

    This is a helper method for processing a `Map` argument containing property values of various kinds, as in the `AbstractIdentifiedObject` constructor.

    Type Parameters:
      `T` - the compile-time value of the `type` argument.
    Parameters:
      `properties` - the map of properties from which to get a value, or `null` if none.
      `key` - the key of the property value to return. Can be `null` if the map supports null key.
      `type` - the expected type of the property value. Cannot be null.
    Returns:
      the property value for the given key cast to the given type, or `null` if none.
    Throws:
      `IllegalArgumentException` - if a non-null property value exists for the given key but can not be cast to the given type.
    See Also:
      - `ArgumentChecks​.ensureCanCast(String, Class, Object)`

  - ### hashMapCapacity

    public static int hashMapCapacity(int count)
    Returns the capacity to give to the `HashMap` and `HashSet` constructors for holding the given number of elements. This method computes the capacity for the default load factor, which is 0.75. This capacity is applicable to the following classes: `HashSet`, `HashMap`, `LinkedHashSet` and `LinkedHashMap`. This capacity is not applicable to `IdentityHashMap`.

    Since Java 19, the static factory methods in above-cited classes should be used instead of this method. However, this `hashMapCapacity` method is still useful in a few cases where the standard factory methods cannot be invoked, for example because the collection to construct is a subclasses for the standard classes.

    Parameters:
      `count` - the number of elements to be put into the hash map or hash set.
    Returns:
      the minimal initial capacity to be given to the hash map constructor.

  - ### compare

    public static <E extends Comparable<E>> int compare(Iterator<E> it1, Iterator<? extends E> it2)
    Compares element-by-element the values provided by two iterators, in iteration order. Let `o1` be an element from the first iterator and `o2` the element at the same position from the second iterator. This method returns the result of the first `o1​.compareTo(o2)` call which returned a value different than zero. If all `o1​.compareTo(o2)` calls returned zero, then this method returns -1 if `it1` iteration finished before `it2`, +1 if `it2` iteration finished before `it1`, or 0 if both iterators finished at the same time.

    Iterators may return null elements. Null elements are considered "after" any non-null element.

    Type Parameters:
      `E` - the type of elements returned by the iterators.
    Parameters:
      `it1` - the first iterator (cannot be null).
      `it2` - the second iterator (cannot be null).
    Returns:
      -1 if the content given by the first iterator is considered "before" the content given by the second iterator, +1 if considered "after", or 0 if considered equal.
    Since:
      1.0