ObjectUtils

package saker.build.thirdparty.saker.util

public class ObjectUtils

saker.build.thirdparty.saker.util.ObjectUtils

java.lang.Object

Class containing general utility functions for handling various objects.

Fields

public static final boolean[]	EMPTY_BOOLEAN_ARRAY Singleton instance of an empty `boolean` array.
public static final byte[]	EMPTY_BYTE_ARRAY Singleton instance of an empty `byte` array.
public static final char[]	EMPTY_CHAR_ARRAY Singleton instance of an empty `char` array.
public static final Class<?>[]	EMPTY_CLASS_ARRAY Singleton instance of an empty Class array.
public static final double[]	EMPTY_DOUBLE_ARRAY Singleton instance of an empty `double` array.
public static final float[]	EMPTY_FLOAT_ARRAY Singleton instance of an empty `float` array.
public static final int[]	EMPTY_INT_ARRAY Singleton instance of an empty `int` array.
public static final long[]	EMPTY_LONG_ARRAY Singleton instance of an empty `long` array.
public static final Object[]	EMPTY_OBJECT_ARRAY Singleton instance of an empty Object array.
public static final short[]	EMPTY_SHORT_ARRAY Singleton instance of an empty `short` array.
public static final StackTraceElement[]	EMPTY_STACK_TRACE_ELEMENT_ARRAY Singleton instance of an empty StackTraceElement array.
public static final String[]	EMPTY_STRING_ARRAY Singleton instance of an empty String array.
public static final Throwable[]	EMPTY_THROWABLE_ARRAY Singleton instance of an empty Throwable array.

Methods

public static <E, CollType extends Collection<? super E>> CollType	addAll(CollType collection, Iterable<? extends E> objects) Adds all the elements in the argument iterable to the specified collecion.
public static <E, CollType extends Collection<? super E>> CollType	addAll(CollType collection, Collection<? extends E> objects) Adds all the elements in the argument collection to the specified collecion.
public static <E, CollType extends Collection<? super E>> CollType	addAll(CollType collection, Iterator<? extends E> iterator) Adds all the remaining elements in the argument iterator to the specified collecion.
public static <E, CollType extends Collection<? super E>> CollType	addAll(CollType collection, E... objects) Adds all the elements in the specified iterable to the argument collecion.
public static String	classNameOf(Object obj) Gets the class name of the argument object.
public static <T> Class<? extends T>	classOf(T object) Gets the class of the argument if non-`null`.
public static <T> Class<? extends T>	classOf(T object, Class<? extends T> defaultvalue) Gets the class of the argument if non-`null`, else returns a default value.
public static Class<?>[]	classOfArrayElements(Object[] array) Gets the classes of the elements in the argument array.
public static Class<?>[]	classOfArrayElements(Object[] array, Class<?> defaultclass) Gets the classes of the elements in the argument array.
public static <T> T	clone(T object, Function<? super T, ? extends T> cloner) Clones the argument object using the specified cloner function.
public static <E, T> T[]	cloneArray(E[] array, Class<T> targetcomponenttype, Function<? super E, ? extends T> cloner) Clones the argument array to the target component type using the specified cloner function.
public static <E> E[]	cloneArray(E[] array, Function<? super E, ? extends E> cloner) Clones the argument array using the specified cloner function.
public static <E> ArrayList<E>	cloneArrayList(Collection<? extends E> coll) Clones the argument collection by creating an array list that contains the same items.
public static <E> ArrayList<E>	cloneArrayList(Collection<? extends E> coll, Function<? super E, ? extends E> elementcloner) Clones the argument collection and its elements into an array list.
public static <E extends Enum<E>> EnumSet<E>	cloneEnumSet(Class<E> enumclass, Collection<E> values) Creates an EnumSet for the argument enum class and values.
public static <K, V> HashMap<K, V>	cloneHashMap(Map<? extends K, ? extends V> map) Clones the argument map by creating a hash map that contains the same entries.
public static <K, V> LinkedHashMap<K, V>	cloneLinkedHashMap(Map<? extends K, ? extends V> map) Clones the argument map by creating a linked hash map that contains the same entries.
public static <E> LinkedHashSet<E>	cloneLinkedHashSet(Collection<? extends E> coll) Clones the argument collection by creating a new LinkedHashSet.
public static <K, V> TreeMap<K, V>	cloneTreeMap(Map<? extends K, ? extends V> map) Clones the argument map by creating a tree map that contains the same entries.
public static <K, V> TreeMap<K, V>	cloneTreeMap(Map<? extends K, ? extends V> map, Function<? super K, ? extends K> keycloner, Function<? super V, ? extends V> valuecloner) Clones the argument map and its entries into a tree map.
public static <K, V> TreeMap<K, V>	cloneTreeMap(SortedMap<K, ? extends V> map) Clones the argument sorted map by creating a tree map with the same order and entries.
public static <E> TreeSet<E>	cloneTreeSet(Collection<? extends E> coll) Clones the argument collection by creating an tree set that contains the same items.
public static <E> TreeSet<E>	cloneTreeSet(SortedSet<E> coll) Clones the argument sorted set by creating an tree set with the same order and items.
public static <LType, RType> boolean	collectionOrderedEquals(Collection<? extends LType> left, Collection<? extends RType> right) Same as calling collectionEquals`(left, right, Objects::equals`).
public static <LType, RType> boolean	collectionOrderedEquals(Collection<? extends LType> left, Collection<? extends RType> right, BiPredicate<? super LType, ? super RType> comparator) Checks if the argument collections equal by checking the equality of the elements in iteration order using the given function.
public static String	collectionToString(Iterable<?> elements) Creates a string representation of the argument iterable.
public static <LType, RType> int	compareArrays(LType[] left, RType[] right, ToIntBiFunction<? super LType, ? super RType> comparator) Comparison function for comparing the elements of arrays.
public static <LType, RType> int	compareIterables(Iterable<? extends LType> left, Iterable<? extends RType> right, ToIntBiFunction<? super LType, ? super RType> comparator) Comparison function for comparing elements of iterables.
public static <LType, RType> int	compareIterators(Iterator<? extends LType> left, Iterator<? extends RType> right, ToIntBiFunction<? super LType, ? super RType> comparator) Comparison function for comparing iterators.
public static <T extends Comparable<? super T>> int	compareNullsFirst(T l, T r) Comparator function that sorts non-`null` arguments by natural order, else the `null` values first.
public static <T extends Comparable<? super T>> int	compareNullsLast(T l, T r) Comparator function that sorts non-`null` arguments by natural order, else the `null` values last.
public static <LKey, RKey, LType, RType> int	compareOrderedMaps(Map<? extends LKey, ? extends LType> left, Map<? extends RKey, ? extends RType> right, ToIntBiFunction<? super LKey, ? super RKey> keycomparator, ToIntBiFunction<? super LType, ? super RType> valuecomparator) Comparison function for comparing maps based on their iteration order and values.
public static <Key, LType, RType> int	compareOrderedMaps(SortedMap<? extends Key, ? extends LType> left, SortedMap<? extends Key, ? extends RType> right, ToIntBiFunction<? super LType, ? super RType> valuecomparator) Comparison function for comparing sorted maps with the same ordering.
public static <E> int	compareOrderedSets(SortedSet<? extends E> left, SortedSet<? extends E> right) Comparison function for comparing sorted sets with the same ordering.
public static boolean	contains(Iterable<?> iterable, Object object) Checks if the argument iterable contains the specified object.
public static boolean	contains(Collection<?> collection, Object object) Checks if the argument collection is non-`null` and contains the given object.
public static boolean	containsAny(Collection<?> haystack, Iterable<?> needle) Checks if the argument haystack collection contains any element from the needle elements.
public static boolean	containsAny(Collection<?> haystack, Iterator<?> needleit) Checks if the argument haystack collection contains any element from the needle iterator.
public static boolean	containsAnyKey(Map<?, ?> haystack, Iterable<?> needle) Checks if the argument haystack map contains any key from the needle elements.
public static boolean	containsAnyValue(Map<?, ?> haystack, Iterable<?> needle) Checks if the argument haystack map contains any value from the needle elements.
public static boolean	containsKey(Map<?, ?> map, Object object) Checks if the argument map contains a key for the given object.
public static boolean	containsValue(Map<?, ?> map, Object object) Checks if the argument map contains a value for the given object.
public static <K, V> ConcurrentSkipListMap<K, V>	createConcurrentSkipListMapFromSortedIterator(Iterator<? extends Entry<? extends K, ? extends V>> it) Creates a ConcurrentSkipListMap based on the sorted entries in the argument iterator.
public static <K, V> ConcurrentSkipListMap<K, V>	createConcurrentSkipListMapFromSortedIterator(Iterator<? extends Entry<? extends K, ? extends V>> it, Comparator<? super K> comparator) Creates a ConcurrentSkipListMap based on the sorted entries in the argument iterator.
public static <E> ConcurrentSkipListSet<E>	createConcurrentSkipListSetFromSortedIterator(Iterator<? extends E> it) Creates a ConcurrentSkipListSet based on the sorted elements in the argument iterator.
public static <E> ConcurrentSkipListSet<E>	createConcurrentSkipListSetFromSortedIterator(Iterator<? extends E> it, Comparator<? super E> comparator) Creates a ConcurrentSkipListSet based on the sorted elements in the argument iterator.
public static <K, V> NavigableMap<K, V>	createImmutableNavigableMapFromSortedIterator(Iterator<? extends Entry<? extends K, ? extends V>> it, int size) Creates an immutable NavigableMap based on the sorted entries in the argument iterator.
public static <K, V> NavigableMap<K, V>	createImmutableNavigableMapFromSortedIterator(Iterator<? extends Entry<? extends K, ? extends V>> it, int size, Comparator<? super K> comparator) Creates an immutable NavigableMap based on the sorted entries in the argument iterator.
public static <K, V> TreeMap<K, V>	createTreeMapFromSortedIterator(Iterator<? extends Entry<? extends K, ? extends V>> it, int size) Creates a TreeMap based on the sorted entries in the argument iterator.
public static <K, V> TreeMap<K, V>	createTreeMapFromSortedIterator(Iterator<? extends Entry<? extends K, ? extends V>> it, int size, Comparator<? super K> comparator) Creates a TreeMap based on the sorted entries in the argument iterator.
public static <E> TreeSet<E>	createTreeSetFromSortedIterator(Iterator<? extends E> it, int size) Creates a TreeSet based on the sorted elements in the argument iterator.
public static <E> TreeSet<E>	createTreeSetFromSortedIterator(Iterator<? extends E> it, int size, Comparator<? super E> comparator) Creates a TreeSet based on the sorted elements in the argument iterator.
public static boolean	deepEquals(Object left, Object right) Function that checks the arguments for deep equality.
public static boolean	defaultize(Boolean value, boolean defaultvalue) Checks if the argument boxed `boolean` is `null` and returns the default value if it is.
public static byte	defaultize(Byte value, byte defaultvalue) Checks if the argument boxed `byte` is `null` and returns the default value if it is.
public static char	defaultize(Character value, char defaultvalue) Checks if the argument boxed `char` is `null` and returns the default value if it is.
public static double	defaultize(Double value, double defaultvalue) Checks if the argument boxed `double` is `null` and returns the default value if it is.
public static float	defaultize(Float value, float defaultvalue) Checks if the argument boxed `float` is `null` and returns the default value if it is.
public static int	defaultize(Integer value, int defaultvalue) Checks if the argument boxed `int` is `null` and returns the default value if it is.
public static long	defaultize(Long value, long defaultvalue) Checks if the argument boxed `long` is `null` and returns the default value if it is.
public static short	defaultize(Short value, short defaultvalue) Checks if the argument boxed `short` is `null` and returns the default value if it is.
public static boolean	equalsExcCheck(Object left, Object right) Checks if the argument objects equal.
public static <K> Comparator<? super K>	getComparator(SortedMap<K, ?> map) Gets the comparator for a sorted map.
public static <E> Comparator<? super E>	getComparator(SortedSet<E> set) Gets the comparator for a sorted set.
public static <R> R	getContainsAny(Collection<?> haystack, Iterable<R> needle) Checks if the argument haystack collection contains any element from the needle elements, and returns it if found.
public static <K, V> Entry<K, V>	getEntry(NavigableMap<K, V> map, K key) Gets the entry in a navigable map that has the specified key.
public static Class<? extends Enum<?>>	getEnumMapEnumType(EnumMap<?, ?> enummap) Gets the enumeration type of the argument EnumMap.
public static <K> K	getExactKey(NavigableMap<K, ?> map, K key) Gets the key that is present in the navigable map and equals to the specified key argument.
public static <E> E	getListElement(List<? extends E> list, int index) Gets the element of a list at the specified index.
public static <V> V	getMapValue(Map<?, V> map, Object key) Gets the value mapped to the given key in a map, if the map is non-`null`.
public static <V> V	getMapValueOrDefault(Map<?, V> map, Object key, V defaultval) Gets the value mapped to the given key in a map, or the default if the key is not present in the map or if the map is non-`null`.
public static <T> T	getOptional(Optional<? extends T> optional) Gets the value of an optional if it is non-`null`, and is present.
public static <T> T	getReference(Reference<? extends T> ref) Gets the referenced object by the argument reference, if it is non-`null`.
public static <T> T	getSupplier(Supplier<? extends T> supplier) Gets the value from a supplier, if it is non-`null`.
public static boolean	hasNonNull(Iterable<?> objects) Checks if there are any non-`null` values among the argument.
public static boolean	hasNonNull(Object... objects) Checks if there are any non-`null` values among the argument.
public static boolean	hasNull(Iterable<?> objects) Checks if there are any `null` values among the argument.
public static boolean	hasNull(Object... objects) Checks if there are any `null` values among the argument.
public static int	indexOfIterable(Iterable<?> iterable, Object object) Finds the index of the first occurrence of a given object in an iterable.
public static boolean	isFalse(Boolean b) Checks if the argument is non-`null` and represents the `false` Boolean.
public static boolean	isNaturalOrder(Comparator<?> comparator) Checks if the argument comparator represents the natural order.
public static boolean	isNullOrEmpty(CharSequence str) Checks if the argument character sequence is `null` or empty.
public static boolean	isNullOrEmpty(Iterable<?> iterable) Checks if the argument iterable is `null` or empty.
public static boolean	isNullOrEmpty(String str) Checks if the argument string is `null` or empty.
public static boolean	isNullOrEmpty(Collection<?> collection) Checks if the argument string is `null` or empty.
public static boolean	isNullOrEmpty(Map<?, ?> map) Checks if the argument string is `null` or empty.
public static boolean	isNullOrEmpty(Optional<?> optional) Checks if the argument optional is `null`, or contains no value.
public static boolean	isNullOrEmpty(byte[] array) Checks if the argument array is `null`, or empty (i.e.
public static boolean	isNullOrEmpty(char[] array) Checks if the argument array is `null`, or empty (i.e.
public static boolean	isNullOrEmpty(double[] array) Checks if the argument array is `null`, or empty (i.e.
public static boolean	isNullOrEmpty(float[] array) Checks if the argument array is `null`, or empty (i.e.
public static boolean	isNullOrEmpty(int[] array) Checks if the argument array is `null`, or empty (i.e.
public static boolean	isNullOrEmpty(long[] array) Checks if the argument array is `null`, or empty (i.e.
public static boolean	isNullOrEmpty(Object[] array) Checks if the argument array is `null`, or empty (i.e.
public static boolean	isNullOrEmpty(short[] array) Checks if the argument array is `null`, or empty (i.e.
public static boolean	isNullOrEmpty(boolean[] array) Checks if the argument array is `null`, or empty (i.e.
public static boolean	isSameClass(Object first, Object second) Checks if the argument objects are an instance of the same class.
public static <E> boolean	isSorted(Iterable<? extends E> iterable, Comparator<? super E> comparator) Checks if the argument iterable is sorted by the order specified by the given comparator.
public static <K> boolean	isSortedEntries(Iterable<? extends Entry<? extends K, ?>> entries, Comparator<? super K> comparator) Checks if the keys of the argument entry iterable is sorted by the order specified by the given comparator.
public static <E> boolean	isStrictlySorted(Iterable<? extends E> iterable, Comparator<? super E> comparator) Checks if the argument iterable is strictly sorted by the order specified by the given comparator.
public static <K> boolean	isStrictlySortedEntries(Iterable<? extends Entry<? extends K, ?>> entries, Comparator<? super K> comparator) Checks if the keys of the argument entry iterable is strictly sorted by the order specified by the given comparator.
public static boolean	isTrue(Boolean b) Checks if the argument is non-`null` and represents the `true` Boolean.
public static <LType, RType> boolean	iterablesOrderedEquals(Iterable<? extends LType> left, Iterable<? extends RType> right) Same as calling iterablesEquals`(left, right, Objects::equals`).
public static <LType, RType> boolean	iterablesOrderedEquals(Iterable<? extends LType> left, Iterable<? extends RType> right, BiPredicate<? super LType, ? super RType> comparator) Checks if the argument iterables equal by checking the equality of the elements in iteration order using the given function.
public static <K, VL, VR> void	iterateOrderedEntryIterables(Iterable<? extends Entry<? extends K, ? extends VL>> left, Iterable<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriConsumer<? super K, ? super VL, ? super VR> action) Iterates over the given iterables of map entries assuming that both of them are sorted by the specified comparator.
public static <K, VL, VR> boolean	iterateOrderedEntryIterablesBreak(Iterable<? extends Entry<? extends K, ? extends VL>> left, Iterable<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriPredicate<? super K, ? super VL, ? super VR> action) Iterates over the given iterables of map entries assuming that both of them are sorted by the specified comparator, optionally breaking the iteration.
public static <K, VL, VR> void	iterateOrderedEntryIterablesDual(Iterable<? extends Entry<? extends K, ? extends VL>> left, Iterable<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriConsumer<? super K, ? super VL, ? super VR> action) Iterates over the given iterables of map entries assuming that both of them are sorted by the specified comparator, and calling the given action for paired entries only.
public static <K, VL, VR> boolean	iterateOrderedEntryIterablesDualBreak(Iterable<? extends Entry<? extends K, ? extends VL>> left, Iterable<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriPredicate<? super K, ? super VL, ? super VR> action) Iterates over the given iterables of map entries assuming that both of them are sorted by the specified comparator, and calling the given action for paired entries only, optionally breaking the iteration.
public static <K, VL, VR> void	iterateOrderedEntryIterators(Iterator<? extends Entry<? extends K, ? extends VL>> left, Iterator<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriConsumer<? super K, ? super VL, ? super VR> action) Iterates over the given iterators of map entries assuming that both of them are sorted by the specified comparator.
public static <K, VL, VR> boolean	iterateOrderedEntryIteratorsBreak(Iterator<? extends Entry<? extends K, ? extends VL>> left, Iterator<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriPredicate<? super K, ? super VL, ? super VR> action) Iterates over the given iterators of map entries assuming that both of them are sorted by the specified comparator, optionally breaking the iteration.
public static <K, VL, VR> void	iterateOrderedEntryIteratorsDual(Iterator<? extends Entry<? extends K, ? extends VL>> left, Iterator<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriConsumer<? super K, ? super VL, ? super VR> action) Iterates over the given iterators of map entries assuming that both of them are sorted by the specified comparator, and calling the given action for paired entries only.
public static <K, VL, VR> boolean	iterateOrderedEntryIteratorsDualBreak(Iterator<? extends Entry<? extends K, ? extends VL>> left, Iterator<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriPredicate<? super K, ? super VL, ? super VR> action) Iterates over the given iterators of map entries assuming that both of them are sorted by the specified comparator, calling the action only for matching entries, optionally breaking the iteration.
public static <L extends Comparable<? super R>, R> void	iterateOrderedIterables(Iterable<? extends L> left, Iterable<? extends R> right, BiConsumer<? super L, ? super R> action) Iterates over the given iterables assuming that both of them are sorted by the natural order.
public static <L, R> void	iterateOrderedIterables(Iterable<? extends L> left, Iterable<? extends R> right, ToIntBiFunction<? super L, ? super R> comparator, BiConsumer<? super L, ? super R> action) Iterates over the given iterables assuming that both of them are sorted by the specified comparator function.
public static <L extends Comparable<? super R>, R> void	iterateOrderedIterators(Iterator<? extends L> left, Iterator<? extends R> right, BiConsumer<? super L, ? super R> action) Iterates over the given iterators assuming that both of them are sorted by the natural order.
public static <L, R> void	iterateOrderedIterators(Iterator<? extends L> lit, Iterator<? extends R> rit, ToIntBiFunction<? super L, ? super R> comparator, BiConsumer<? super L, ? super R> action) Iterates over the given iterators assuming that both of them are sorted by the specified comparator function.
public static boolean	iteratePrevUntil(ListIterator<?> it, Object obj) Moves the argument iterator backwards until an object is encountered that equals the argument.
public static <K, VL, VR> void	iterateSortedMapEntries(SortedMap<? extends K, ? extends VL> left, SortedMap<? extends K, ? extends VR> right, TriConsumer<? super K, ? super VL, ? super VR> action) Iterates over the entries of the argument sorted maps assuming that both of them are sorted by the same order.
public static <K, VL, VR> boolean	iterateSortedMapEntriesBreak(SortedMap<? extends K, ? extends VL> left, SortedMap<? extends K, ? extends VR> right, TriPredicate<? super K, ? super VL, ? super VR> action) Iterates over the entries of the argument sorted maps assuming that both of them are sorted by the same order, optionally breaking the iteration.
public static <K, VL, VR> void	iterateSortedMapEntriesDual(SortedMap<? extends K, ? extends VL> left, SortedMap<? extends K, ? extends VR> right, TriConsumer<? super K, ? super VL, ? super VR> action) Iterates over the entries of the argument sorted maps assuming that both of them are sorted by the same order, and calling the given action for paired entries only.
public static <K, VL, VR> void	iterateSortedMapEntriesDualBreak(SortedMap<? extends K, ? extends VL> left, SortedMap<? extends K, ? extends VR> right, TriPredicate<? super K, ? super VL, ? super VR> action) Iterates over the entries of the argument sorted maps assuming that both of them are sorted by the same order, and calling the given action for paired entries only, optionally breaking the iteration.
public static boolean	iterateUntil(Iterator<?> it, Object obj) Moves the argument iterator until an object is encountered that equals the argument.
public static <T> Iterator<T>	iterator(Iterable<T> iterable) Calls Iterable.iterator() on the argument if non-`null`.
public static <T> Iterator<T>	iterator(T[] array) Gets an iterator that iterates over the argument array.
public static int	listHash(Iterable<?> iterable) Calculates the hash of the elements contained in the argument based on the method specified by List.hashCode().
public static int	listHash(Iterator<?> it) Calculates the hash of the elements contained in the argument based on the method specified by List.hashCode().
public static boolean	listsEqual(List<?> first, List<?> second) Checks the argument lists for equality.
public static int	mapEntryHash(Object key, Object value) Calculates the hash of the argument key-value map entry based on the method specified by Map.Entry.hashCode().
public static int	mapEntryHash(Entry<?, ?> entry) Calculates the hash of the argument map entry based on the method specified by Map.Entry.hashCode().
public static int	mapHash(Iterable<? extends Entry<?, ?>> entryiterable) Calculates the hash of the entries contained in the argument based on the method specified by Map.hashCode().
public static int	mapHash(Iterator<? extends Entry<?, ?>> iterator) Calculates the hash of the entries contained in the argument based on the method specified by Map.hashCode().
public static int	mapHash(Map<?, ?> map) Calculates the hash of the entries contained in the argument based on the method specified by Map.hashCode().
public static <Key, LType, RType> boolean	mapOrderedEquals(Map<? extends Key, ? extends LType> left, Map<? extends Key, ? extends RType> right) Same as calling orderedMapEquals`(left, right, Objects::equals`).
public static <Key, LType, RType> boolean	mapOrderedEquals(Map<? extends Key, ? extends LType> left, Map<? extends Key, ? extends RType> right, BiPredicate<? super LType, ? super RType> comparator) Checks if the argument maps equal by checking the equality of the keys and values in iteration order using the given function.
public static String	mapToString(Map<?, ?> map) Creates a string representation of the argument map.
public static boolean	mapsEqual(Map<?, ?> first, Map<?, ?> second) Checks the argument maps for equality.
public static <E> ArrayList<E>	newArrayList(Iterable<? extends E> objects) Creates a new array list and adds each element of the argument iterable.
public static <E> ArrayList<E>	newArrayList(Collection<? extends E> objects) Creates a new array list and adds each element of the argument collection.
public static <E> ArrayList<E>	newArrayList(Collection<? extends E> firstobjects, Collection<? extends E> secondobjects) Creates a new array list and adds the elements of the first, and then the second collection.
public static <E> ArrayList<E>	newArrayList(Iterator<? extends E> objects) Creates a new array list and adds each remaining element from the argument iterator.
public static <E> ArrayList<E>	newArrayList(E... objects) Creates a new array list and adds each element of the argument array.
public static <K, V> HashMap<K, V>	newHashMap(Map<? extends K, ? extends V> map) Creates a new HashMap and initializes it with the argument objects.
public static <E> HashSet<E>	newHashSet(Iterable<? extends E> objects) Creates a new HashSet and initializes it with the argument objects.
public static <E> HashSet<E>	newHashSet(Collection<? extends E> objects) Creates a new HashSet and initializes it with the argument objects.
public static <E> HashSet<E>	newHashSet(E... objects) Creates a new HashSet and initializes it with the argument objects.
public static <K, V> IdentityHashMap<K, V>	newIdentityHashMap(Map<? extends K, ? extends V> map) Creates a new IdentityHashMap and initializes it with the argument objects.
public static <E> Set<E>	newIdentityHashSet() Creates a new identity hash set.
public static <E> Set<E>	newIdentityHashSet(Iterable<? extends E> objects) Creates a new identity hash set and initializes it with the argument objects.
public static <E> Set<E>	newIdentityHashSet(Collection<? extends E> objects) Creates a new identity hash set and initializes it with the argument objects.
public static <E> Set<E>	newIdentityHashSet(Set<? extends E> objects) Creates a new identity hash set and initializes it with the argument objects.
public static <E> Set<E>	newIdentityHashSet(E... objects) Creates a new identity hash set and initializes it with the argument objects.
public static <K, V> LinkedHashMap<K, V>	newLinkedHashMap(Map<? extends K, ? extends V> map) Creates a new LinkedHashMap and initializes it with the argument objects.
public static <E> LinkedHashSet<E>	newLinkedHashSet(Iterable<? extends E> objects) Creates a new LinkedHashSet and initializes it with the argument objects.
public static <E> LinkedHashSet<E>	newLinkedHashSet(Collection<? extends E> objects) Creates a new LinkedHashSet and initializes it with the argument objects.
public static <E> LinkedHashSet<E>	newLinkedHashSet(E... objects) Creates a new LinkedHashSet and initializes it with the argument objects.
public static <E> Set<E>	newSetFromMap(Map<E, ? super Boolean> map) Creates a new set that is backed by the argument map.
public static <K, V> TreeMap<K, V>	newTreeMap(Map<? extends K, ? extends V> map) Creates a new TreeMap and initializes it with the argument map entries.
public static <K, V> TreeMap<K, V>	newTreeMap(SortedMap<K, ? extends V> map) Creates a new TreeMap and initializes it with the argument map entries.
public static <E> TreeSet<E>	newTreeSet(Iterable<? extends E> objects) Creates a new TreeSet and initializes it with the argument objects.
public static <E> TreeSet<E>	newTreeSet(Collection<? extends E> objects) Creates a new TreeSet and initializes it with the argument objects.
public static <E> TreeSet<E>	newTreeSet(SortedSet<E> objects) Creates a new TreeSet and initializes it with the argument objects.
public static <E> TreeSet<E>	newTreeSet(E... objects) Creates a new TreeSet and initializes it with the argument objects.
public static int	nonNullObjectCount(Iterable<?> objects) Counts the number of non-`null` objects in the argument iterable.
public static int	nonNullObjectCount(Object... objects) Counts the number of non-`null` objects in the argument array.
public static <T> T	nullDefault(T first, T defaultvalue) Checks if the first argument is `null` and if it is, returns the default value.
public static <T> T	nullDefault(T test, Supplier<? extends T> defaultvalue) Checks if the first argument is `null` and if it is, returns the value supplied by the default supplier.
public static int	nullObjectCount(Iterable<?>... objects) Counts the number of `null` objects in the argument iterable.
public static int	nullObjectCount(Object... objects) Counts the number of `null` objects in the argument array.
public static <LType, RType> boolean	objectsEquals(LType left, RType right, BiPredicate<? super LType, ? super RType> comparator) Checks the argument objects for equality using the given comparator predicate.
public static <E> Iterable<E>	onceIterable(Iterator<E> iterator) Converts the argument iterator to an once iterable.
public static void	reachabilityFence(Object o) Backports Reference`.reachabilityFence(Object)` to Java 8.
public static boolean	removeAtIndex(Iterable<?> iterable, int index) Finds the object at the given index in the argument iterable, and removes it.
public static <T> T	removeFirstElement(Iterable<? extends T> iterable) Removes the first element from an iterable if present.
public static <T> T	removeFirstElementThrow(Iterable<? extends T> iterable) Removes the first element from an iterable, or throws an exception if there is no first element.
public static boolean	removeFirstOccurrence(Iterable<?> iterable, Object object) Searches for the first occurrence of an object in an iterable, and removes it.
public static <M extends SortedMap<?, ?>> M	requireComparator(M map, Comparator<?> comparator) Validation method for requiring that the argument sorted map is sorted by the given comparator.
public static <S extends SortedSet<?>> S	requireComparator(S set, Comparator<?> comparator) Validation method for requiring that the argument sorted set is sorted by the given comparator.
public static <C extends Comparator<?>> C	requireNaturalOrder(C comparator) Validation method for checking if the comparator represents the natural order.
public static <M extends SortedMap<?, ?>> M	requireNaturalOrder(M map) Validation method for checking if a sorted map is ordered by the natural order.
public static <S extends SortedSet<?>> S	requireNaturalOrder(S set) Validation method for checking if a sorted set is ordered by the natural order.
public static <E, C extends Iterable<E>> C	requireNonNullElements(C iterable) Validation method for requiring that the argument iterable contains no `null` elements.
public static <E> E[]	requireNonNullElements(E[] objects) Validation method for requiring that the argument array contains no `null` elements.
public static <K, V, M extends Map<K, V>> M	requireNonNullEntryKeyValues(M map) Validation method for requiring that the argument map contains no `null` keys or values.
public static <K, V, M extends Map<K, V>> M	requireNonNullValues(M map) Validation method for requiring that the argument map contains no `null` values.
public static <T> Comparator<T>	requireSameComparators(Comparator<T> cmp1, Comparator<?> cmp2) Validation method for ensuring that the two comparators define the same order.
public static <K> Comparator<? super K>	requireSameComparators(SortedMap<K, ?> firstmap, SortedMap<?, ?> secondmap) Validation method for ensuring that two sorted maps have the same order.
public static <E> Comparator<? super E>	requireSameComparators(SortedSet<E> firstset, SortedSet<?> secondset) Validation method for ensuring that two sorted sets have the same order.
public static <E> List<E>	reversedList(List<E> list) Gets a reversed view of the argument list.
public static int	setHash(Iterable<?> iterable) Calculates the hash of the elements contained in the argument based on the method specified by Set.hashCode().
public static int	setHash(Iterator<?> it) Calculates the hash of the elements contained in the argument based on the method specified by Set.hashCode().
public static boolean	setsEqual(Set<?> first, Set<?> second) Checks the argument sets for equality.
public static <K, V> NavigableMap<K, V>	singleValueMap(NavigableSet<K> set, V value) Creates a new navigable map view that has the same keys as the argument set, and all keys are mapped to the argument value.
public static <K, V> Map<K, V>	singleValueMap(Set<K> set, V value) Creates a new map view that has the same keys as the argument set, and all keys are mapped to the argument value.
public static <K, V> SortedMap<K, V>	singleValueMap(SortedSet<K> set, V value) Creates a new sorted map view that has the same keys as the argument set, and all keys are mapped to the argument value.
public static int	sizeOfIterable(Iterable<?> iterable) Counts the number of elements in the iterable.
public static int	sizeOfIterator(Iterator<?> it) Counts the number of remaining elements in the iterator.
public static RuntimeException	sneakyThrow(Throwable t) Sneakily throws the argument throwable.
public static <T> T[]	transformArray(T[] array, Function<? super T, ? extends T> transformer) Transforms the elements of the given array using the transformer function.
public static <T, E> Iterable<E>	transformIterable(Iterable<? extends T> iterable, Function<? super T, ? extends E> transformer) Wraps the argument iterable into a new one that creates iterators which transform the elements using the given function.
public static <T, E> Iterator<E>	transformIterator(Iterator<? extends T> iterator, Function<? super T, ? extends E> transformer) Wraps the argument iterator into a new one that transforms the elements using the given function.

Inherited methods
From: Object clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

public static final boolean[] EMPTY_BOOLEAN_ARRAY

Singleton instance of an empty boolean array.

public static final byte[] EMPTY_BYTE_ARRAY

Singleton instance of an empty byte array.

public static final char[] EMPTY_CHAR_ARRAY

Singleton instance of an empty char array.

public static final Class<?>[] EMPTY_CLASS_ARRAY

Singleton instance of an empty Class array.

public static final double[] EMPTY_DOUBLE_ARRAY

Singleton instance of an empty double array.

public static final float[] EMPTY_FLOAT_ARRAY

Singleton instance of an empty float array.

public static final int[] EMPTY_INT_ARRAY

Singleton instance of an empty int array.

public static final long[] EMPTY_LONG_ARRAY

Singleton instance of an empty long array.

public static final Object[] EMPTY_OBJECT_ARRAY

Singleton instance of an empty Object array.

public static final short[] EMPTY_SHORT_ARRAY

Singleton instance of an empty short array.

public static final StackTraceElement[] EMPTY_STACK_TRACE_ELEMENT_ARRAY

Singleton instance of an empty StackTraceElement array.

public static final String[] EMPTY_STRING_ARRAY

Singleton instance of an empty String array.

public static final Throwable[] EMPTY_THROWABLE_ARRAY

Singleton instance of an empty Throwable array.

public static <E, CollType extends Collection<? super E>> CollType addAll(CollType collection, Iterable<? extends E> objects) throws NullPointerException

Adds all the elements in the argument iterable to the specified collecion.

If the argument iterable is null, no elements are added to the collection.

EThe element type.

CollTypeThe type of the collection.

collectionThe collection.

objectsThe iterable of elements to add.

The argument collection.

NullPointerExceptionIf the collection is null. (May be only thrown when the iterable is non-null.)

public static <E, CollType extends Collection<? super E>> CollType addAll(CollType collection, Collection<? extends E> objects) throws NullPointerException

Adds all the elements in the argument collection to the specified collecion.

If the argument collection is null, no elements are added to the target collection.

EThe element type.

CollTypeThe type of the collection.

collectionThe target collection to add the elements to.

objectsThe collection of elements to add.

The target collection.

NullPointerExceptionIf the target collection is null. (May be only thrown when the source collection is non-null and non-empty.)

public static <E, CollType extends Collection<? super E>> CollType addAll(CollType collection, Iterator<? extends E> iterator) throws NullPointerException

Adds all the remaining elements in the argument iterator to the specified collecion.

If the argument iterator is null, no elements are added to the collection.

EThe element type.

CollTypeThe type of the collection.

collectionThe collection.

iteratorThe iterator of elements to add.

The argument collection.

NullPointerExceptionIf the collection is null. (May be only thrown when the iterator is non-null.)

@SafeVarargs

public static <E, CollType extends Collection<? super E>> CollType addAll(CollType collection, E... objects) throws NullPointerException

Adds all the elements in the specified iterable to the argument collecion.

If the argument array is null, no elements are added to the collection.

EThe element type.

CollTypeThe type of the collection.

collectionThe collection.

objectsThe array of elements to add.

The argument collection.

NullPointerExceptionIf the collection is null. (May be only thrown when the array is non-null and non-empty.)

public static String classNameOf(Object obj)

Gets the class name of the argument object.

If the argument is null, null is returned.

objThe object.

The class name or null if the object is null.

Class.getName()

public static <T> Class<? extends T> classOf(T object)

Gets the class of the argument if non-null.

TThe type of the argument.

objectThe object to get the class of.

The class of the object, or null if the object is null.

public static <T> Class<? extends T> classOf(T object, Class<? extends T> defaultvalue)

Gets the class of the argument if non-null, else returns a default value.

TThe type of the argument.

objectThe object to get the class of.

defaultvalueThe class to return if the object is null.

The class of the object, or the default value if the object is null.

public static Class<?>[] classOfArrayElements(Object[] array)

Gets the classes of the elements in the argument array.

This method will determine the class type of each element in the argument in the same manner as classOf(T).

arrayThe array to get the element types of.

An array of classes which correspond to the classes of each element in the array, or null if the array is null.

public static Class<?>[] classOfArrayElements(Object[] array, Class<?> defaultclass)

Gets the classes of the elements in the argument array.

This method will determine the class type of each element in the argument in the same manner as classOf(T, Class<? extends T>).

arrayThe array to get the element types of.

defaultclassThe class type to set for an element if it is null.

An array of classes which correspond to the classes of each element in the array, or null if the array is null.

public static <T> T clone(T object, Function<? super T, ? extends T> cloner) throws NullPointerException

Clones the argument object using the specified cloner function.

This method returns null, if the argument object is null, else calls the cloner function with its as the argument.

TThe type of the object.

objectThe object to clone.

clonerThe cloner function for non-null object.

The cloned object or null if the object was null, or the cloner function returned null.

NullPointerExceptionIf the cloner function is null.

public static <E, T> T[] cloneArray(E[] array, Class<T> targetcomponenttype, Function<? super E, ? extends T> cloner) throws NullPointerException

Clones the argument array to the target component type using the specified cloner function.

This method returns null if the argument array is null, else calls the cloner function for each element in the source array and puts them into a new array with the specified component type.

EThe element type of the source array.

TThe element type of the target array.

arrayThe array to clone.

targetcomponenttypeThe component type of the returned array.

clonerThe cloner function for the elements.

The cloned array or null if the object was null.

NullPointerExceptionIf the cloner function or the target component type is null.

public static <E> E[] cloneArray(E[] array, Function<? super E, ? extends E> cloner) throws NullPointerException

Clones the argument array using the specified cloner function.

This method returns null if the argument array is null, else calls the cloner function for each element in the source array and puts them into a new array.

EThe element type of the array.

arrayThe array to clone.

clonerThe cloner function for the elements.

The cloned array or null if the object was null.

NullPointerExceptionIf the cloner function is null.

public static <E> ArrayList<E> cloneArrayList(Collection<? extends E> coll)

Clones the argument collection by creating an array list that contains the same items.

This method returns null, if the argument is null.

EThe element type.

collThe collection to clone.

A newly created ArrayList or null if the argument was null.

ArrayList.ArrayList(Collection<? extends E>)

public static <E> ArrayList<E> cloneArrayList(Collection<? extends E> coll, Function<? super E, ? extends E> elementcloner) throws NullPointerException

Clones the argument collection and its elements into an array list.

This method returns null, if the argument is null.

A new ArrayList will be created, and the element cloner function will be applied to each element in the original collection. The cloned elements will be added to the new list.

EThe element type.

collThe collection to clone.

elementclonerThe element cloner function that is applied to each element.

A newly created ArrayList or null if the argument was null.

NullPointerExceptionIf the element cloner is null.

public static <E extends Enum<E>> EnumSet<E> cloneEnumSet(Class<E> enumclass, Collection<E> values)

Creates an EnumSet for the argument enum class and values.

This method can be useful when creating a clone of collections that contain enumeration values.

The enumeration class argument is required for proper operation, as in order to construct an EnumSet, the enum class is required. If the argument collection is empty, this would not be available.

EThe type of the element enums.

enumclassThe enum type.

valuesThe values to initialize the resulting enum set with.

The created enum set, or null if the argument collection is null.

public static <K, V> HashMap<K, V> cloneHashMap(Map<? extends K, ? extends V> map)

Clones the argument map by creating a hash map that contains the same entries.

This method returns null, if the argument is null.

KThe key type.

VThe value type.

mapThe map to clone.

A newly created HashMap or null if the argument was null.

HashMap.HashMap(Map<? extends K, ? extends V>)

public static <K, V> LinkedHashMap<K, V> cloneLinkedHashMap(Map<? extends K, ? extends V> map)

Clones the argument map by creating a linked hash map that contains the same entries.

This method returns null, if the argument is null.

KThe key type.

VThe value type.

mapThe map to clone.

A newly created LinkedHashMap or null if the argument was null.

LinkedHashMap.LinkedHashMap(Map<? extends K, ? extends V>)

public static <E> LinkedHashSet<E> cloneLinkedHashSet(Collection<? extends E> coll)

Clones the argument collection by creating a new LinkedHashSet.

The LinkedHashSet is initialized using the LinkedHashSet(Collection<E>) constructor.

EThe element type.

collThe collection to clone.

A newly created LinkedHashSet or null if the argument was null.

public static <K, V> TreeMap<K, V> cloneTreeMap(Map<? extends K, ? extends V> map)

Clones the argument map by creating a tree map that contains the same entries.

This method returns null, if the argument is null.

KThe key type.

VThe value type.

mapThe map to clone.

A newly created TreeMap or null if the argument was null.

TreeMap.TreeMap(Map<? extends K, ? extends V>)

public static <K, V> TreeMap<K, V> cloneTreeMap(Map<? extends K, ? extends V> map, Function<? super K, ? extends K> keycloner, Function<? super V, ? extends V> valuecloner) throws NullPointerException

Clones the argument map and its entries into a tree map.

This method returns null, if the argument is null.

A new TreeMap will be created, and the key and value cloner functions will be applied to each entry in the original map. The cloned entries will be put into the new map.

KThe key type.

VThe value type.

mapThe map to clone.

keyclonerThe key cloner function that is applied to each key.

valueclonerThe value cloner function that is applied to each value.

A newly created TreeMap or null if the argument was null.

NullPointerExceptionIf the key or value cloner is null.

public static <K, V> TreeMap<K, V> cloneTreeMap(SortedMap<K, ? extends V> map)

Clones the argument sorted map by creating a tree map with the same order and entries.

This method returns null, if the argument is null.

KThe key type.

VThe value type.

mapThe map to clone.

A newly created TreeMap or null if the argument was null.

TreeMap.TreeMap(SortedMap<K, ? extends V>)

public static <E> TreeSet<E> cloneTreeSet(Collection<? extends E> coll)

Clones the argument collection by creating an tree set that contains the same items.

This method returns null, if the argument is null.

EThe element type.

collThe collection to clone.

A newly created TreeSet or null if the argument was null.

TreeSet.TreeSet(Collection<? extends E>)

public static <E> TreeSet<E> cloneTreeSet(SortedSet<E> coll)

Clones the argument sorted set by creating an tree set with the same order and items.

This method returns null, if the argument is null.

EThe element type.

collThe collection to clone.

A newly created TreeSet or null if the argument was null.

public static <LType, RType> boolean collectionOrderedEquals(Collection<? extends LType> left, Collection<? extends RType> right)

Same as calling collectionEquals(left, right, Objects::equals).

LTypeThe element types of the first collection.

RTypeThe element types of the second collection.

leftThe first collection.

rightThe second collection.

true if the collections are considered to be equal.

public static <LType, RType> boolean collectionOrderedEquals(Collection<? extends LType> left, Collection<? extends RType> right, BiPredicate<? super LType, ? super RType> comparator) throws NullPointerException

Checks if the argument collections equal by checking the equality of the elements in iteration order using the given function.

Note: this method is not suitable for checking the equality of unordered collections like HashSet.

If the collections have different sizes, this method will return false.

The method handles nullability of the arguments.

This method differs from iterablesOrderedEquals(Iterable<? extends LType>, Iterable<? extends RType>, BiPredicate<? super LType, ? super RType>) only by checking the size equality before starting to iterate over the collections. This can result in faster determination if inequality. Callers should keep this in mind when passing arguments that provide a Collection.size() method which has greater complexity than O(1) (E.g. some concurrent collections may do this).

Example usage:

 ObjectUtils.collectionEquals(coll1, coll2, Objects::equals);

LTypeThe element types of the first collection.

RTypeThe element types of the second collection.

leftThe first collection.

rightThe second collection.

comparatorThe function to determine if two elements are equal.

true if the collections are considered to be equal.

NullPointerExceptionIf the comparator function is null.

public static String collectionToString(Iterable<?> elements)

Creates a string representation of the argument iterable.

Each element in the argument will be displayed in a comma separated list between square brackets. ([])

The method creates a string representation of the iterable that is semantically same as the usual collection representations.

elementsThe elements.

The string representation of the iterable.

AbstractCollection.toString()

public static <LType, RType> int compareArrays(LType[] left, RType[] right, ToIntBiFunction<? super LType, ? super RType> comparator) throws NullPointerException

Comparison function for comparing the elements of arrays.

This function will iterate over the elements of the argument arrays and compare them after each other. Each element is going to be compared to the element at the same index in the other array.

The argument comparator works the same way as Comparator, but takes elements with different types as argument. If the comparator is null, the elements are compared by the natural order of theirs.

The comparison function finishes early, if it finds non-equal elements, in which case the function will return the result of the first mismatching elements.

If all checked elements are equal, then the shorter arrays will be ordered first if they have different lengths.

The method will only check elements up to the length of the shorter array.

LTypeThe left array element type.

RTypeThe right array element type.

leftThe left array.

rightThe right array.

comparatorThe comparator for the elements.

The comparison result.

NullPointerExceptionIf any of the arguments are null.

Comparable.compareTo(T)

public static <LType, RType> int compareIterables(Iterable<? extends LType> left, Iterable<? extends RType> right, ToIntBiFunction<? super LType, ? super RType> comparator) throws NullPointerException

Comparison function for comparing elements of iterables.

Works the same ways as compareIterators(Iterator<? extends LType>, Iterator<? extends RType>, ToIntBiFunction<? super LType, ? super RType>), but the iterators are instantiated in this function.

Same as:

 compareIterators(comparables1.iterator(), comparables2.iterator(), comparator);

LTypeThe left iterable element type.

RTypeThe right iterable element type.

leftThe left iterable of comparables.

rightThe right iterable of comparables.

comparatorThe comparator for the elements.

The comparison result.

NullPointerExceptionIf any of the arguments are null.

Comparable.compareTo(T)

public static <LType, RType> int compareIterators(Iterator<? extends LType> left, Iterator<? extends RType> right, ToIntBiFunction<? super LType, ? super RType> comparator) throws NullPointerException

Comparison function for comparing iterators.

This function will iterate over both iterators simultaneously and compare each pair of elements accordingly.

The argument comparator works the same way as Comparator, but takes elements with different types as argument. If the comparator is null, the elements are compared by the natural order of theirs.

If a mismatching element is found, the result of that comparison is returned from the function.

If one of the iterator has no more elements, that iterator will be ordered first. I.e. the shorter iterators are ordered first.

If neither iterators have next elements after all comparisons, 0 is returned.

LTypeThe left iterator element type.

RTypeThe right iterator element type.

leftThe left iterator.

rightThe right iterator.

comparatorThe comparator for the elements.

The comparison result.

NullPointerExceptionIf any of the arguments are null.

Comparable.compareTo(T)

public static <T extends Comparable<? super T>> int compareNullsFirst(T l, T r)

Comparator function that sorts non-null arguments by natural order, else the null values first.

TThe type of the compared objects.

lThe left object.

rThe right object.

The comparison result.

Comparator.compare(T, T)

Functionals.nullsFirstNaturalComparator()

public static <T extends Comparable<? super T>> int compareNullsLast(T l, T r)

Comparator function that sorts non-null arguments by natural order, else the null values last.

lThe left object.

rThe right object.

The comparison result.

Comparator.compare(T, T)

Functionals.nullsLastNaturalComparator()

public static <LKey, RKey, LType, RType> int compareOrderedMaps(Map<? extends LKey, ? extends LType> left, Map<? extends RKey, ? extends RType> right, ToIntBiFunction<? super LKey, ? super RKey> keycomparator, ToIntBiFunction<? super LType, ? super RType> valuecomparator) throws NullPointerException

Comparison function for comparing maps based on their iteration order and values.

Note: this method is not suitable for comparing unordered maps like HashMap.

This method will iterate over the arguments maps and compare the keys of their entries. If the key comparison yields a non-zero result, it is returned as the comparion result of the function. If the keys compare to be equal, the values of the maps are compared using the value comparator argument. If the value comparions yields non-zero result, it is returned as the result of the function. If they equal, the next entry will be processed the same way.

When there are no more entries in either of the maps, the one that has less entries will be ordered first. If both maps have the same length, and all of their entries compare to be equal, this function will return 0 as the comparison result.

This method is suitable for comparing maps only, if the maps have a deterministic iteration order. It is most suitable for sorted maps (E.g. TreeMap) or maps that have a predictable iteration order (E.g. LinkedHashMap).

LKeyThe key type of the left map.

RKeyThe key type of the right map.

LTypeThe value type of the left map.

RTypeThe value type of the right map.

leftThe left map.

rightThe right map.

keycomparatorThe comparator function for comparing the keys of the maps.

valuecomparatorThe comparator function for the values of the maps.

The comparison result. 0 if the maps compare to be equal, negative if the left map is ordered first, positive if the right map is ordered first.

NullPointerExceptionIf any of the arguments are null.

public static <Key, LType, RType> int compareOrderedMaps(SortedMap<? extends Key, ? extends LType> left, SortedMap<? extends Key, ? extends RType> right, ToIntBiFunction<? super LType, ? super RType> valuecomparator) throws NullPointerException, IllegalArgumentException

Comparison function for comparing sorted maps with the same ordering.

This function works the same way as compareOrderedMaps(Map<? extends LKey, ? extends LType>, Map<? extends RKey, ? extends RType>, ToIntBiFunction<? super LKey, ? super RKey>, ToIntBiFunction<? super LType, ? super RType>), but determines the key comparator based on the comparators of the argument maps.

KeyThe key type of the maps.

LTypeThe value type of the left map.

RTypeThe value type of the right map.

leftThe left map.

rightThe right map.

valuecomparatorThe comparator function for the values of the maps.

The comparison result. 0 if the maps compare to be equal, negative if the left map is ordered first, positive if the right map is ordered first.

NullPointerExceptionIf any of the arguments are null.

IllegalArgumentExceptionIf the maps are ordered differently.

requireSameComparators(SortedMap<K, ?>, SortedMap<?, ?>)

public static <E> int compareOrderedSets(SortedSet<? extends E> left, SortedSet<? extends E> right) throws NullPointerException, IllegalArgumentException

Comparison function for comparing sorted sets with the same ordering.

This function works the same way as compareIterables(Iterable<? extends LType>, Iterable<? extends RType>, ToIntBiFunction<? super LType, ? super RType>), but determines the element comparator based on the comparators of the maps.

EThe element type.

leftThe left set.

rightThe right set.

The comparison result. 0 if the maps compare to be equal, negative if the left map is ordered first, positive if the right map is ordered first.

NullPointerExceptionIf any of the arguments are null.

IllegalArgumentExceptionIf the sets are ordered differently.

requireSameComparators(SortedSet<E>, SortedSet<?>)

public static boolean contains(Iterable<?> iterable, Object object)

Checks if the argument iterable contains the specified object.

This method iterates over the iterable and searches for the specified object. Object.equals(Object) is to check equality.

iterableThe iterable.

objectThe object.

true if the iterable is non-null and the object was found.

public static boolean contains(Collection<?> collection, Object object)

Checks if the argument collection is non-null and contains the given object.

This method checks if the collection is non-null, and if so, calls Collection.contains(Object) on it with the given object.

collectionThe collection.

objectThe object.

If the argument collection contains the object.

public static boolean containsAny(Collection<?> haystack, Iterable<?> needle) throws NullPointerException

Checks if the argument haystack collection contains any element from the needle elements.

The method will iterate over the needle objects and check if it is contained in the argument haystack. If the needle is found, true is returned.

If the haystack argument is null, false is returned.

haystackThe haystack collection.

needleThe needle iterable to search for.

true if a needle object was found.

NullPointerExceptionIf the needle argument is null.

public static boolean containsAny(Collection<?> haystack, Iterator<?> needleit) throws NullPointerException

Checks if the argument haystack collection contains any element from the needle iterator.

The method will iterate over the needle iterator and check if it an element is contained in the argument haystack. If the needle is found, true is returned.

If the haystack argument is null, false is returned.

haystackThe haystack collection.

needleitThe needle iterator to search for the elements.

true if a needle object was found.

NullPointerExceptionIf the needle argument is null.

public static boolean containsAnyKey(Map<?, ?> haystack, Iterable<?> needle) throws NullPointerException

Checks if the argument haystack map contains any key from the needle elements.

If the haystack argument is null, false is returned.

haystackThe map.

needleThe keys to search for.

true if any needle element is present as a key in the haystack map.

NullPointerExceptionIf the needle argument is null.

public static boolean containsAnyValue(Map<?, ?> haystack, Iterable<?> needle) throws NullPointerException

Checks if the argument haystack map contains any value from the needle elements.

If the haystack argument is null, false is returned.

haystackThe map.

needleThe values to search for.

true if any needle element is present as a value in the haystack map.

NullPointerExceptionIf the needle argument is null.

public static boolean containsKey(Map<?, ?> map, Object object)

Checks if the argument map contains a key for the given object.

mapThe map.

objectThe object to check.

true if the map is non-null and contains a key for the object.

Map.containsKey(Object)

public static boolean containsValue(Map<?, ?> map, Object object)

Checks if the argument map contains a value for the given object.

mapThe map.

objectThe object to check.

true if the map is non-null and contains a value for the object.

Map.containsValue(Object)

public static <K, V> ConcurrentSkipListMap<K, V> createConcurrentSkipListMapFromSortedIterator(Iterator<? extends Entry<? extends K, ? extends V>> it) throws NullPointerException

Creates a ConcurrentSkipListMap based on the sorted entries in the argument iterator.

The entries iterated by the iterator must be stricly ordered by natural order.

The above requirement is not checked by this function. Violating it will result in the returned map not working properly.

Same as:

 createConcurrentSkipListMapFromSortedIterator(it, null);

KThe key type.

VThe value type.

itThe iterator for the entries.

The created map that contains the entries in the iterator.

NullPointerExceptionIf the iterator is null.

public static <K, V> ConcurrentSkipListMap<K, V> createConcurrentSkipListMapFromSortedIterator(Iterator<? extends Entry<? extends K, ? extends V>> it, Comparator<? super K> comparator) throws NullPointerException

Creates a ConcurrentSkipListMap based on the sorted entries in the argument iterator.

The entries iterated by the iterator must be stricly ordered by the argument comparator.

The above requirement is not checked by this function. Violating it will result in the returned map not working properly.

KThe key type.

VThe value type.

itThe iterator for the entries.

comparatorThe comparator defining the order of the entries or null to use the natural order.

The created map that contains the entries in the iterator.

NullPointerExceptionIf the iterator is null.

public static <E> ConcurrentSkipListSet<E> createConcurrentSkipListSetFromSortedIterator(Iterator<? extends E> it) throws NullPointerException

Creates a ConcurrentSkipListSet based on the sorted elements in the argument iterator.

The elements iterated by the iterator must be stricly ordered by natural order.

The above requirements are not checked by this function. Violating the above requirements will result in the returned set not working properly.

Same as:

 createConcurrentSkipListSetFromSortedIterator(it, null);

EThe element type.

itThe iterator for the elements.

The created set that contains the elements in the iterator.

NullPointerExceptionIf the iterator is null.

saker.util 0.8.1

public static <E> ConcurrentSkipListSet<E> createConcurrentSkipListSetFromSortedIterator(Iterator<? extends E> it, Comparator<? super E> comparator) throws NullPointerException

Creates a ConcurrentSkipListSet based on the sorted elements in the argument iterator.

The elements iterated by the iterator must be stricly ordered by the argument comparator.

The above requirements are not checked by this function. Violating the above requirements will result in the returned set not working properly.

EThe element type.

itThe iterator for the elements.

comparatorThe comparator defining the order of the elements or null to use the natural order.

The created set that contains the elements in the iterator.

NullPointerExceptionIf the iterator is null.

saker.util 0.8.1

public static <K, V> NavigableMap<K, V> createImmutableNavigableMapFromSortedIterator(Iterator<? extends Entry<? extends K, ? extends V>> it, int size) throws NullPointerException, NoSuchElementException

Creates an immutable NavigableMap based on the sorted entries in the argument iterator.

The entries iterated by the iterator must be stricly ordered by natural order.

The number of entries iterated over must be the same as the size argument.

The sortedness requirement is not checked by this function. Violating that requirement will result in the returned map not working properly.

This method consumes size number of elements from the iterator. If it contains more elements, those elements will be still retrievable from the iterator after this method returns.

KThe key type.

VThe value type.

itThe iterator for the entries.

sizeThe number of elements remaining in the iterator.

The created map that contains the entries in the iterator.

NullPointerExceptionIf the iterator is null or any of the entries it returns is null.

NoSuchElementExceptionIf there are fewer elements in the iterator than the specified size.

public static <K, V> NavigableMap<K, V> createImmutableNavigableMapFromSortedIterator(Iterator<? extends Entry<? extends K, ? extends V>> it, int size, Comparator<? super K> comparator) throws NullPointerException, NoSuchElementException

Creates an immutable NavigableMap based on the sorted entries in the argument iterator.

The entries iterated by the iterator must be stricly ordered by the argument comparator.

The number of entries iterated over must be the same as the size argument.

The sortedness requirement is not checked by this function. Violating that requirement will result in the returned map not working properly.

This method consumes size number of elements from the iterator. If it contains more elements, those elements will be still retrievable from the iterator after this method returns.

KThe key type.

VThe value type.

itThe iterator for the entries.

sizeThe number of elements remaining in the iterator.

comparatorThe comparator defining the order of the entries or null to use the natural order.

The created map that contains the entries in the iterator.

NullPointerExceptionIf the iterator is null or any of the entries it returns is null.

NoSuchElementExceptionIf there are fewer elements in the iterator than the specified size.

public static <K, V> TreeMap<K, V> createTreeMapFromSortedIterator(Iterator<? extends Entry<? extends K, ? extends V>> it, int size) throws NullPointerException

Creates a TreeMap based on the sorted entries in the argument iterator.

The entries iterated by the iterator must be stricly ordered by natural order.

The number of entries iterated over must be the same as the size argument.

The above requirements are not checked by this function. Violating the above requirements will result in the returned map not working properly.

Same as:

 createTreeMapFromSortedIterator(it, size, null);

KThe key type.

VThe value type.

itThe iterator for the entries.

sizeThe number of entries remaining in the iterator.

The created map that contains the entries in the iterator.

NullPointerExceptionIf the iterator is null.

public static <K, V> TreeMap<K, V> createTreeMapFromSortedIterator(Iterator<? extends Entry<? extends K, ? extends V>> it, int size, Comparator<? super K> comparator) throws NullPointerException

Creates a TreeMap based on the sorted entries in the argument iterator.

The entries iterated by the iterator must be stricly ordered by the argument comparator.

The number of entries iterated over must be the same as the size argument.

The above requirements are not checked by this function. Violating the above requirements will result in the returned map not working properly.

KThe key type.

VThe value type.

itThe iterator for the entries.

sizeThe number of elements remaining in the iterator.

comparatorThe comparator defining the order of the entries or null to use the natural order.

The created map that contains the entries in the iterator.

NullPointerExceptionIf the iterator is null.

public static <E> TreeSet<E> createTreeSetFromSortedIterator(Iterator<? extends E> it, int size) throws NullPointerException

Creates a TreeSet based on the sorted elements in the argument iterator.

The elements iterated by the iterator must be stricly ordered by natural order.

The number of elements iterated over must be the same as the size argument.

The above requirements are not checked by this function. Violating the above requirements will result in the returned set not working properly.

Same as:

 createTreeSetFromSortedIterator(it, size, null);

EThe element type.

itThe iterator for the elements.

sizeThe number of elements remaining in the iterator.

The created set that contains the elements in the iterator.

NullPointerExceptionIf the iterator is null.

public static <E> TreeSet<E> createTreeSetFromSortedIterator(Iterator<? extends E> it, int size, Comparator<? super E> comparator) throws NullPointerException

Creates a TreeSet based on the sorted elements in the argument iterator.

The elements iterated by the iterator must be stricly ordered by the argument comparator.

The number of elements iterated over must be the same as the size argument.

The above requirements are not checked by this function. Violating the above requirements will result in the returned set not working properly.

EThe element type.

itThe iterator for the elements.

sizeThe number of elements remaining in the iterator.

comparatorThe comparator defining the order of the elements or null to use the natural order.

The created set that contains the elements in the iterator.

NullPointerExceptionIf the iterator is null.

public static boolean deepEquals(Object left, Object right)

Function that checks the arguments for deep equality.

If at least one argument is not an array, then they will be simply compared using Object.equals(Object).

When both arguments are arrays, they will be checked for deep equality for each of their elements. This method handles if the arrays have primitive component types. If they have reference component types then each of the elements will be compared by deep equality accordingly.

This method works similarly to Arrays.deepEquals(Object[], Object[]), but handles the case when the objects are not array to begin with.

leftThe first object.

rightThe second object.

true if the two objects equal.

public static boolean defaultize(Boolean value, boolean defaultvalue)

Checks if the argument boxed boolean is null and returns the default value if it is.

valueThe boolean.

defaultvalueThe default value to return if the boxed primitive is null.

The value of the Boolean argument if non-null, else the default argument.

public static byte defaultize(Byte value, byte defaultvalue)

Checks if the argument boxed byte is null and returns the default value if it is.

valueThe byte.

defaultvalueThe default value to return if the boxed primitive is null.

The value of the Byte argument if non-null, else the default argument.

public static char defaultize(Character value, char defaultvalue)

Checks if the argument boxed char is null and returns the default value if it is.

valueThe char.

defaultvalueThe default value to return if the boxed primitive is null.

The value of the Character argument if non-null, else the default argument.

public static double defaultize(Double value, double defaultvalue)

Checks if the argument boxed double is null and returns the default value if it is.

valueThe double.

defaultvalueThe default value to return if the boxed primitive is null.

The value of the Double argument if non-null, else the default argument.

public static float defaultize(Float value, float defaultvalue)

Checks if the argument boxed float is null and returns the default value if it is.

valueThe float.

defaultvalueThe default value to return if the boxed primitive is null.

The value of the Float argument if non-null, else the default argument.

public static int defaultize(Integer value, int defaultvalue)

Checks if the argument boxed int is null and returns the default value if it is.

valueThe int.

defaultvalueThe default value to return if the boxed primitive is null.

The value of the Integer argument if non-null, else the default argument.

public static long defaultize(Long value, long defaultvalue)

Checks if the argument boxed long is null and returns the default value if it is.

valueThe long.

defaultvalueThe default value to return if the boxed primitive is null.

The value of the Long argument if non-null, else the default argument.

public static short defaultize(Short value, short defaultvalue)

Checks if the argument boxed short is null and returns the default value if it is.

valueThe short.

defaultvalueThe default value to return if the boxed primitive is null.

The value of the Short argument if non-null, else the default argument.

public static boolean equalsExcCheck(Object left, Object right)

Checks if the argument objects equal.

If the Object.equals(Object) method throws a RuntimeException, false is returned.

leftThe first object.

rightThe second object.

true if the objects equal and no exception was thrown.

public static <K> Comparator<? super K> getComparator(SortedMap<K, ?> map) throws NullPointerException

Gets the comparator for a sorted map.

If the map is sorted by natural order (i.e. SortedMap.comparator() returns null), Comparator.naturalOrder() is returned.

KThe key type of the map.

mapThe sorted map.

The comparator.

NullPointerExceptionIf the map is null.

public static <E> Comparator<? super E> getComparator(SortedSet<E> set) throws NullPointerException

Gets the comparator for a sorted set.

If the set is sorted by natural order (i.e. SortedSet.comparator() returns null), Comparator.naturalOrder() is returned.

EThe element type of the set.

setThe sorted set.

The comparator.

NullPointerExceptionIf the set is null.

public static <R> R getContainsAny(Collection<?> haystack, Iterable<R> needle) throws NullPointerException

Checks if the argument haystack collection contains any element from the needle elements, and returns it if found.

The method will iterate over the needle objects and check if it is contained in the argument haystack. If the needle is found, it is returned.

If no needles are found, null is returned. Note that if any needle object is null, a return value of null can mean either that it was found or that it was not.

If the haystack argument is null, null is returned.

haystackThe haystack collection.

needleThe needle iterable to search for.

An object from the needle iterable if it was found, or null if none was found.

NullPointerExceptionIf the needle argument is null.

public static <K, V> Entry<K, V> getEntry(NavigableMap<K, V> map, K key)

Gets the entry in a navigable map that has the specified key.

The entry is located by taking the floor entry for the key, and comparing the key of the resulted entry to the argument. If they match, it is returned.

KThe key type.

VThe value type.

mapThe map.

keyThe entry key to search for.

The found entry or null if the map is null, or not found.

public static Class<? extends Enum<?>> getEnumMapEnumType(EnumMap<?, ?> enummap) throws UnsupportedOperationException

Gets the enumeration type of the argument EnumMap.

The method will retrieve the first key of the map and return the enum class of it. The method handles if the enum key is an anonymous inner class, and returns the enclosing enumeration type appropriately.

If the argument map is empty, the method will attempt to serialize the argument map to an ObjectOutputStream. It will intercept the type serialization and will return the found enum type. It is strongly recommended that the argument has the type EnumMap, and is not a subclass of it. This method is somewhat a hack, but no EnumMap implementation has failed with it yet, and is not expected to. If the enum type fails to be detected, an UnsupportedOperationException is thrown.

enummapThe enum map.

The enum class type or null if the argument is null.

UnsupportedOperationExceptionIf the enum type detection failed. (Usually never happens.)

public static <K> K getExactKey(NavigableMap<K, ?> map, K key)

Gets the key that is present in the navigable map and equals to the specified key argument.

The key is located by resolving the floor key for the argument key, and comparing it to the argument. If they match, it is returned.

KThe key type.

mapThe map.

keyThe key to search for.

The found key or null if the map is null, or not found.

public static <E> E getListElement(List<? extends E> list, int index)

Gets the element of a list at the specified index.

If the list is null, or the index is out of range, null is returned.

If the list is concurrently modified while this method is called, the possible IndexOutOfBoundsException is relayed to the caller. (This is usually not an issue.)

EThe element type.

listThe list to get the element of.

indexThe index to get the element at.

The element at the given index or null if there's none.

public static <V> V getMapValue(Map<?, V> map, Object key)

Gets the value mapped to the given key in a map, if the map is non-null.

This method simply calls Map.get(Object) if the map is non-null.

VThe value type of the map.

mapThe map.

keyThe key.

The value mapped to the key, or null if the map is null, no mapping is present, or the key is mapped to null.

public static <V> V getMapValueOrDefault(Map<?, V> map, Object key, V defaultval)

Gets the value mapped to the given key in a map, or the default if the key is not present in the map or if the map is non-null.

This method simply calls Map.getOrDefault(Object, V) if the map is non-null. If it's null, the default value is returned.

VThe value type of the map.

mapThe map.

keyThe key.

defaultvalThe default value.

The value mapped to the key, or the default value if the map is null or no mapping is present.

public static <T> T getOptional(Optional<? extends T> optional)

Gets the value of an optional if it is non-null, and is present.

TThe value type.

optionalThe optional.

The value of the optional, or null if it is not present, or the optional is null.

Optional.isPresent()

public static <T> T getReference(Reference<? extends T> ref)

Gets the referenced object by the argument reference, if it is non-null.

This method simply calls Reference.get() if the reference is non-null.

TThe type of the referenced object.

refThe reference.

The referenced object, or null if the reference is null.

public static <T> T getSupplier(Supplier<? extends T> supplier)

Gets the value from a supplier, if it is non-null.

This method simply calls Supplier.get() if the supplier is non-null.

TThe type of the supplied value.

supplierThe supplier.

The result of Supplier.get() or null if the supplier is null.

public static boolean hasNonNull(Iterable<?> objects)

Checks if there are any non-null values among the argument.

If the argument iterable is null, false is returned.

objectsThe objects to examine.

true if there's at least one non-null element in the argument.

public static boolean hasNonNull(Object... objects)

Checks if there are any non-null values among the argument.

If the argument array is null, false is returned.

objectsThe objects to examine.

true if there's at least one non-null element in the argument.

public static boolean hasNull(Iterable<?> objects)

Checks if there are any null values among the argument.

If the argument iterable is null, false is returned.

objectsThe objects to examine.

true if there's at least one null element in the argument.

public static boolean hasNull(Object... objects)

Checks if there are any null values among the argument.

If the argument array is null, false is returned.

objectsThe objects to examine.

true if there's at least one null element in the argument.

public static int indexOfIterable(Iterable<?> iterable, Object object) throws NullPointerException

Finds the index of the first occurrence of a given object in an iterable.

The object will be compared using Object.equals(Object).

iterableThe iterable to search in.

objectThe object to search for.

The index at which the object was found, or -1 if not found.

NullPointerExceptionIf the iterable is null.

public static boolean isFalse(Boolean b)

Checks if the argument is non-null and represents the false Boolean.

bThe boolean.

true if the argument is the false boolean.

public static boolean isNaturalOrder(Comparator<?> comparator)

Checks if the argument comparator represents the natural order.

comparatorThe comparator

true if the argument comparator is null or equals to the natural order comparator.

public static boolean isNullOrEmpty(CharSequence str)

Checks if the argument character sequence is null or empty.

The emptiness is determined using the length of the sequence.

strThe char sequence.

true if the argument is null or empty.

public static boolean isNullOrEmpty(Iterable<?> iterable)

Checks if the argument iterable is null or empty.

This method includes creating an iterator for the given iterable.

iterableThe iterable.

true if the argument is null or empty.

public static boolean isNullOrEmpty(String str)

Checks if the argument string is null or empty.

strThe string.

true if the argument is null or empty.

public static boolean isNullOrEmpty(Collection<?> collection)

Checks if the argument string is null or empty.

collectionThe collection.

true if the argument is null or empty.

public static boolean isNullOrEmpty(Map<?, ?> map)

Checks if the argument string is null or empty.

mapThe map.

true if the argument is null or empty.

public static boolean isNullOrEmpty(Optional<?> optional)

Checks if the argument optional is null, or contains no value.

optionalThe optional.

true if the argument is null, or Optional.isPresent() is false.

public static boolean isNullOrEmpty(byte[] array)

Checks if the argument array is null, or empty (i.e. has a length of 0).

arrayThe array.

true if the argument is null or empty.

public static boolean isNullOrEmpty(char[] array)

Checks if the argument array is null, or empty (i.e. has a length of 0).

arrayThe array.

true if the argument is null or empty.

public static boolean isNullOrEmpty(double[] array)

Checks if the argument array is null, or empty (i.e. has a length of 0).

arrayThe array.

true if the argument is null or empty.

public static boolean isNullOrEmpty(float[] array)

Checks if the argument array is null, or empty (i.e. has a length of 0).

arrayThe array.

true if the argument is null or empty.

public static boolean isNullOrEmpty(int[] array)

Checks if the argument array is null, or empty (i.e. has a length of 0).

arrayThe array.

true if the argument is null or empty.

public static boolean isNullOrEmpty(long[] array)

Checks if the argument array is null, or empty (i.e. has a length of 0).

arrayThe array.

true if the argument is null or empty.

public static boolean isNullOrEmpty(Object[] array)

Checks if the argument array is null, or empty (i.e. has a length of 0).

arrayThe array.

true if the argument is null or empty.

public static boolean isNullOrEmpty(short[] array)

Checks if the argument array is null, or empty (i.e. has a length of 0).

arrayThe array.

true if the argument is null or empty.

public static boolean isNullOrEmpty(boolean[] array)

Checks if the argument array is null, or empty (i.e. has a length of 0).

arrayThe array.

true if the argument is null or empty.

public static boolean isSameClass(Object first, Object second)

Checks if the argument objects are an instance of the same class.

The class of the arguments will be retrieved, and compared for equality.

If both of the arguments are null, true will be returned. If only one of the arguments are null, false is returned.

firstThe first object.

secondThe second object.

true if they are an instance of the same class.

public static <E> boolean isSorted(Iterable<? extends E> iterable, Comparator<? super E> comparator)

Checks if the argument iterable is sorted by the order specified by the given comparator.

If the comparator is null, the natural order is checked.

This method checks for weak ordering, meaning that if two consecutive elements compare to be equal, the iterable is still considered to be sorted.

EThe type of the elements.

iterableThe iterable.

comparatorThe comparator.

true if the elements in the iterable are sorted.

isStrictlySorted(Iterable<? extends E>, Comparator<? super E>)

public static <K> boolean isSortedEntries(Iterable<? extends Entry<? extends K, ?>> entries, Comparator<? super K> comparator)

Checks if the keys of the argument entry iterable is sorted by the order specified by the given comparator.

If the comparator is null, the natural order is checked.

This method checks for weak ordering, meaning that if two consecutive keys compare to be equal, the iterable is still considered to be sorted.

KThe type of the keys.

entriesThe iterable of entries to examine.

comparatorThe comparator.

true if the keys in the entry iterable are sorted.

isStrictlySortedEntries(Iterable<? extends Entry<? extends K, ?>>, Comparator<? super K>)

public static <E> boolean isStrictlySorted(Iterable<? extends E> iterable, Comparator<? super E> comparator)

Checks if the argument iterable is strictly sorted by the order specified by the given comparator.

If the comparator is null, the natural order is checked.

This method checks for strict ordering, meaning that if two consecutive elements compare to be equal, the iterable is not considered to be sorted.

EThe type of the elements.

iterableThe iterable.

comparatorThe comparator.

true if the elements in the iterable are strictly sorted.

isSorted(Iterable<? extends E>, Comparator<? super E>)

public static <K> boolean isStrictlySortedEntries(Iterable<? extends Entry<? extends K, ?>> entries, Comparator<? super K> comparator)

Checks if the keys of the argument entry iterable is strictly sorted by the order specified by the given comparator.

If the comparator is null, the natural order is checked.

This method checks for strict ordering, meaning that if two consecutive keys compare to be equal, the iterable is not considered to be sorted.

KThe type of the keys.

entriesThe iterable of entries to examine.

comparatorThe comparator.

true if the keys in the entry iterable are stricly sorted.

isSortedEntries(Iterable<? extends Entry<? extends K, ?>>, Comparator<? super K>)

public static boolean isTrue(Boolean b)

Checks if the argument is non-null and represents the true Boolean.

bThe boolean.

true if the argument is the true boolean.

public static <LType, RType> boolean iterablesOrderedEquals(Iterable<? extends LType> left, Iterable<? extends RType> right)

Same as calling iterablesEquals(left, right, Objects::equals).

LTypeThe element types of the first iterable.

RTypeThe element types of the second iterable.

leftThe first iterable.

rightThe second iterable.

true if the iterables are considered to be equal.

public static <LType, RType> boolean iterablesOrderedEquals(Iterable<? extends LType> left, Iterable<? extends RType> right, BiPredicate<? super LType, ? super RType> comparator) throws NullPointerException

Checks if the argument iterables equal by checking the equality of the elements in iteration order using the given function.

Note: this method is not suitable for checking the equality of unordered collections like HashSet.

If the iterables have different sizes, this method will return false.

The method handles nullability of the arguments.

Example usage:

 ObjectUtils.collectionEquals(iterable1, iterable2, Objects::equals);

LTypeThe element types of the first iterable.

RTypeThe element types of the second iterable.

leftThe first iterable.

rightThe second iterable.

comparatorThe function to determine if two elements are equal.

true if the iterables are considered to be equal.

NullPointerExceptionIf the comparator function is null.

public static <K, VL, VR> void iterateOrderedEntryIterables(Iterable<? extends Entry<? extends K, ? extends VL>> left, Iterable<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriConsumer<? super K, ? super VL, ? super VR> action) throws NullPointerException

Iterates over the given iterables of map entries assuming that both of them are sorted by the specified comparator.

Works the same way as iterateOrderedEntryIteratorsBreak(Iterator<? extends Entry<? extends K, ? extends VL>>, Iterator<? extends Entry<? extends K, ? extends VR>>, Comparator<? super K>, TriPredicate<? super K, ? super VL, ? super VR>) with creating the iterators from the argument iterables, and never breaking the iteration.

KThe key type.

VLThe left value type.

VRThe right value type.

leftThe left iterable of entries.

rightThe right iterable of entries.

comparatorThe comparator function for the entry keys.

actionThe action to execute for the entries.

NullPointerExceptionIf any of the arguments are null.

public static <K, VL, VR> boolean iterateOrderedEntryIterablesBreak(Iterable<? extends Entry<? extends K, ? extends VL>> left, Iterable<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriPredicate<? super K, ? super VL, ? super VR> action) throws NullPointerException

Iterates over the given iterables of map entries assuming that both of them are sorted by the specified comparator, optionally breaking the iteration.

KThe key type.

VLThe left value type.

VRThe right value type.

leftThe left iterable of entries.

rightThe right iterable of entries.

comparatorThe comparator function for the entry keys.

actionThe action to execute for the entries. Return false from it to break the iteration.

true if the iterables were fully iterated over, false if the action returned false for any invocation.

NullPointerExceptionIf any of the arguments are null.

public static <K, VL, VR> void iterateOrderedEntryIterablesDual(Iterable<? extends Entry<? extends K, ? extends VL>> left, Iterable<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriConsumer<? super K, ? super VL, ? super VR> action) throws NullPointerException

Iterates over the given iterables of map entries assuming that both of them are sorted by the specified comparator, and calling the given action for paired entries only.

Works the same way as iterateOrderedEntryIteratorsDualBreak(Iterator<? extends Entry<? extends K, ? extends VL>>, Iterator<? extends Entry<? extends K, ? extends VR>>, Comparator<? super K>, TriPredicate<? super K, ? super VL, ? super VR>) with creating the iterators from the argument iterables, and never breaking the iteration.

KThe key type.

VLThe left value type.

VRThe right value type.

leftThe left iterable of entries.

rightThe right iterable of entries.

comparatorThe comparator function for the entry keys.

actionThe action to execute for the paired entries.

NullPointerExceptionIf any of the arguments are null.

public static <K, VL, VR> boolean iterateOrderedEntryIterablesDualBreak(Iterable<? extends Entry<? extends K, ? extends VL>> left, Iterable<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriPredicate<? super K, ? super VL, ? super VR> action) throws NullPointerException

Iterates over the given iterables of map entries assuming that both of them are sorted by the specified comparator, and calling the given action for paired entries only, optionally breaking the iteration.

KThe key type.

VLThe left value type.

VRThe right value type.

leftThe left iterable of entries.

rightThe right iterable of entries.

comparatorThe comparator function for the entry keys.

actionThe action to execute for the entries. Return false from it to break the iteration.

true if the iterables were fully iterated over, false if the action returned false for any invocation.

NullPointerExceptionIf any of the arguments are null.

public static <K, VL, VR> void iterateOrderedEntryIterators(Iterator<? extends Entry<? extends K, ? extends VL>> left, Iterator<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriConsumer<? super K, ? super VL, ? super VR> action) throws NullPointerException

Iterates over the given iterators of map entries assuming that both of them are sorted by the specified comparator.

KThe key type.

VLThe left value type.

VRThe right value type.

leftThe left iterator of entries.

rightThe right iterator of entries.

comparatorThe comparator function for the entry keys.

actionThe action to execute for the entries.

NullPointerExceptionIf any of the arguments are null.

public static <K, VL, VR> boolean iterateOrderedEntryIteratorsBreak(Iterator<? extends Entry<? extends K, ? extends VL>> left, Iterator<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriPredicate<? super K, ? super VL, ? super VR> action) throws NullPointerException

Iterates over the given iterators of map entries assuming that both of them are sorted by the specified comparator, optionally breaking the iteration.

This method advances the argument iterator simultaneously in the order defined by the argument comparator function, and will pair the matching entries in the iterators.

During iteration, each entry key is compared to the current key of the other iterator. Based on the comparison result, the function will advance the iterator that returned the key that is less than the other. If the comparison resulted in equality, both iterators are advanecd.

The action argument will be called for each entry in the iterators. If a matching pair was not found for an entry in an iterator, null will be passed as the value argument for the action for the respective parameter. When a match is found, both value arguments are present for the associated iterator. Note that a null argument for a value doesn't necessarily mean that the entry is not present in the other iterator, but only that the associated value for the given key is null for that entry. Callers should ensure that the entries doesn't contain null values if this can cause disruption.

If an iterator finishes early, the remaining entries will be iterated over in the other iterator, and the actions will be called.

For proper operation, the caller must ensure that the entries in both iterators are sorted by the the specified order. If this requirement is violated, the pairing algorithm will not work, however, all the iterators will still be fully iterated, and the action will be called for all entries, but the calls will be semantically incorrect. This function doesn't ensure that the iterators are ordered, and no runtime exception will be thrown if this requirement is violated.

The first argument of the passed action will be the key that is associated with the second and third arguments. The second argument is the value that was found in the left iterator, and the third is the value that was found in the right iterator.

KThe key type.

VLThe left value type.

VRThe right value type.

leftThe left iterator of entries.

rightThe right iterator of entries.

comparatorThe comparator function for the entry keys.

actionThe action to execute for the entries.

true if the iterators were fully iterated over, false if the action returned false for any invocation.

NullPointerExceptionIf any of the arguments are null.

public static <K, VL, VR> void iterateOrderedEntryIteratorsDual(Iterator<? extends Entry<? extends K, ? extends VL>> left, Iterator<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriConsumer<? super K, ? super VL, ? super VR> action) throws NullPointerException

Iterates over the given iterators of map entries assuming that both of them are sorted by the specified comparator, and calling the given action for paired entries only.

KThe key type.

VLThe left value type.

VRThe right value type.

leftThe left iterator of entries.

rightThe right iterator of entries.

comparatorThe comparator function for the entry keys.

actionThe action to execute for the paired entries.

NullPointerExceptionIf any of the arguments are null.

public static <K, VL, VR> boolean iterateOrderedEntryIteratorsDualBreak(Iterator<? extends Entry<? extends K, ? extends VL>> left, Iterator<? extends Entry<? extends K, ? extends VR>> right, Comparator<? super K> comparator, TriPredicate<? super K, ? super VL, ? super VR> action) throws NullPointerException

Iterates over the given iterators of map entries assuming that both of them are sorted by the specified comparator, calling the action only for matching entries, optionally breaking the iteration.

This method advances the argument iterator simultaneously in the order defined by the argument comparator function, and will pair the matching entries in the iterators.

The action argument will be called for each matched entry in the iterators. If a matching pair was not found for an entry in an iterator, the action is not called. When a match is found, both value arguments are present for the associated iterator. A null argument in the action means that the associated value for the entry was null.

If an iterator finishes early, the remaining entries are not iterated over.

This method works similarly to iterateOrderedEntryIteratorsBreak(Iterator<? extends Entry<? extends K, ? extends VL>>, Iterator<? extends Entry<? extends K, ? extends VR>>, Comparator<? super K>, TriPredicate<? super K, ? super VL, ? super VR>), but only calls the action if an entry has been successfully paired.

KThe key type.

VLThe left value type.

VRThe right value type.

leftThe left iterator of entries.

rightThe right iterator of entries.

comparatorThe comparator function for the entry keys.

actionThe action to execute for the entries.

true if the iterators were fully iterated over, false if the action returned false for any invocation.

NullPointerExceptionIf any of the arguments are null.

public static <L extends Comparable<? super R>, R> void iterateOrderedIterables(Iterable<? extends L> left, Iterable<? extends R> right, BiConsumer<? super L, ? super R> action) throws NullPointerException

Iterates over the given iterables assuming that both of them are sorted by the natural order.

This function will iterate both iterables simultaneously in ascending natural order, and will pair the matching elements in the iterables.

During iteration, each element is compared to the current element of the other iterator. Based on the comparison result, the function will advance the iterator that returned the element that compared to be less than the other. If the comparison resulted in equality, both iterators are advanced.

The action argument will be called for each element in the iterables. If a matching pair was not found for an element in an iterable, null will be passed as the argument for the action for the respective parameter. When a match is found, both arguments are present for the associated iterable.

If an iterator finishes early, the remaining elements will be iterated over in the other iterator, and the actions will be called.

For proper operation, the caller must ensure that the elements in both iterables are sorted by the natural order. If this requirement is violated, the pairing algorithm will not work, however, all the iterables will still be fully iterated, and the action will be called for all elements, but the calls will be semantically incorrect. This function doesn't ensure that the iterables are ordered, and no runtime exception will be thrown if this requirement is violated.

LThe type of the left elements. Must be comparable to the right elements.

RThe type of the right elements.

leftThe iterable of the left elements.

rightThe iterable of the right elements.

actionThe action to call for the iterated elements.

NullPointerExceptionIf any of the arguments are null.

public static <L, R> void iterateOrderedIterables(Iterable<? extends L> left, Iterable<? extends R> right, ToIntBiFunction<? super L, ? super R> comparator, BiConsumer<? super L, ? super R> action) throws NullPointerException

Iterates over the given iterables assuming that both of them are sorted by the specified comparator function.

This function will iterate both iterables simultaneously in the order defined by the argument comparator function, and will pair the matching elements in the iterables.

If an iterator finishes early, the remaining elements will be iterated over in the other iterator, and the actions will be called.

For proper operation, the caller must ensure that the elements in both iterables are sorted by the specified order. If this requirement is violated, the pairing algorithm will not work, however, all the iterables will still be fully iterated, and the action will be called for all elements, but the calls will be semantically incorrect. This function doesn't ensure that the iterables are ordered, and no runtime exception will be thrown if this requirement is violated.

LThe type of the left elements.

RThe type of the right elements.

leftThe iterable of the left elements.

rightThe iterable of the right elements.

comparatorThe comparator function that compares the left and right elements. It should return 0 if the elements compare to be equal, negative if the left is less than the right, or positive if the right is less than the left. See Comparator.compare(T, T).

actionThe action to call for the iterated elements.

NullPointerExceptionIf any of the arguments are null.

public static <L extends Comparable<? super R>, R> void iterateOrderedIterators(Iterator<? extends L> left, Iterator<? extends R> right, BiConsumer<? super L, ? super R> action) throws NullPointerException

Iterates over the given iterators assuming that both of them are sorted by the natural order.

This function will advance both iterators simultaneously in ascending natural order, and will pair the matching elements in the iterators.

The action argument will be called for each element in the iterators. If a matching pair was not found for an element in an iterator, null will be passed as the argument for the action for the respective parameter. When a match is found, both arguments are present for the associated iterator.

If an iterator finishes early, the remaining elements will be iterated over in the other iterator, and the actions will be called.

For proper operation, the caller must ensure that the elements in both iterators are sorted by the natural order. If this requirement is violated, the pairing algorithm will not work, however, all the iterators will still be fully iterated, and the action will be called for all elements, but the calls will be semantically incorrect. This function doesn't ensure that the iterators are ordered, and no runtime exception will be thrown if this requirement is violated.

LThe type of the left elements. Must be comparable to the right elements.

RThe type of the right elements.

leftThe iterator of the left elements.

rightThe iterator of the right elements.

actionThe action to call for the iterated elements.

NullPointerExceptionIf any of the arguments are null.

public static <L, R> void iterateOrderedIterators(Iterator<? extends L> lit, Iterator<? extends R> rit, ToIntBiFunction<? super L, ? super R> comparator, BiConsumer<? super L, ? super R> action) throws NullPointerException

Iterates over the given iterators assuming that both of them are sorted by the specified comparator function.

This function will advance both iterators simultaneously in the order defined by the argument comparator function, and will pair the matching elements in the iterators.

If an iterator finishes early, the remaining elements will be iterated over in the other iterator, and the actions will be called.

For proper operation, the caller must ensure that the elements in both iterators are sorted by the the specified order. If this requirement is violated, the pairing algorithm will not work, however, all the iterators will still be fully iterated, and the action will be called for all elements, but the calls will be semantically incorrect. This function doesn't ensure that the iterators are ordered, and no runtime exception will be thrown if this requirement is violated.

LThe type of the left elements.

RThe type of the right elements.

litThe iterator of the left elements.

ritThe iterator of the right elements.

actionThe action to call for the iterated elements.

NullPointerExceptionIf any of the arguments are null.

public static boolean iteratePrevUntil(ListIterator<?> it, Object obj) throws NullPointerException

Moves the argument iterator backwards until an object is encountered that equals the argument.

If this method returns true, the iterator will point before the object has been encountered. Calling Iterator.remove() will remove an object that equals to the given argument.

This method works the same way as iterateUntil(Iterator<?>, Object), but takes a ListIterator as its argument, and iterates using ListIterator.previous() instead of Iterator.next().

itThe iterator to iterate with.

objThe object to search.

true if an object was found that equals to the argument.

NullPointerExceptionIf the iterator is null.

public static <K, VL, VR> void iterateSortedMapEntries(SortedMap<? extends K, ? extends VL> left, SortedMap<? extends K, ? extends VR> right, TriConsumer<? super K, ? super VL, ? super VR> action) throws NullPointerException, IllegalArgumentException

Iterates over the entries of the argument sorted maps assuming that both of them are sorted by the same order.

Works the same way ax iterateOrderedEntryIterables(Iterable<? extends Entry<? extends K, ? extends VL>>, Iterable<? extends Entry<? extends K, ? extends VR>>, Comparator<? super K>, TriConsumer<? super K, ? super VL, ? super VR>), with the comparator taken from the maps.

If the maps are not ordered the same way, an IllegalArgumentException is thrown.

KThe key type.

VLThe left value type.

VRThe right value type.

leftThe left map.

rightThe right map.

actionThe action to execute for the entries.

NullPointerExceptionIf any of the arguments are null.

IllegalArgumentExceptionIf the maps are not ordered the same way.

requireSameComparators(SortedMap<K, ?>, SortedMap<?, ?>)

public static <K, VL, VR> boolean iterateSortedMapEntriesBreak(SortedMap<? extends K, ? extends VL> left, SortedMap<? extends K, ? extends VR> right, TriPredicate<? super K, ? super VL, ? super VR> action) throws NullPointerException, IllegalArgumentException

Iterates over the entries of the argument sorted maps assuming that both of them are sorted by the same order, optionally breaking the iteration.

Works the same way ax iterateOrderedEntryIterablesBreak(Iterable<? extends Entry<? extends K, ? extends VL>>, Iterable<? extends Entry<? extends K, ? extends VR>>, Comparator<? super K>, TriPredicate<? super K, ? super VL, ? super VR>), with the comparator taken from the maps.

If the maps are not ordered the same way, an IllegalArgumentException is thrown.

KThe key type.

VLThe left value type.

VRThe right value type.

leftThe left map.

rightThe right map.

actionThe action to execute for the entries. Return false from it to break the iteration.

true if the maps were fully iterated over, false if the action returned false for any invocation.

NullPointerExceptionIf any of the arguments are null.

IllegalArgumentExceptionIf the maps are not ordered the same way.

requireSameComparators(SortedMap<K, ?>, SortedMap<?, ?>)

public static <K, VL, VR> void iterateSortedMapEntriesDual(SortedMap<? extends K, ? extends VL> left, SortedMap<? extends K, ? extends VR> right, TriConsumer<? super K, ? super VL, ? super VR> action) throws NullPointerException, IllegalArgumentException

Iterates over the entries of the argument sorted maps assuming that both of them are sorted by the same order, and calling the given action for paired entries only.

Works the same way ax iterateOrderedEntryIterablesDual(Iterable<? extends Entry<? extends K, ? extends VL>>, Iterable<? extends Entry<? extends K, ? extends VR>>, Comparator<? super K>, TriConsumer<? super K, ? super VL, ? super VR>), with the comparator taken from the maps.

If the maps are not ordered the same way, an IllegalArgumentException is thrown.

KThe key type.

VLThe left value type.

VRThe right value type.

leftThe left map.

rightThe right map.

actionThe action to execute for the paired entries.

NullPointerExceptionIf any of the arguments are null.

IllegalArgumentExceptionIf the maps are not ordered the same way.

requireSameComparators(SortedMap<K, ?>, SortedMap<?, ?>)

public static <K, VL, VR> void iterateSortedMapEntriesDualBreak(SortedMap<? extends K, ? extends VL> left, SortedMap<? extends K, ? extends VR> right, TriPredicate<? super K, ? super VL, ? super VR> action) throws NullPointerException, IllegalArgumentException

Iterates over the entries of the argument sorted maps assuming that both of them are sorted by the same order, and calling the given action for paired entries only, optionally breaking the iteration.

Works the same way ax iterateOrderedEntryIterablesDualBreak(Iterable<? extends Entry<? extends K, ? extends VL>>, Iterable<? extends Entry<? extends K, ? extends VR>>, Comparator<? super K>, TriPredicate<? super K, ? super VL, ? super VR>), with the comparator taken from the maps.

If the maps are not ordered the same way, an IllegalArgumentException is thrown.

KThe key type.

VLThe left value type.

VRThe right value type.

leftThe left map.

rightThe right map.

actionThe action to execute for the paired entries. Return false from it to break the iteration.

NullPointerExceptionIf any of the arguments are null.

IllegalArgumentExceptionIf the maps are not ordered the same way.

requireSameComparators(SortedMap<K, ?>, SortedMap<?, ?>)

public static boolean iterateUntil(Iterator<?> it, Object obj) throws NullPointerException

Moves the argument iterator until an object is encountered that equals the argument.

If this method returns true, the iterator will point after the object has been encountered. Calling Iterator.remove() will remove an object that equals to the given argument.

itThe iterator to iterate with.

objThe object to search.

true if an object was found that equals to the argument.

NullPointerExceptionIf the iterator is null.

public static <T> Iterator<T> iterator(Iterable<T> iterable)

Calls Iterable.iterator() on the argument if non-null.

TThe element type.

iterableThe iterable.

An iterator from the argument or null if the argument is null.

public static <T> Iterator<T> iterator(T[] array)

Gets an iterator that iterates over the argument array.

TThe element type.

arrayThe array.

An iterator or null if the argument is null.

public static int listHash(Iterable<?> iterable) throws NullPointerException

Calculates the hash of the elements contained in the argument based on the method specified by List.hashCode().

iterableThe iterable of elements.

The hash.

NullPointerExceptionIf the iterable is null.

public static int listHash(Iterator<?> it) throws NullPointerException

Calculates the hash of the elements contained in the argument based on the method specified by List.hashCode().

itThe iterator of elements.

The hash.

NullPointerExceptionIf the iterator is null.

public static boolean listsEqual(List<?> first, List<?> second)

Checks the argument lists for equality.

This method will examine if both lists have the same size and their elements at the same indexes are equal.

Note: this method doesn't call List.size() to shortcut the equality check, but iterate over the lists at the same time.

firstThe first list.

secondThe second list.

true if they equal.

public static int mapEntryHash(Object key, Object value)

Calculates the hash of the argument key-value map entry based on the method specified by Map.Entry.hashCode().

keyThe key.

valueThe value.

The hash.

public static int mapEntryHash(Entry<?, ?> entry) throws NullPointerException

Calculates the hash of the argument map entry based on the method specified by Map.Entry.hashCode().

entryThe map entry.

The hash.

NullPointerExceptionIf the entry is null.

public static int mapHash(Iterable<? extends Entry<?, ?>> entryiterable) throws NullPointerException

Calculates the hash of the entries contained in the argument based on the method specified by Map.hashCode().

entryiterableAn iterable of map entries.

The hash.

NullPointerExceptionIf the iterable is null.

public static int mapHash(Iterator<? extends Entry<?, ?>> iterator) throws NullPointerException

Calculates the hash of the entries contained in the argument based on the method specified by Map.hashCode().

iteratorAn iterator of map entries.

The hash.

NullPointerExceptionIf the iterator is null.

public static int mapHash(Map<?, ?> map) throws NullPointerException

Calculates the hash of the entries contained in the argument based on the method specified by Map.hashCode().

mapThe map of elements.

The hash.

NullPointerExceptionIf the map is null.

public static <Key, LType, RType> boolean mapOrderedEquals(Map<? extends Key, ? extends LType> left, Map<? extends Key, ? extends RType> right)

Same as calling orderedMapEquals(left, right, Objects::equals).

KeyThe key type.

LTypeThe value types of the first map.

RTypeThe value types of the second map.

leftThe first map.

rightThe second map.

true if the maps are considered to be equal.

public static <Key, LType, RType> boolean mapOrderedEquals(Map<? extends Key, ? extends LType> left, Map<? extends Key, ? extends RType> right, BiPredicate<? super LType, ? super RType> comparator) throws NullPointerException

Checks if the argument maps equal by checking the equality of the keys and values in iteration order using the given function.

Note: this method is not suitable for checking the equality of unordered maps like HashMap.

This method will simultaneously iterate over the entries of both maps and compare them for equality. This method is only suitable for checking equality of maps which iterate over the entries in a deterministic order. Examples for this are sorted maps (E.g. TreeMap), or maps that preserve their order in some ways (E.g. LinkedHashMap).

If the maps have different sizes, this method will return false.

The method handles nullability of the arguments.

The method checks the sizes of the maps before starting the iteration, so callers should keep this in mind when passing arguments that provide a Map.size() method which has greater complexity than O(1) (E.g. some concurrent maps).

Example usage:

 ObjectUtils.orderedMapEquals(map1, map2, Objects::equals);

KeyThe key type.

LTypeThe value types of the first map.

RTypeThe value types of the second map.

leftThe first map.

rightThe second map.

comparatorThe function to determine if two values are equal.

true if the maps are considered to be equal.

NullPointerExceptionIf the comparator function is null.

public static String mapToString(Map<?, ?> map)

Creates a string representation of the argument map.

Each entry in the map will be displayed in a comma separated list between curly braces. ({})

The method creates a string representation of the map that is semantically same as the usual map representations.

mapThe map.

The string representation of the map.

AbstractMap.toString()

public static boolean mapsEqual(Map<?, ?> first, Map<?, ?> second)

Checks the argument maps for equality.

This method checks if the arguments have the same size, and each key in the first map is mapped to the same value in the second as in the first.

The method handles nullability of the arguments. If both of the arguments are null, true is returned.

firstThe first map.

secondThe second map.

true if they equal.

public static <E> ArrayList<E> newArrayList(Iterable<? extends E> objects)

Creates a new array list and adds each element of the argument iterable.

If the argument iterable is null, no elements are added.

EThe element type.

objectsThe iterable of elements.

The created array list.

public static <E> ArrayList<E> newArrayList(Collection<? extends E> objects)

Creates a new array list and adds each element of the argument collection.

If the argument collection is null, no elements are added.

EThe element type.

objectsThe collection of elements.

The created array list.

public static <E> ArrayList<E> newArrayList(Collection<? extends E> firstobjects, Collection<? extends E> secondobjects)

Creates a new array list and adds the elements of the first, and then the second collection.

If any of the collections is null, no elements are added for them.

EThe element type.

firstobjectsThe first collection of objects to add.

secondobjectsThe second collection of objects to add.

The created array list.

public static <E> ArrayList<E> newArrayList(Iterator<? extends E> objects)

Creates a new array list and adds each remaining element from the argument iterator.

If the argument iterator is null, no elements are added.

EThe element type.

objectsThe iterator of elements.

The created array list.

@SafeVarargs

public static <E> ArrayList<E> newArrayList(E... objects)

Creates a new array list and adds each element of the argument array.

If the argument collection is null, no elements are added.

EThe element type.

objectsThe array of elements.

The created array list.

public static <K, V> HashMap<K, V> newHashMap(Map<? extends K, ? extends V> map)

Creates a new HashMap and initializes it with the argument objects.

If the argument is null, the returned map will be empty.

KThe key type.

VThe value type.

mapThe map entries to initialize the result with.

The newly created hash map.

public static <E> HashSet<E> newHashSet(Iterable<? extends E> objects)

Creates a new HashSet and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

EThe element type.

objectsThe objects.

The newly created hash set.

public static <E> HashSet<E> newHashSet(Collection<? extends E> objects)

Creates a new HashSet and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

EThe element type.

objectsThe objects.

The newly created hash set.

@SafeVarargs

public static <E> HashSet<E> newHashSet(E... objects)

Creates a new HashSet and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

EThe element type.

objectsThe objects.

The newly created hash set.

public static <K, V> IdentityHashMap<K, V> newIdentityHashMap(Map<? extends K, ? extends V> map)

Creates a new IdentityHashMap and initializes it with the argument objects.

If the argument is null, the returned map will be empty.

KThe key type.

VThe value type.

mapThe map entries to initialize the result with.

The newly created identity hash map.

public static <E> Set<E> newIdentityHashSet()

Creates a new identity hash set.

The identity hash set is created by calling newSetFromMap(Map<E, ? super Boolean>) with a new IdentityHashMap.

The newly created identity hash set.

IdentityHashMap

public static <E> Set<E> newIdentityHashSet(Iterable<? extends E> objects)

Creates a new identity hash set and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

The identity hash set is created by calling newSetFromMap(Map<E, ? super Boolean>) with a new IdentityHashMap.

EThe element type.

objectsThe objects.

The newly created identity hash set.

IdentityHashMap

public static <E> Set<E> newIdentityHashSet(Collection<? extends E> objects)

Creates a new identity hash set and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

The identity hash set is created by calling newSetFromMap(Map<E, ? super Boolean>) with a new IdentityHashMap.

EThe element type.

objectsThe objects.

The newly created identity hash set.

IdentityHashMap

public static <E> Set<E> newIdentityHashSet(Set<? extends E> objects)

Creates a new identity hash set and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

The identity hash set is created by calling newSetFromMap(Map<E, ? super Boolean>) with a new IdentityHashMap.

EThe element type.

objectsThe objects.

The newly created identity hash set.

IdentityHashMap

@SafeVarargs

public static <E> Set<E> newIdentityHashSet(E... objects)

Creates a new identity hash set and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

The identity hash set is created by calling newSetFromMap(Map<E, ? super Boolean>) with a new IdentityHashMap.

EThe element type.

objectsThe objects.

The newly created identity hash set.

IdentityHashMap

public static <K, V> LinkedHashMap<K, V> newLinkedHashMap(Map<? extends K, ? extends V> map)

Creates a new LinkedHashMap and initializes it with the argument objects.

If the argument is null, the returned map will be empty.

KThe key type.

VThe value type.

mapThe map entries to initialize the result with.

The newly created linked hash map.

public static <E> LinkedHashSet<E> newLinkedHashSet(Iterable<? extends E> objects)

Creates a new LinkedHashSet and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

EThe element type.

objectsThe objects.

The newly created linked hash set.

public static <E> LinkedHashSet<E> newLinkedHashSet(Collection<? extends E> objects)

Creates a new LinkedHashSet and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

EThe element type.

objectsThe objects.

The newly created linked hash set.

@SafeVarargs

public static <E> LinkedHashSet<E> newLinkedHashSet(E... objects)

Creates a new LinkedHashSet and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

EThe element type.

objectsThe objects.

The newly created linked hash set.

public static <E> Set<E> newSetFromMap(Map<E, ? super Boolean> map) throws IllegalArgumentException

Creates a new set that is backed by the argument map.

This method creates a set the same way as Collections.newSetFromMap(Map<E, Boolean>), but the returned set is Externalizable.

EThe element type.

mapThe set backing map.

The set that is backed by the argument map or null if the argument map is null.

IllegalArgumentExceptionIf the argument map is not empty.

public static <K, V> TreeMap<K, V> newTreeMap(Map<? extends K, ? extends V> map)

Creates a new TreeMap and initializes it with the argument map entries.

If the argument is null, the returned map will be empty.

KThe key type.

VThe value type.

mapThe map to initialize the result with.

The newly created tree map.

public static <K, V> TreeMap<K, V> newTreeMap(SortedMap<K, ? extends V> map)

Creates a new TreeMap and initializes it with the argument map entries.

If the argument is null, the returned map will be empty.

The returned tree set will have the same ordering as the argument sorted map.

KThe key type.

VThe value type.

mapThe map to initialize the result with.

The newly created tree map.

public static <E> TreeSet<E> newTreeSet(Iterable<? extends E> objects)

Creates a new TreeSet and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

EThe element type.

objectsThe objects.

The newly created tree set.

public static <E> TreeSet<E> newTreeSet(Collection<? extends E> objects)

Creates a new TreeSet and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

EThe element type.

objectsThe objects.

The newly created tree set.

public static <E> TreeSet<E> newTreeSet(SortedSet<E> objects)

Creates a new TreeSet and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

The returned tree set will have the same ordering as the argument sorted set.

EThe element type.

objectsThe objects.

The newly created tree set.

@SafeVarargs

public static <E> TreeSet<E> newTreeSet(E... objects)

Creates a new TreeSet and initializes it with the argument objects.

If the argument is null, the returned set will be empty.

EThe element type.

objectsThe objects.

The newly created tree set.

public static int nonNullObjectCount(Iterable<?> objects)

Counts the number of non-null objects in the argument iterable.

If the argument itself is null, 0 is returned.

objectsThe iterable of objects to examine.

The number of non-null elements found.

public static int nonNullObjectCount(Object... objects)

Counts the number of non-null objects in the argument array.

If the argument itself is null, 0 is returned.

objectsThe objects to examine.

The number of non-null elements found.

public static <T> T nullDefault(T first, T defaultvalue)

Checks if the first argument is null and if it is, returns the default value.

TThe type of the arguments.

firstThe object to check nullability for.

defaultvalueThe object to return if the object is null.

The first argument if it is non-null, else the default value.

public static <T> T nullDefault(T test, Supplier<? extends T> defaultvalue)

Checks if the first argument is null and if it is, returns the value supplied by the default supplier.

TThe type of the arguments.

testThe object to test null value for.

defaultvalueThe supplier to compute the return value if the test object is null.

The test object is non-null, else the computed value by the supplier.

public static int nullObjectCount(Iterable<?>... objects)

Counts the number of null objects in the argument iterable.

If the argument itself is null, 0 is returned.

objectsThe iterable of objects to examine.

The number of null elements found.

public static int nullObjectCount(Object... objects)

Counts the number of null objects in the argument array.

If the argument itself is null, 0 is returned.

objectsThe objects to examine.

The number of null elements found.

public static <LType, RType> boolean objectsEquals(LType left, RType right, BiPredicate<? super LType, ? super RType> comparator) throws NullPointerException

Checks the argument objects for equality using the given comparator predicate.

If the objects are same by identity, true is returned without calling the comparator.

If any of the objects are null (and the other is not null), then false is returned.

Else, the comparator predicate will be called with the arguments.

LTypeThe type of the left object.

RTypeThe type of the right.

leftThe first object.

rightThe second object.

comparatorThe comparator predicate to check if the objects equal.

true if the objects are same by identity, or the comparator returned true.

NullPointerException

public static <E> Iterable<E> onceIterable(Iterator<E> iterator) throws NullPointerException

Converts the argument iterator to an once iterable.

The Iterable.iterator() function of the returned iterable can only be called once, else IllegalStateException will be thrown. The returned iterator will be the same as the argument to this method.

EThe type of the returned elements.

iteratorThe iterator.

The wrapping once iterable.

NullPointerExceptionIf the iterator is null.

public static void reachabilityFence(Object o)

Backports Reference.reachabilityFence(Object) to Java 8.

This method does nothing at all with the argument object.

On Java 8, it is simply an empty method. On Java 9+ it calls Reference.reachabilityFence(Object).

oAn object reference.

public static boolean removeAtIndex(Iterable<?> iterable, int index) throws NullPointerException, IllegalArgumentException

Finds the object at the given index in the argument iterable, and removes it.

This method will iterate over the argument iterable until the element at the given index is reached. Then it will call Iterator.remove() and return true.

If the specified index is greater than the number of objects in the iterable, no elements will be removed, and false is returned.

iterableThe iterable.

indexThe index at which the element should be removed.

true if the element at the index was removed.

NullPointerExceptionIf the iterable is null.

IllegalArgumentExceptionIf the index is negative.

public static <T> T removeFirstElement(Iterable<? extends T> iterable) throws NullPointerException

Removes the first element from an iterable if present.

This method will use Iterator.hasNext() to determine if there is an element in the iterable, and remove it if there is one.

iterableThe iterable to remove the first element of.

The removed element or null if there was no such element. (null will be returned even if the first element is null.)

NullPointerExceptionIf the iterable is null.

public static <T> T removeFirstElementThrow(Iterable<? extends T> iterable) throws NoSuchElementException, NullPointerException

Removes the first element from an iterable, or throws an exception if there is no first element.

This method will not call the Iterator.hasNext() method, and relies on the iterator to throw a NoSuchElementException if there is no first element. As per the documentation of the Iterator class, all of them should obey this behaviour.

iterableThe iterable to remove the first element of.

The removed element.

NoSuchElementExceptionIf there is no elements in the iterable.

NullPointerExceptionIf the iterable is null.

public static boolean removeFirstOccurrence(Iterable<?> iterable, Object object) throws NullPointerException

Searches for the first occurrence of an object in an iterable, and removes it.

This method will iterate over the argument iterable, and find the first occurrence in it, that equals to the argument object. If found, Iterator.remove() is called to remove it, and true is returned.

iterableThe iterable to search the object in.

objectThe object to search. May be null.

true if an element was removed.

NullPointerExceptionIf the iterable is null.

public static <M extends SortedMap<?, ?>> M requireComparator(M map, Comparator<?> comparator) throws IllegalArgumentException, NullPointerException

Validation method for requiring that the argument sorted map is sorted by the given comparator.

The comparators of the map and the argument are compared by equality. If the comparator instances doesn't implement Object.equals(Object) properly, this method will most likely fail.

MThe map type.

mapThe map.

comparatorThe compare to check for or null to require the natural order.

The argument map.

IllegalArgumentExceptionIf the argument map is not sorted by the given comparator.

NullPointerExceptionIf the map is null.

public static <S extends SortedSet<?>> S requireComparator(S set, Comparator<?> comparator) throws NullPointerException, IllegalArgumentException

Validation method for requiring that the argument sorted set is sorted by the given comparator.

The comparators of the set and the argument are compared by equality. If the comparator instances doesn't implement Object.equals(Object) properly, this method will most likely fail.

SThe set type.

setThe set.

comparatorThe compare to check for or null to require the natural order.

The argument set.

NullPointerExceptionIf the set is null.

IllegalArgumentExceptionIf the argument set is not sorted by the given comparator.

public static <C extends Comparator<?>> C requireNaturalOrder(C comparator) throws IllegalArgumentException

Validation method for checking if the comparator represents the natural order.

CThe comparator type.

comparatorThe comparator.

The comparator.

IllegalArgumentExceptionIf the comparator does not equal the natural order.

isNaturalOrder(Comparator<?>)

public static <M extends SortedMap<?, ?>> M requireNaturalOrder(M map) throws IllegalArgumentException, NullPointerException

Validation method for checking if a sorted map is ordered by the natural order.

MThe map type.

mapThe map.

The argument map.

IllegalArgumentExceptionIf the map is not ordered by natural order.

NullPointerExceptionIf the map is null.

requireNaturalOrder(C)

public static <S extends SortedSet<?>> S requireNaturalOrder(S set) throws IllegalArgumentException, NullPointerException

Validation method for checking if a sorted set is ordered by the natural order.

SThe set type.

setThe set.

The argument set.

IllegalArgumentExceptionIf the set is not ordered by natural order.

NullPointerExceptionIf the set is null.

requireNaturalOrder(C)

public static <E, C extends Iterable<E>> C requireNonNullElements(C iterable) throws NullPointerException

Validation method for requiring that the argument iterable contains no null elements.

EThe type of the elements.

CThe type of the iterable.

iterableThe iterable.

The argument iterable.

NullPointerExceptionIf the argument or any elements arenull.

public static <E> E[] requireNonNullElements(E[] objects) throws NullPointerException

Validation method for requiring that the argument array contains no null elements.

EThe type of the elements.

objectsThe array.

The argument array.

NullPointerExceptionIf the array or any elements are null.

public static <K, V, M extends Map<K, V>> M requireNonNullEntryKeyValues(M map) throws NullPointerException

Validation method for requiring that the argument map contains no null keys or values.

KThe key type.

VThe value type.

MThe map type.

mapThe map.

The argument map.

NullPointerExceptionIf the map, the entries, the keys or values are null.

public static <K, V, M extends Map<K, V>> M requireNonNullValues(M map) throws NullPointerException

Validation method for requiring that the argument map contains no null values.

The keys of the map is not examined.

KThe key type.

VThe value type.

MThe map type.

mapThe map.

The argument map.

NullPointerExceptionIf the map, the entries, or any value is null.

public static <T> Comparator<T> requireSameComparators(Comparator<T> cmp1, Comparator<?> cmp2) throws IllegalArgumentException

Validation method for ensuring that the two comparators define the same order.

The comparators of are compared by equality. null arguments are treated as to denote the natural order.

TThe type of the compared objects.

cmp1The first comparator.

cmp2The second comparator.

The comparator that defines the order. Never null.

IllegalArgumentExceptionIf the comparators are different.

public static <K> Comparator<? super K> requireSameComparators(SortedMap<K, ?> firstmap, SortedMap<?, ?> secondmap) throws IllegalArgumentException, NullPointerException

Validation method for ensuring that two sorted maps have the same order.

The comparators of the sorted maps are compared by equality.

KThe key type.

firstmapThe first map.

secondmapThe second map.

The comparator that defines their orders. Never null.

IllegalArgumentExceptionIf the comparators are different.

NullPointerExceptionIf any of the arguments are null.

public static <E> Comparator<? super E> requireSameComparators(SortedSet<E> firstset, SortedSet<?> secondset) throws IllegalArgumentException, NullPointerException

Validation method for ensuring that two sorted sets have the same order.

The comparators of the sorted sets are compared by equality.

EThe element type.

firstsetThe first set.

secondsetThe second set.

The comparator that defines their orders. Never null.

IllegalArgumentExceptionIf the comparators are different.

NullPointerExceptionIf any of the arguments are null.

public static <E> List<E> reversedList(List<E> list)

Gets a reversed view of the argument list.

The returned list is modifiable, and will return the elements in the reverse order as the argument. Any modifications made to the returned list will be propagated accordingly to the original list.

Calling this with a list that was reversed with this method, will return the original list. The following is true:

 ObjectUtils.reversed(list) == ObjectUtils.reversed(ObjectUtils.reversed(list))

EThe element type.

listThe list to reverse.

The reversed view of the argument list, or null if the argument was null.

public static int setHash(Iterable<?> iterable) throws NullPointerException

Calculates the hash of the elements contained in the argument based on the method specified by Set.hashCode().

iterableThe iterable of elements.

The hash.

NullPointerExceptionIf the iterable is null.

public static int setHash(Iterator<?> it) throws NullPointerException

Calculates the hash of the elements contained in the argument based on the method specified by Set.hashCode().

itThe iterator of elements.

The hash.

NullPointerExceptionIf the iterator is null.

public static boolean setsEqual(Set<?> first, Set<?> second)

Checks the argument sets for equality.

This method checks if the arguments have the same size, and the first set contains all elements from the second set.

The method handles nullability of the arguments. If both of the arguments are null, true is returned.

firstThe first set.

secondThe second set.

true if they equal.

public static <K, V> NavigableMap<K, V> singleValueMap(NavigableSet<K> set, V value) throws NullPointerException

Creates a new navigable map view that has the same keys as the argument set, and all keys are mapped to the argument value.

The returned map is partially modifiable, meaning that only some modifications will succeed. Removals are guaranteed to work, but insertions into the map may fail in some cases. Callers shouldn't rely on the put operations to work.

Putting a key-pair into the map may only work if the newly added entry value is identically the same as the mapped single value.

The Map.Entry.setValue(V) is most likely unsupported regardless of the set value.

KThe key type.

VThe value type.

setThe set that contains the keys for the returned map.

valueThe value to map the keys to.

A navigable map view that is backed by the given key set and value.

NullPointerExceptionIf the set is null.

public static <K, V> Map<K, V> singleValueMap(Set<K> set, V value) throws NullPointerException

Creates a new map view that has the same keys as the argument set, and all keys are mapped to the argument value.

Putting a key-pair into the map may only work if the newly added entry value is identically the same as the mapped single value.

The Map.Entry.setValue(V) is most likely unsupported regardless of the set value.

KThe key type.

VThe value type.

setThe set that contains the keys for the returned map.

valueThe value to map the keys to.

A map view that is backed by the given key set and value.

NullPointerExceptionIf the set is null.

public static <K, V> SortedMap<K, V> singleValueMap(SortedSet<K> set, V value) throws NullPointerException

Creates a new sorted map view that has the same keys as the argument set, and all keys are mapped to the argument value.

Putting a key-pair into the map may only work if the newly added entry value is identically the same as the mapped single value.

The Map.Entry.setValue(V) is most likely unsupported regardless of the set value.

KThe key type.

VThe value type.

setThe set that contains the keys for the returned map.

valueThe value to map the keys to.

A sorted map view that is backed by the given key set and value.

NullPointerExceptionIf the set is null.

public static int sizeOfIterable(Iterable<?> iterable)

Counts the number of elements in the iterable.

The value of the elements are not examined, null elements also count towards the result.

iterableThe iterable.

The number of elements in the iterable. 0 is returned if the iterable is null.

public static int sizeOfIterator(Iterator<?> it)

Counts the number of remaining elements in the iterator.

The value of the elements are not examined, null elements also count towards the result.

itThe iterator.

The number of remaining elements in the iterator. 0 is returned if the iterator is null.

public static RuntimeException sneakyThrow(Throwable t)

Sneakily throws the argument throwable.

This method can be used to throw checked exceptions in a function context that doesn't declare it. In general, this functionality should be very rarely used, and one should not create an API that sneakily throws exceptions, as callers cannot catch them by explicitly declaring it.

A good use-case for this:

 private Object calculate(Object k) throws IOException {
 	return something;
 }
 
 public Object computeSomething(Object key) {
 	try {
 		return map.computeIfAbsent(key, k -> {
 			try {
 				return calculate(k);
 			} catch (IOException e) {
 				throw ObjectUtils.sneakyThrow(e);
 			}
 		});
 	} catch (IOException e) {
 		// the exception sneakily thrown by the computer function is caught by ourself.
 		return null;
 	}
 }

In the above example, we throw the IOException sneakily, and catch it in the enclosing code block. This is necessary, as the computer function doesn't allow for a checked exception to be thrown. In this case we deem that it is acceptable to use sneaky throwing, but callers should make sure that they catch the exception as well.

It is a good practice, that if a code sneakily throws some exception, the maintainer of the enclosing code should either explicitly catch the sneakily thrown exception, or declare it in the API method declaration.

Throwing the return value of the sneakyThrow(Throwable) function is useful so the Java compiler doesn't issue an error that the method doesn't have a return value. That throw declaration actually has no effect, as the exception is thrown inside the sneakyThrow(Throwable) function.

tThe throwable to throw.

Never returns properly.

public static <T> T[] transformArray(T[] array, Function<? super T, ? extends T> transformer) throws NullPointerException

Transforms the elements of the given array using the transformer function.

This method will call the transformer function for each element in the array, and replace them with the result of the function.

If the argument array is null, this method returns null.

arrayThe array to transform.

transformerThe element transformer function.

The argument array.

NullPointerExceptionIf the transformer is null.

public static <T, E> Iterable<E> transformIterable(Iterable<? extends T> iterable, Function<? super T, ? extends E> transformer)

Wraps the argument iterable into a new one that creates iterators which transform the elements using the given function.

The returned iterable will create iterators that transform each element using the given function.

If the transformer is null, a NullPointerException might be thrown when an iterator is constructed from the result.

TThe original element type.

EThe new element type.

iterableThe iterable to transform.

transformerThe iterator element transformer.

The transforming iterable, or null if the iterable is null.

transformIterator(Iterator<? extends T>, Function<? super T, ? extends E>)

public static <T, E> Iterator<E> transformIterator(Iterator<? extends T> iterator, Function<? super T, ? extends E> transformer) throws NullPointerException

Wraps the argument iterator into a new one that transforms the elements using the given function.

The returned iterator will use the argument function to transform each element, and return the resulting object.

TThe original element type.

EThe new element type.

iteratorThe iterator to transform.

transformerThe iterator element transformer.

The transforming iterator, or null if the iterator is null.

NullPointerExceptionIf the iterator is non-null and the transformer is null.