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 Checked­Container. 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>	copy­To­Immutable­List(Collection<? extends E> collection, Class<E> element­Type)	Copies the content of the specified collection in an immutable list, or returns null if the collection is null.
static <E> Set<E>	copy­To­Immutable­Set(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>	copy­To­Immutable­Set­Ignore­Null(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>	derived­List(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>	derived­Map(Map<SK,SV> storage, Object­Converter<SK,K> key­Converter, Object­Converter<SV,V> value­Converter)	Returns a map whose keys and values are derived on-the-fly from the given map.
static <S,E> Set<E>	derived­Set(Set<S> storage, Object­Converter<S,E> converter)	Returns a set whose elements are derived on-the-fly from the given set.
static <E> Queue<E>	empty­Queue()	Returns a queue which is always empty and accepts no element.
static int	hash­Map­Capacity(int count)	Returns the capacity to give to the Hash­Map and Hash­Set constructors for holding the given number of elements.
static boolean	is­Null­Or­Empty(Collection<?> collection)	Returns true if the given collection is either null or empty.
static boolean	is­Null­Or­Empty(Map<?,?> map)	Returns true if the given map is either null or empty.
static <E> List<E>	new­Checked­List(Collection<? extends E> collection, Class<E> element­Type)	Creates a dynamically type-safe and null-safe list.
static <E> Set<E>	new­Checked­Set(Collection<? extends E> collection, Class<E> element­Type)	Creates a dynamically type-safe and null-safe set.
static <E> Collection<E>	non­Null(Collection<E> collection)	Returns the given collection, or Collections.EMPTY_SET if the given collection is null.
static <E> Set<E>	non­Null(Set<E> set)	Returns the given set, or Collections.EMPTY_SET if the given set is null.
static <T> T	peek­First(Iterable<T> collection)	Returns the first element of the given iterable, or null if none.
static <T> T	peek­If­Singleton(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>	singleton­Or­Empty(E element)	Returns the given value as a singleton if non-null, or returns an empty set otherwise.
static Collection<?>	to­Collection(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>	unmodifiable­List(E... array)	Deprecated, for removal: This API element is subject to removal in a future version. Renamed as view­As­Unmodifiable­List(Object...) for clarity.
static <E> List<? extends E>	unmodifiable­List(E[] array, int lower, int upper)	Deprecated, for removal: This API element is subject to removal in a future version. Renamed as view­As­Unmodifiable­List(Object[], int, int) for clarity.
static <E> List<E>	view­As­Unmodifiable­List(E... array)	Returns an unmodifiable view of the given array.
static <E> List<E>	view­As­Unmodifiable­List(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, get­Class, hash­Code, notify, notify­All, to­String, 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.empty­List()
• Collections.empty­Set()

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.peek­First()

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 peek­First(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.empty­Set()
• 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 copy­To­Immutable­Set(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 Illegal­Argument­Exception 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 Checked­Container 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 Checked­Container.

Type Parameters:

E - the type of collection elements.

Parameters:

collection - the collection to copy in a list. May be null or contain null elements.

element­Type - type of elements. This value will be returned by Checked­Container.get­Element­Type().

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 Checked­Container interface. The value returned by its Checked­Container.get­Element­Type() 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.as­List(Object[])
• Collections.unmodifiable­List(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 Checked­Container interface. The value returned by its Checked­Container.get­Element­Type() 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:

Index­Out­Of­Bounds­Exception - 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 view­As­Unmodifiable­List(Object...) for clarity. The new name emphases the contrast with copy­To­Immutable­List(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 view­As­Unmodifiable­List(Object[], int, int) for clarity. The new name emphases the contrast with copy­To­Immutable­List(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:

Index­Out­Of­Bounds­Exception - 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.unmodifiable­List(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.unmodifiable­List(List) method if a view is desired, or List.copy­Of(Collection) otherwise.

Differences with standard copy­Of(…) method

This method differs from List.copy­Of(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.unmodifiable­Set(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.unmodifiable­Set(Set) method instead.

Differences with standard copy­Of(…) method

This method differs from Set.copy­Of(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.unmodifiable­Map(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.unmodifiable­Map(Map) method instead.

Differences with standard copy­Of(…) method

This method differs from Map.copy­Of(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 Class­Cast­Exception, and any attempt to insert a null element will result in an immediate Null­Pointer­Exception.

Differences with standard Collections.checked­Set(…) method

This method differs from Collections.checked­Set(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 Enum­Set, Code­List­Set or Checked­Container.

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.

element­Type - type of elements. This value will be returned by Checked­Container.get­Element­Type().

Returns:

a modifiable set initialized to the given collection elements.

Throws:

Null­Pointer­Exception - if element­Type is null or collection is non-null and contains null elements.

Class­Cast­Exception - if the given collection is non-null and contains elements not assignable to element­Type.

Since:

1.6

See Also:

• Collections.checked­Set(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 Class­Cast­Exception, and any attempt to insert a null element will result in an immediate Null­Pointer­Exception.

Differences with standard Collections.checked­List(…) method

This method differs from Collections.checked­List(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 Checked­Container.

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.

element­Type - type of elements. This value will be returned by Checked­Container.get­Element­Type().

Returns:

a modifiable list initialized to the given collection elements.

Throws:

Null­Pointer­Exception - if element­Type is null or collection is non-null and contains null elements.

Class­Cast­Exception - if the given collection is non-null and contains elements not assignable to element­Type.

Since:

1.6

See Also:

• Collections.checked­List(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 Checked­Container.

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 Object­Converter.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:

• Object­Converters.derived­Set(Set, Object­Converter)

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 Object­Converter.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 key­Converter.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 Checked­Container 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.

key­Converter - the converter from the keys in the storage map to the keys in the derived map.

value­Converter - 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:

• Object­Converters.derived­Map(Map, Object­Converter, Object­Converter)
• Object­Converters.derived­Keys(Map, Object­Converter, Class)
• Object­Converters.derived­Values(Map, Class, Object­Converter)

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 Illegal­Argument­Exception 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 Abstract­Identified­Object 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:

Illegal­Argument­Exception - if a non-null property value exists for the given key but can not be cast to the given type.

See Also:

• Argument­Checks.ensure­Can­Cast(String, Class, Object)

hashMapCapacity

public static int hashMapCapacity(int count)

Returns the capacity to give to the Hash­Map and Hash­Set 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: Hash­Set, Hash­Map, Linked­Hash­Set and Linked­Hash­Map. This capacity is not applicable to Identity­Hash­Map.

Since Java 19, the static factory methods in above-cited classes should be used instead of this method. However, this hash­Map­Capacity 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.compare­To(o2) call which returned a value different than zero. If all o1.compare­To(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