# Class Containers

Object
Containers

public final class Containers extends Object
Static methods working on various types of objects that can be viewed as collections. The types include `Collection` and `CheckedContainer`. Some methods are extensions to the standard `Collections` utility class.

## Null values

Most methods in this class accepts null argument values, and collections or arrays containing null elements. By contrast, the standard static methods of `List`, `Set` and `Map` interfaces reject null values. These standard methods should be preferred when null values would be error.

## Element order

All methods in this class preserve element order, including the methods returning a `Set`.

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 <E> List<E>`
  `copyToImmutableList(Collection<? extends E> collection, Class<E> elementType)`
  Copies the content of the specified collection in an immutable list, or returns `null` if the collection is null.
  `static <E> Set<E>`
  `copyToImmutableSet(E... elements)`
  Copies the content of the specified array in an immutable set, or returns `null` if the array is null.
  `static <E> Set<E>`
  `copyToImmutableSetIgnoreNull(E... elements)`
  Copies the non-null elements of the specified array in an immutable set, or returns `null` if the array is null.
  `static <S,E> List<E>`
  `derivedList(List<S> storage, Function<S,E> converter)`
  Returns a list whose elements are derived on-the-fly from the given list.
  `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 <E> Queue<E>`
  `emptyQueue()`
  Returns a queue which is always empty and accepts no element.
  `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 <E> List<E>`
  `newCheckedList(Collection<? extends E> collection, Class<E> elementType)`
  Creates a dynamically type-safe and null-safe list.
  `static <E> Set<E>`
  `newCheckedSet(Collection<? extends E> collection, Class<E> elementType)`
  Creates a dynamically type-safe and null-safe set.
  `static <E> Collection<E>`
  `nonNull(Collection<E> collection)`
  Returns the given collection, or `Collections​.EMPTY_SET` if the given collection is null.
  `static <E> Set<E>`
  `nonNull(Set<E> set)`
  Returns the given set, or `Collections​.EMPTY_SET` if the given set is null.
  `static <T> T`
  `peekFirst(Iterable<T> collection)`
  Returns the first element of the given iterable, or `null` if none.
  `static <T> T`
  `peekIfSingleton(Iterable<T> collection)`
  If the given iterable contains exactly one non-null element, returns that element.
  `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> Set<E>`
  `singletonOrEmpty(E element)`
  Returns the given value as a singleton if non-null, or returns an empty set otherwise.
  `static Collection<?>`
  `toCollection(Object object)`
  Returns the given object as a collection.
  `static <E> List<E>`
  `unmodifiable(List<E> list)`
  Returns an unmodifiable view or copy of the given list.
  `static <K,V> Map<K,V>`
  `unmodifiable(Map<K,V> map)`
  Returns an unmodifiable view or copy of the given map.
  `static <E> Set<E>`
  `unmodifiable(Set<E> set)`
  Returns an unmodifiable view or copy of the given set.
  `static <E> List<? extends E>`
  `unmodifiableList(E... array)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Renamed as `viewAsUnmodifiableList(Object...)` for clarity.
  `static <E> List<? extends E>`
  `unmodifiableList(E[] array, int lower, int upper)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Renamed as `viewAsUnmodifiableList(Object[], int, int)` for clarity.
  `static <E> List<E>`
  `viewAsUnmodifiableList(E... array)`
  Returns an unmodifiable view of the given array.
  `static <E> List<E>`
  `viewAsUnmodifiableList(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

  - ### emptyQueue

    public static <E> Queue<E> emptyQueue()
    Returns a queue which is always empty and accepts no element.
    Type Parameters:
      `E` - the type of elements in the empty queue.
    Returns:
      an empty queue.
    Since:
      1.6
    See Also:
      - `Collections​.emptyList()`
      - `Collections​.emptySet()`

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

  - ### nonNull

    public static <E> Collection<E> nonNull(Collection<E> collection)
    Returns the given collection, or `Collections​.EMPTY_SET` if the given collection is null. In the latter case, the returned collection is tolerant to calls to `contains(null)` and `clear()`.
    Type Parameters:
      `E` - the type of elements in the collection.
    Parameters:
      `collection` - the collection, or `null`.
    Returns:
      the given collection, or an empty collection if the given collection was null.
    Since:
      1.6

  - ### nonNull

    public static <E> Set<E> nonNull(Set<E> set)
    Returns the given set, or `Collections​.EMPTY_SET` if the given set is null. In the latter case, the returned set is tolerant to calls to `contains(null)` and `clear()`.
    Type Parameters:
      `E` - the type of elements in the collection.
    Parameters:
      `set` - the collection, or `null`.
    Returns:
      the given collection, or an empty set if the given collection was null.
    Since:
      1.6

  - ### peekFirst

    public static <T> T peekFirst(Iterable<T> collection)
    Returns the first element of the given iterable, or `null` if none. If the iterable contains more than one element, the remaining elements are ignored. Consequently, this method should be used only when multi-occurrence is not ambiguous.

    This method is null-safe. Note however that the first element may be null. This method does not distinguish between an empty collection and a collection containing null elements.

    Type Parameters:
      `T` - the type of elements contained in the iterable.
    Parameters:
      `collection` - the iterable from which to get the first element, or `null`.
    Returns:
      the first element, or `null` if the given iterable is null or empty.
    Since:
      1.6
    See Also:
      - `Deque​.peekFirst()`

  - ### peekIfSingleton

    public static <T> T peekIfSingleton(Iterable<T> collection)
    If the given iterable contains exactly one non-null element, returns that element. Otherwise returns `null`. This is a variant of `peekFirst(Iterable)` where remaining elements are not ignored.
    Type Parameters:
      `T` - the type of elements contained in the iterable.
    Parameters:
      `collection` - the iterable from which to get the singleton element, or `null`.
    Returns:
      the singleton element, or `null` if the given iterable is null or does not contain exactly one non-null element.
    Since:
      1.6

  - ### singletonOrEmpty

    public static <E> Set<E> singletonOrEmpty(E element)
    Returns the given value as a singleton if non-null, or returns an empty set otherwise.
    Type Parameters:
      `E` - the element type.
    Parameters:
      `element` - the element to return in a collection if non-null.
    Returns:
      a collection containing the given element if non-null, or an empty collection otherwise.
    Since:
      1.6
    See Also:
      - `Collections​.emptySet()`
      - `Collections​.singleton(Object)`

  - ### copyToImmutableSetIgnoreNull

    @SafeVarargs public static <E> Set<E> copyToImmutableSetIgnoreNull(E... elements)
    Copies the non-null elements of the specified array in an immutable set, or returns `null` if the array is null. This method does the same work as `copyToImmutableSet(Object...)` except that null elements are silently ignored.
    Type Parameters:
      `E` - the type of array elements.
    Parameters:
      `elements` - the array to copy in a set. May be `null` or contain null elements.
    Returns:
      an immutable set containing the non-null array elements, or `null` if the given array was null.
    Since:
      1.6
    See Also:
      - `Set​.of(Object...)`

  - ### copyToImmutableSet

    @SafeVarargs public static <E> Set<E> copyToImmutableSet(E... elements)
    Copies the content of the specified array in an immutable set, or returns `null` if the array is null. If the given array contains duplicated elements in the sense of `Object​.equals(Object)`, then the returned set will contain an arbitrary instance among the duplicated values. If the array contains some `null` elements, then the returned set contains one null element.

    #### Differences with standard `Set​.of(…)` method

    This method differs from `Set​.of(Object...)` in that it preserves element order, accepts null argument, accepts null elements and does not throw `IllegalArgumentException` if the array contains duplicated elements.
    Type Parameters:
      `E` - the type of array elements.
    Parameters:
      `elements` - the array to copy in a set. May be `null` or contain null elements.
    Returns:
      an immutable set containing the array elements, or `null` if the given array was null.
    Since:
      1.6
    See Also:
      - `Set​.of(Object...)`

  - ### copyToImmutableList

    public static <E> List<E> copyToImmutableList(Collection<? extends E> collection, Class<E> elementType)
    Copies the content of the specified collection in an immutable list, or returns `null` if the collection is null. The returned list implements the `CheckedContainer` interface.

    #### Differences with standard `List​.of(…)` method

    This method differs from `List​.of(Object...)` in that it accepts null argument, accepts null array elements, and returns a list implementing `CheckedContainer`.
    Type Parameters:
      `E` - the type of collection elements.
    Parameters:
      `collection` - the collection to copy in a list. May be `null` or contain null elements.
      `elementType` - type of elements. This value will be returned by `CheckedContainer​.getElementType()`.
    Returns:
      an immutable list containing the collection elements, or `null` if the given collection was null.
    Since:
      1.6
    See Also:
      - `List​.of(Object...)`

  - ### viewAsUnmodifiableList

    @SafeVarargs public static <E> List<E> viewAsUnmodifiableList(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.

    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.
    Since:
      1.6
    See Also:
      - `Arrays​.asList(Object[])`
      - `Collections​.unmodifiableList(List)`

  - ### viewAsUnmodifiableList

    public static <E> List<E> viewAsUnmodifiableList(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.

    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.
    Since:
      1.6

  - ### unmodifiableList

    @SafeVarargs @Deprecated(since="1.6", forRemoval=true) public static <E> List<? extends E> unmodifiableList(E... array)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Renamed as `viewAsUnmodifiableList(Object...)` for clarity. The new name emphases the contrast with `copyToImmutableList(Collection, Class)`. The parameterized return type is also different.
    Returns an unmodifiable view of the given array. A direct reference to the given array is retained (i.e. the array is not cloned).
    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.

  - ### unmodifiableList

    @Deprecated(since="1.6", forRemoval=true) public static <E> List<? extends E> unmodifiableList(E[] array, int lower, int upper)
    Deprecated, for removal: This API element is subject to removal in a future version.
    Renamed as `viewAsUnmodifiableList(Object[], int, int)` for clarity. The new name emphases the contrast with `copyToImmutableList(Collection, Class)`. The parameterized return type is also different.
    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).
    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.

  - ### unmodifiable

    public static <E> List<E> unmodifiable(List<E> list)
    Returns an unmodifiable view or copy of the given list. This method is similar to the standard `Collections​.unmodifiableList(List)` except for the following:
    - Accepts `null` argument, in which case this method returns `null`.
    - Does not guarantee that the returned list is a view of the given list. It may be a copy.
    - As a result of above relaxation, returns more efficient implementations for lists of zero or one element. Such small set occurs frequently in Apache SIS.
    This method should be used only if the given list will not be modified after this method call. In case of doubt, use the standard `Collections​.unmodifiableList(List)` method if a view is desired, or `List​.copyOf(Collection)` otherwise.

    #### Differences with standard `copyOf(…)` method

    This method differs from `List​.copyOf(Collection)` in that it may avoid copy, and accepts null elements.
    Type Parameters:
      `E` - the type of elements in the list.
    Parameters:
      `list` - the list to make unmodifiable, or `null`.
    Returns:
      an unmodifiable view or copy of the given list, or `null` if the given list was null.
    Since:
      1.6

  - ### unmodifiable

    public static <E> Set<E> unmodifiable(Set<E> set)
    Returns an unmodifiable view or copy of the given set. This method is similar to the standard `Collections​.unmodifiableSet(Set)` except for the following:
    - Accepts `null` argument, in which case this method returns `null`.
    - Does not guarantee that the returned set is a view of the given set. It may be a copy.
    - As a result of above relaxation, returns more efficient implementations for sets of zero or one element. Such small set occurs frequently in Apache SIS, especially for names or identifiers.
    This method should be used only if the given set will not be modified after this method call. In case of doubt, use the standard `Collections​.unmodifiableSet(Set)` method instead.

    #### Differences with standard `copyOf(…)` method

    This method differs from `Set​.copyOf(Collection)` in that it may avoid copy, preserves element order and accepts null elements.
    Type Parameters:
      `E` - the type of elements in the set.
    Parameters:
      `set` - the set to make unmodifiable, or `null`.
    Returns:
      an unmodifiable view or copy of the given set, or `null` if the given set was null.
    Since:
      1.6

  - ### unmodifiable

    public static <K,V> Map<K,V> unmodifiable(Map<K,V> map)
    Returns an unmodifiable view or copy of the given map. This method is similar to the standard `Collections​.unmodifiableMap(Map)` except for the following:
    - Accepts `null` argument, in which case this method returns `null`.
    - Does not guarantee that the returned map is a view of the given map. It may be a copy.
    - As a result of above relaxation, returns more efficient implementations for maps of zero or one entry. Such small map occurs frequently in Apache SIS.
    This method should be used only if the given map will not be modified after this method call. In case of doubt, use the standard `Collections​.unmodifiableMap(Map)` method instead.

    #### Differences with standard `copyOf(…)` method

    This method differs from `Map​.copyOf(Map)` in that it may avoid copy, preserves entry order and accepts null keys and values.
    Type Parameters:
      `K` - the type of keys in the map.
      `V` - the type of values in the map.
    Parameters:
      `map` - the map to make unmodifiable, or `null`.
    Returns:
      an unmodifiable view or copy of the given map, or `null` if the given map was null.
    Since:
      1.6

  - ### newCheckedSet

    public static <E> Set<E> newCheckedSet(Collection<? extends E> collection, Class<E> elementType)
    Creates a dynamically type-safe and null-safe set. Any attempt to insert an element of the wrong type will result in an immediate `ClassCastException`, and any attempt to insert a null element will result in an immediate `NullPointerException`.

    #### Differences with standard `Collections​.checkedSet(…)` method

    This method differs from `Collections​.checkedSet(Set, Class)` in that it copies the given collection instead of wrapping it, verifies the elements of the given collection, does not accept null elements, and returns an instance of `EnumSet`, `CodeListSet` or `CheckedContainer`.
    Type Parameters:
      `E` - the type of collection elements.
    Parameters:
      `collection` - the collection to copy in the set, or `null` for creating an initially empty set.
      `elementType` - type of elements. This value will be returned by `CheckedContainer​.getElementType()`.
    Returns:
      a modifiable set initialized to the given collection elements.
    Throws:
      `NullPointerException` - if `elementType` is null or `collection` is non-null and contains null elements.
      `ClassCastException` - if the given collection is non-null and contains elements not assignable to `elementType`.
    Since:
      1.6
    See Also:
      - `Collections​.checkedSet(Set, Class)`

  - ### newCheckedList

    public static <E> List<E> newCheckedList(Collection<? extends E> collection, Class<E> elementType)
    Creates a dynamically type-safe and null-safe list. Any attempt to insert an element of the wrong type will result in an immediate `ClassCastException`, and any attempt to insert a null element will result in an immediate `NullPointerException`.

    #### Differences with standard `Collections​.checkedList(…)` method

    This method differs from `Collections​.checkedList(List, Class)` in that it copies the given collection instead of wrapping it, verifies the elements of the given collection, does not accept null elements, and returns an instance of `CheckedContainer`.
    Type Parameters:
      `E` - the type of collection elements.
    Parameters:
      `collection` - the collection to copy in the list, or `null` for creating an initially empty list.
      `elementType` - type of elements. This value will be returned by `CheckedContainer​.getElementType()`.
    Returns:
      a modifiable list initialized to the given collection elements.
    Throws:
      `NullPointerException` - if `elementType` is null or `collection` is non-null and contains null elements.
      `ClassCastException` - if the given collection is non-null and contains elements not assignable to `elementType`.
    Since:
      1.6
    See Also:
      - `Collections​.checkedList(List, Class)`

  - ### derivedList

    public static <S,E> List<E> derivedList(List<S> storage, Function<S,E> converter)
    Returns a list whose elements are derived on-the-fly from the given list. Conversions from the original elements to the derived elements are performed when needed by invoking the `Function​.apply(Object)` method on the given converter. Those conversions are repeated every time that a `List` method needs to access values. Consequently, any change in the original list is immediately visible in the derived list.

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

    The returned list does not implement `CheckedContainer`.

    Type Parameters:
      `S` - the type of elements in the storage (original) list.
      `E` - the type of elements in the derived list.
    Parameters:
      `storage` - the storage list containing the original elements, or `null`.
      `converter` - the converter from the elements in the storage list to the elements in the derived list.
    Returns:
      a view over the `storage` list containing all elements converted by the given converter, or `null` if `storage` was null.
    Since:
      1.6

  - ### 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 that a `Set` method needs to access values. 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 that a `Map` method needs to access values. 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)`

  - ### toCollection

    public static Collection<?> toCollection(Object object)
    Returns the given object as a collection. This method recognizes the following types, in that order:
    - If the object is null, then this method returns an empty set.
    - If the object is an instance of `Collection`, then it is returned unchanged.
    - If the object is an array of objects, then it is returned as a list.
    - If the object is an array of primitive type, then it is returned as a list of their wrapper class.
    - Otherwise, the object is returned as a singleton.
    Parameters:
      `object` - the object to return as a collection, or `null`.
    Returns:
      the object cast as a collection or wrapped in a collection (never `null`).
    Since:
      1.6

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