added test cases

Author: wadoon

key.util/src/main/java/org/key_project/util/collection/ImmutableList.java

@@ -3,18 +3,21 @@
  * SPDX-License-Identifier: GPL-2.0-only */
 package org.key_project.util.collection;
 
+import org.jspecify.annotations.Nullable;
+
+import java.lang.reflect.Array;
 import java.util.*;
 import java.util.function.Function;
 import java.util.function.Predicate;
 import java.util.stream.Collector;
+import java.util.stream.Collectors;
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
 
-import org.jspecify.annotations.Nullable;
-
 /**
  * List interface to be implemented by non-destructive lists
  */
+@SuppressWarnings("unchecked")
 public interface ImmutableList<T extends @Nullable Object>
         extends Iterable<T>, java.io.Serializable {
 
@@ -31,14 +34,28 @@ public interface ImmutableList<T extends @Nullable Object>
         }, ImmutableList::fromList);
     }
 
-    /**
-     * Creates an ImmutableList from a List.
-     *
-     * @param list a List.
-     * @return an ImmutableList containing the same elements as the specified list.
-     */
+    /// Creates an [ImmutableList] from an [Iterable].
+    /// This method is not recommended to use as space overhead is required.
+    ///
+    /// @param list a List.
+    /// @return an ImmutableList containing the same elements as the specified list.
+    /// @see #fromList(List)
+    /// @see #fromArray(Object[])
     static <T extends @Nullable Object> ImmutableList<T> fromList(Iterable<? extends T> list) {
-        return new ImmutableListList<>(list);
+        // Short-cuts, iterables are often lists, if so use them and try to avoid copy.
+        if (list instanceof ImmutableList<?> ilist) {
+            return (ImmutableList<T>) ilist;
+        }
+
+        if (list instanceof List<?> ilist) {
+            return fromList((List<T>) ilist);
+        }
+
+        List<T> seq = new ArrayList<>(64);
+        for (var t : list) {
+            seq.add(t);
+        }
+        return fromList(seq);
     }
 
     static <T extends @Nullable Object> ImmutableList<T> fromList(List<T> list) {
@@ -53,8 +70,8 @@ public interface ImmutableList<T extends @Nullable Object>
     /**
      * Return an empty immutable list.
      *
-     * @return empty immutable list.
      * @param <T> the entry type of the list.
+     * @return empty immutable list.
      */
     static <T extends @Nullable Object> ImmutableList<T> of() {
         return nil();
@@ -63,66 +80,51 @@ public interface ImmutableList<T extends @Nullable Object>
     /**
      * Return a singleton immutable list.
      *
-     * @param e1 the element to put into the list
-     * @return singleton immutable list.
+     * @param e1  the element to put into the list
      * @param <T> the entry type of the list.
+     * @return singleton immutable list.
      */
     static <T extends @Nullable Object> ImmutableList<T> of(T e1) {
         return singleton(e1);
     }
 
-    /**
-     * Return an immutable list with two elements.
-     * The iteration order is: e1 then e2
-     *
-     * @param e1 the element to put into the list
-     * @param e2 the element to put into the list
-     * @return (e1, e2) as immutable list
-     * @param <T> the entry type of the list.
-     */
-    static <T extends @Nullable Object> ImmutableList<T> of(T e1, T e2) {
-        return singleton(e2).prepend(e1);
-    }
-
-    /**
-     * Return an immutable list with three elements.
-     * The iteration order is: e1 then e2 then e3
-     *
-     * @param e1 the element to put into the list
-     * @param e2 the element to put into the list
-     * @param e3 the element to put into the list
-     * @return (e1, e2, e3) as immutable list
-     * @param <T> the entry type of the list.
-     */
-    static <T extends @Nullable Object> ImmutableList<T> of(T e1, T e2, T e3) {
-        return singleton(e3).prepend(e2).prepend(e1);
-    }
-
     /**
      * Return an immutable list with the iterated elements.
      * The iteration order is the order of the arguments
      *
-     * @param es the elements to put into the list
-     * @return (e1, e2, e3, ...) as immutable list
+     * @param es  the elements to put into the list
      * @param <T> the entry type of the list.
+     * @return (e1, e2, e3, ...) as immutable list
      */
     static <T extends @Nullable Object> ImmutableList<T> of(T... es) {
+        if (es.length == 0) {
+            return of();
+        }
+        return new ImmutableListArray<>(es);
+
+        /*
         ImmutableList<T> result = nil();
         for (int i = es.length - 1; i >= 0; i--) {
             result = result.prepend(es[i]);
         }
-        return result;
+        return result;*/
     }
 
-    /** the empty list */
-    static <T extends @Nullable Object> ImmutableSLList<T> nil() {
+    /**
+     * the empty list
+     */
+    static <T extends @Nullable Object> ImmutableList<T> nil() {
         return (ImmutableSLList<T>) ImmutableSLList.NIL.NIL;
     }
 
-    static <T extends @Nullable Object> ImmutableSLList<T> singleton(T obj) {
+    static <T extends @Nullable Object> ImmutableList<T> singleton(T obj) {
         return new ImmutableSLList.Cons<>(obj, nil());
     }
 
+    static <T extends @Nullable Object> String toString(ImmutableList<T> seq) {
+        return seq.stream().map(Objects::toString).collect(Collectors.joining(", ", "[", "]"));
+    }
+
     default ImmutableList<T> prepend(T element) {
         return new ImmutableListConcat<>(ImmutableList.singleton(element), this);
     }
@@ -168,11 +170,18 @@ default T head() {
 
     /**
      * return true if predicate is fullfilled for at least one element
+     * <p>
+     * The default implementation is based on the {@link #stream()} functionality
      *
      * @param predicate the predicate
      * @return true if predicate is fullfilled for at least one element
+     * @see #stream()
+     * @see #spliterator()
+     *
      */
-    boolean exists(Predicate<? super T> predicate);
+    default boolean exists(Predicate<? super T> predicate) {
+        return stream().anyMatch(predicate);
+    }
 
     /**
      * @return IList<T> tail of list
@@ -190,6 +199,9 @@ default ImmutableList<T> skip(int n) {
      * @return IList<T> this list without the first <code>n</code> elements
      */
     default ImmutableList<T> take(int n) {
+        if (n == 0) {
+            return nil();
+        }
         return new ImmutableListSubList<>(this, 0, n);
     }
 
@@ -204,7 +216,21 @@ default ImmutableList<T> reverse() {
      * @return Iterator<T> of this list
      */
     @Override
-    Iterator<T> iterator();
+    default Iterator<T> iterator() {
+        return new Iterator<>() {
+            int cursor = 0;
+
+            @Override
+            public boolean hasNext() {
+                return cursor < size();
+            }
+
+            @Override
+            public T next() {
+                return get(cursor++);
+            }
+        };
+    }
 
     /**
      * @return boolean is true iff. obj is in List
@@ -239,21 +265,49 @@ default boolean contains(@Nullable Object obj) {
      */
     ImmutableList<T> removeAll(T obj);
 
-    /**
-     * Convert the list to a Java array (O(n))
-     */
-    <S extends @Nullable Object> S[] toArray(S[] array);
+    /// Convert the list to a Java array (O(n)) based on the {@link #iterator()} implementation.
+    /// If you can convert faster, feel free to override.
+    ///
+    /// @see #iterator()
+    @SuppressWarnings("unchecked")
+    default <S extends @Nullable Object> S[] toArray(S[] array) {
+        S[] result;
+        if (array.length < size()) {
+            Class<? extends Object[]> arrayClass = array.getClass();
+            assert arrayClass.isArray()
+                    : "@AssumeAssertion(nullness): This has indeed a component type";
+            result = (S[]) Array.newInstance(arrayClass.getComponentType(), size());
+        } else {
+            result = array;
+        }
 
-    /**
-     * Convert the list to a Java array (O(n))
-     */
-    <S extends @Nullable Object> S[] toArray(Class<S> type);
+        int pos = 0;
+        for (var item : this) {
+            result[pos++] = (S) item;
+        }
+        return result;
+    }
+
+    /// Convert the list to a Java array (O(n)) of the given class `type`.
+    ///
+    /// @see #iterator()
+    default <S extends @Nullable Object> S[] toArray(Class<S> type) {
+        S[] result = (S[]) Array.newInstance(type, size());
+        int pos = 0;
+        for (var head : this) {
+            // Somehow the nullness checker needs this cast to be explicit.
+            result[pos++] = (S) type.cast(head);
+        }
+        return result;
+    }
 
 
     /**
      * A stream object for this collection.
      *
      * @return a non-null stream object
+     * @see #spliterator()
+     * @see #iterator()
      */
     default Stream<T> stream() {
         return StreamSupport.stream(this.spliterator(), false);
@@ -277,9 +331,8 @@ default List<T> toList() {
      * the given predicate.
      *
      * @param predicate a non-interfering, stateless
-     *        predicate to apply to each element to determine if it
-     *        should be included
-     *
+     *                  predicate to apply to each element to determine if it
+     *                  should be included
      * @return the filtered list
      */
     default ImmutableList<T> filter(Predicate<? super T> predicate) {
@@ -290,7 +343,7 @@ default ImmutableList<T> filter(Predicate<? super T> predicate) {
      * Returns an immutable list consisting of the results of applying the given
      * function to the elements of this list.
      *
-     * @param <R> The element type of the result list
+     * @param <R>      The element type of the result list
      * @param function a non-interfering, stateless function to apply to each element
      * @return the mapped list of the same length as this
      */
@@ -339,9 +392,9 @@ default ImmutableList<T> stripPrefix(ImmutableList<? extends T> prefix) {
      *
      * @return last element of this list
      */
-    default T last() {
+    default T last() throws NoSuchElementException {
         if (isEmpty()) {
-            throw new IllegalStateException("last() called on empty list");
+            throw new NoSuchElementException("last() called on empty list");
         }
         ImmutableList<T> remainder = this;
         while (!remainder.tail().isEmpty()) {
@@ -358,10 +411,23 @@ default T last() {
      * @param idx the 0-based index of the element
      * @return the element at index idx.
      * @throws IndexOutOfBoundsException if idx is less than 0 or at
-     *         least {@link #size()}.
+     *                                   least {@link #size()}.
      */
-    default T get(int idx) {
-        return take(idx).head();
+    T get(int idx);
+
+    /// compares two {@link ImmutableList} content-wise
+    static boolean equals(
+            ImmutableList<?> seq1, ImmutableList<?> seq2) {
+
+        final var size = seq1.size();
+        if (size == seq2.size()) {
+            for (int i = 0; i < size; i++) {
+                if (!Objects.equals(seq1.get(i), seq2.get(i))) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        return false;
     }
-
 }