ImmutableCollections.java
package org.djutils.immutablecollections;
import java.util.Collection;
import java.util.Collections;
import java.util.Comparator;
import java.util.List;
import java.util.NoSuchElementException;
/**
* Static methods operating on immutable collections, or a mix of an immutable collection and a mutable collection.
* <p>
* Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
* BSD-style license. See <a href="https://djutils.org/docs/current/djutils/licenses.html">DJUTILS License</a>.
* </p>
* @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
* @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</a>
*/
public final class ImmutableCollections
{
/**
* There is never a need to instantiate an object of this class.
*/
private ImmutableCollections()
{
// Do not instantiate
}
/**
* Return an immutable empty set.
* @return ImmutableSet<T>; an immutable empty set
* @param <T> the data type of the ImmutableSet
*/
public static <T extends Object> ImmutableSet<T> emptyImmutableSet()
{
return new ImmutableHashSet<T>(Collections.emptySet(), Immutable.WRAP);
}
/**
* Return an immutable empty map.
* @return ImmutableMap<T, V>; an immutable empty map
* @param <T> the key type of the ImmutableMap
* @param <V> the value type of the ImmutableMap
*/
public static <T extends Object, V extends Object> ImmutableMap<T, V> emptyImmutableMap()
{
return new ImmutableHashMap<T, V>(Collections.emptyMap(), Immutable.WRAP);
}
/**
* Return an immutable empty list.
* @return ImmutableList<T>; an immutable empty list
* @param <T> the data type of the ImmutableList
*/
public static <T extends Object> ImmutableList<T> emptyImmutableList()
{
return new ImmutableArrayList<T>(Collections.emptyList(), Immutable.WRAP);
}
/**
* Search the immutable list for the specified object using the binary search algorithm. The list must be ordered according
* to the natural ordering of its elements.
* @param il ImmutableList<? extends Comparable<? super T>>; the list (must be ordered according to the natural
* ordering of <code>T</code>
* @param key T; the element to search for.
* @return int; if <code>key</code> is present in the list, the index of <code>key</code>, or, when <code>key</code> is not
* present in the list <code>(-(<i>insertion point</i>) - 1)</code> where <code>insertion point</code> is the index
* of <code>key</code> if it were contained in the list.
* @param <T> the data type of the ImmutableList
*/
public static <T> int binarySearch(final ImmutableList<? extends Comparable<? super T>> il, final T key)
{
return Collections.binarySearch(il.toList(), key);
}
/**
* Search the immutable list for the specified object using the binary search algorithm. The list must be ordered according
* to the comparator.
* @param il ImmutableList<? extends T>; the list (must be ordered according to the
* <code>comparator</code>
* @param key T; the element to search for.
* @param comparator Comparator<? super T>; a comparator for <code>T</code>
* @return int; if <code>key</code> is present in the list, the index of <code>key</code>, or, when <code>key</code> is not
* present in the list <code>(-(<i>insertion point</i>) - 1)</code> where <code>insertion point</code> is the index
* of <code>key</code> if it were contained in the list.
* @param <T> the object type in the list
*/
public static <T> int binarySearch(final ImmutableList<? extends T> il, final T key, final Comparator<? super T> comparator)
{
return Collections.binarySearch(il.toList(), key, comparator);
}
/**
* Determine if two immutable collections have no common members.
* @param ic1 ImmutableCollection<?>; ImmutableCollection<?> one immutable collection
* @param ic2 ImmutableCollection<?>; ImmutableCollection<?> another immutable collection
* @return boolean; true if the collections have no common members; false if the collections have at least one member in
* common
*/
public static boolean disjoint(final ImmutableCollection<?> ic1, final ImmutableCollection<?> ic2)
{
return Collections.disjoint(ic1.toCollection(), ic2.toCollection());
}
/**
* Determine if an immutable collection and a (non immutable) collection have no common members.
* @param ic1 ImmutableCollection<?>; ImmutableCollection<?> an immutable collection
* @param c2 Collection<?>; Collection<?> a (mutable) collection
* @return boolean; true if the collections have no common members; false if the collections have at least one member in
* common
*/
public static boolean disjoint(final ImmutableCollection<?> ic1, final Collection<?> c2)
{
return Collections.disjoint(ic1.toCollection(), c2);
}
/**
* Determine if an immutable collection and a (non immutable) collection have no common members.
* @param c1 Collection<?>; Collection<?> a (mutable) collection
* @param ic2 ImmutableCollection<?>; ImmutableCollection<?> an immutable collection
* @return boolean; true if the collections have no common members; false if the collections have at least one member in
* common
*/
public static boolean disjoint(final Collection<?> c1, final ImmutableCollection<?> ic2)
{
return Collections.disjoint(c1, ic2.toCollection());
}
/**
* Returns the starting position of the first occurrence of the specified target list within the specified source list, or
* -1 if there is no such occurrence.
* @param source ImmutableList<?>; the list in which to find the first occurrence of <code>target</code>
* @param target ImmutableList<?>; the pattern to find in <code>source</code>
* @return int; the index in <code>source</code> of the first occurrence of <code>target</code> or -1 if <code>target</code>
* does not occur anywhere in <code>source</code>
*/
public static int indexOfSubList(final ImmutableList<?> source, final ImmutableList<?> target)
{
return Collections.indexOfSubList(source.toList(), target.toList());
}
/**
* Returns the starting position of the first occurrence of the specified target list within the specified source list, or
* -1 if there is no such occurrence.
* @param source ImmutableList<?>; the list in which to find the first occurrence of <code>target</code>
* @param target List<?>; the pattern to find in <code>source</code>
* @return int; the index in <code>source</code> of the first occurrence of <code>target</code> or -1 if <code>target</code>
* does not occur anywhere in <code>source</code>
*/
public static int indexOfSubList(final ImmutableList<?> source, final List<?> target)
{
return Collections.indexOfSubList(source.toList(), target);
}
/**
* Returns the starting position of the first occurrence of the specified target list within the specified source list, or
* -1 if there is no such occurrence.
* @param source List<?>; the list in which to find the first occurrence of <code>target</code>
* @param target ImmutableList<?>; the pattern to find in <code>source</code>
* @return int; the index in <code>source</code> of the first occurrence of <code>target</code> or -1 if <code>target</code>
* does not occur anywhere in <code>source</code>
*/
public static int indexOfSubList(final List<?> source, final ImmutableList<?> target)
{
return Collections.indexOfSubList(source, target.toList());
}
/**
* Returns the starting position of the last occurrence of the specified target list within the specified source list, or -1
* if there is no such occurrence.
* @param source ImmutableList<?>; the list in which to find the last occurrence of <code>target</code>
* @param target ImmutableList<?>; the pattern to find in <code>source</code>
* @return int; the index in <code>source</code> of the last occurrence of <code>target</code> or -1 if <code>target</code>
* does not occur anywhere in <code>source</code>
*/
public static int lastIndexOfSubList(final ImmutableList<?> source, final ImmutableList<?> target)
{
return Collections.lastIndexOfSubList(source.toList(), target.toList());
}
/**
* Returns the starting position of the last occurrence of the specified target list within the specified source list, or -1
* if there is no such occurrence.
* @param source ImmutableList<?>; the list in which to find the last occurrence of <code>target</code>
* @param target List<?>; the pattern to find in <code>source</code>
* @return int; the index in <code>source</code> of the last occurrence of <code>target</code> or -1 if <code>target</code>
* does not occur anywhere in <code>source</code>
*/
public static int lastIndexOfSubList(final ImmutableList<?> source, final List<?> target)
{
return Collections.lastIndexOfSubList(source.toList(), target);
}
/**
* Returns the starting position of the last occurrence of the specified target list within the specified source list, or -1
* if there is no such occurrence.
* @param source List<?>; the list in which to find the last occurrence of <code>target</code>
* @param target ImmutableList<?>; the pattern to find in <code>source</code>
* @return int; the index in <code>source</code> of the last occurrence of <code>target</code> or -1 if <code>target</code>
* does not occur anywhere in <code>source</code>
*/
public static int lastIndexOfSubList(final List<?> source, final ImmutableList<?> target)
{
return Collections.indexOfSubList(source, target.toList());
}
/**
* Returns the maximum element of an immutable collection according to the <i>natural ordering</i> of its elements.
* @param ic ImmutableCollection<T extends Object & Comparable<? super T>>; the immutable collection
* @return T <T extends Object & Comparable<? super T>>; the maximum element in the immutable collection
* @throws NoSuchElementException if the immutable collection is empty.
* @param <T> the object type in the collection
*/
public static <T extends Object & Comparable<? super T>> T max(final ImmutableCollection<? extends T> ic)
{
return Collections.max(ic.toCollection());
}
/**
* Returns the maximum element of an immutable collection according to the <i>natural ordering</i> of its elements.
* @param ic ImmutableCollection<T extends Object & Comparable<? super T>>; the immutable collection
* @param comparator Comparator<? super T>; a comparator for <code>T</code>
* @return T <T extends Object & Comparable<? super T>>; the maximum element in the immutable collection
* @throws NoSuchElementException if the immutable collection is empty.
* @param <T> the object type in the collection
*/
public static <T extends Object> T max(final ImmutableCollection<? extends T> ic, final Comparator<? super T> comparator)
{
return Collections.max(ic.toCollection(), comparator);
}
/**
* Returns the minimum element of an immutable collection according to the <i>natural ordering</i> of its elements.
* @param ic ImmutableCollection<T extends Object & Comparable<? super T>>; the immutable collection
* @return T <T extends Object & Comparable<? super T>>; the minimum element in the immutable collection
* @throws NoSuchElementException if the immutable collection is empty.
* @param <T> the object type in the collection
*/
public static <T extends Object & Comparable<? super T>> T min(final ImmutableCollection<? extends T> ic)
{
return Collections.min(ic.toCollection());
}
/**
* Returns the minimum element of an immutable collection according to the <i>natural ordering</i> of its elements.
* @param ic ImmutableCollection<T extends Object & Comparable<? super T>>; the immutable collection
* @param comparator Comparator<? super T>; a comparator for <code>T</code>
* @return T <T extends Object & Comparable<? super T>>; the minimum element in the immutable collection
* @throws NoSuchElementException if the immutable collection is empty.
* @param <T> the object type in the collection
*/
public static <T extends Object> T min(final ImmutableCollection<? extends T> ic, final Comparator<? super T> comparator)
{
return Collections.min(ic.toCollection(), comparator);
}
/**
* Return the number of occurrences of an object in an immutable collection.
* @param ic ImmutableCollection<?>; the immutable collection
* @param o Object; the object to count the number occurrences of
* @return int; the number of occurrences of <code>o</code> in <code>ic</code>
*/
public static int frequency(final ImmutableCollection<?> ic, final Object o)
{
return Collections.frequency(ic.toCollection(), o);
}
}