Package org.djutils.immutablecollections

Interface ImmutableCollection<E>

Type Parameters:
E - the type of content of this Collection
All Superinterfaces:
Iterable<E>, Serializable
All Known Subinterfaces:
ImmutableList<E>, ImmutableNavigableSet<E>, ImmutableSet<E>, ImmutableSortedSet<E>
All Known Implementing Classes:
ImmutableAbstractCollection, ImmutableAbstractList, ImmutableAbstractSet, ImmutableArrayList, ImmutableHashSet, ImmutableLinkedHashSet, ImmutableTreeSet, ImmutableVector
public interface ImmutableCollection<E> extends Iterable<E>, Serializable
A Collection interface without the methods that can change it.

Copyright (c) 2016-2024 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information https://djutils.org. The DJUTILS project is distributed under a three-clause BSD-style license, which can be found at https://djutils.org/docs/license.html.

Author:
Alexander Verbraeck, Peter Knoppers

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    contains(Object o)
    Returns true if this immutable collection contains the specified element.
    boolean
    containsAll(Collection<?> c)
    Returns true if this immutable collection contains all of the elements in the specified collection.
    boolean
    containsAll(ImmutableCollection<?> c)
    Returns true if this immutable collection contains all of the elements in the specified immutable collection.
    boolean
    equals(Object obj)
    Force to redefine equals for the implementations of immutable collection classes.
    int
    hashCode()
    Force to redefine hashCode for the implementations of immutable collection classes.
    default boolean
    isCopy()
    Return whether the internal storage is a (shallow) copy of the original collection.
    boolean
    isEmpty()
    Returns true if this immutable collection contains no elements.
    boolean
    isWrap()
    Return whether the internal storage is a wrapped pointer to the original collection.
    ImmutableIterator<E>
    iterator()
    Returns an immutable iterator over the elements in this immutable collection.
    default Stream<E>
    parallelStream()
    Returns a possibly parallel Stream with this collection as its source.
    int
    size()
    Returns the number of elements in this immutable collection.
    default Spliterator<E>
    spliterator()
    Creates a Spliterator over the elements in this collection.
    default Stream<E>
    stream()
    Returns a sequential Stream with this collection as its source.
    Object[]
    toArray()
    Returns an array containing all of the elements in this immutable collection.
    <T> T[]
    toArray(T[] a)
    Returns an array containing all of the elements in this immutable collection; the runtime type of the returned array is that of the specified array.
    Collection<E>
    toCollection()
    Returns a modifiable copy of this immutable collection.

    Methods inherited from interface java.lang.Iterable

    forEach

  • Method Details

    • size

      int size()
      Returns the number of elements in this immutable collection. If this immutable collection contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
      Returns:
      the number of elements in this immutable collection

    • isEmpty

      boolean isEmpty()
      Returns true if this immutable collection contains no elements.
      Returns:
      true if this immutable collection contains no elements

    • contains

      boolean contains(Object o)
      Returns true if this immutable collection contains the specified element. More formally, returns true if and only if this immutable collection contains at least one element e such that (o==null ? e==null : o.equals(e)).
      Parameters:
      o - Object; element whose presence in this immutable collection is to be tested
      Returns:
      true if this immutable collection contains the specified element
      Throws:
      ClassCastException - if the type of the specified element is incompatible with this immutable collection
      NullPointerException - if the specified element is null and this immutable collection does not permit null elements

    • iterator

      ImmutableIterator<E> iterator()
      Returns an immutable iterator over the elements in this immutable collection. There are no guarantees concerning the order in which the elements are returned (unless this immutable collection is an instance of some class that provides a guarantee). The ImmutableIterator is an Iterator where the remove() operation will throw an exception.
      Specified by:
      iterator in interface Iterable<E>
      Returns:
      an ImmutableIterator over the elements in this immutable collection

    • toArray

      Object[] toArray()
      Returns an array containing all of the elements in this immutable collection. If this immutable collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

      See java.util.Collection.toArray() for more details.

      Returns:
      an array containing all of the elements in this immutable collection

    • toArray

      <T> T[] toArray(T[] a)
      Returns an array containing all of the elements in this immutable collection; the runtime type of the returned array is that of the specified array. If the immutable collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this immutable collection.

      See java.util.Collection.toArray(T[]) for more details.

      Type Parameters:
      T - the runtime type of the array to contain the immutable collection
      Parameters:
      a - the array into which the elements of this immutable collection are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
      Returns:
      an array containing all of the elements in this immutable collection
      Throws:
      ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this immutable collection
      NullPointerException - if the specified array is null

    • containsAll

      boolean containsAll(Collection<?> c)
      Returns true if this immutable collection contains all of the elements in the specified collection.
      Parameters:
      c - Collection<?>; collection to be checked for containment in this immutable collection
      Returns:
      true if this immutable collection contains all of the elements in the specified collection
      Throws:
      ClassCastException - if the types of one or more elements in the specified collection are incompatible with this immutable collection
      NullPointerException - if the specified collection contains one or more null elements and this immutable collection does not permit null elements, or if the specified collection is null.
      See Also:

    • containsAll

      boolean containsAll(ImmutableCollection<?> c)
      Returns true if this immutable collection contains all of the elements in the specified immutable collection.
      Parameters:
      c - ImmutableCollection<?>; immutable collection to be checked for containment in this immutable collection
      Returns:
      true if this immutable collection contains all of the elements in the specified immutable collection
      Throws:
      ClassCastException - if the types of one or more elements in the specified immutable collection are incompatible with this immutable collection
      NullPointerException - if the specified immutable collection contains one or more null elements and this immutable collection does not permit null elements, or if the specified immutable collection is null.
      See Also:

    • spliterator

      default Spliterator<E> spliterator()
      Creates a Spliterator over the elements in this collection. Implementations should document characteristic values reported by the spliterator. See java.util.Collection for more information.
      Specified by:
      spliterator in interface Iterable<E>
      Returns:
      a Spliterator over the elements in this collection

    • stream

      default Stream<E> stream()
      Returns a sequential Stream with this collection as its source.

      This method should be overridden when the spliterator() method cannot return a spliterator that is IMMUTABLE, CONCURRENT, or late-binding. (See spliterator() for details.)

      Returns:
      a sequential Stream over the elements in this collection

    • parallelStream

      default Stream<E> parallelStream()
      Returns a possibly parallel Stream with this collection as its source. It is allowable for this method to return a sequential stream.

      This method should be overridden when the spliterator() method cannot return a spliterator that is IMMUTABLE, CONCURRENT, or late-binding. (See spliterator() for details.)

      Returns:
      a possibly parallel Stream over the elements in this collection

    • toCollection

      Collection<E> toCollection()
      Returns a modifiable copy of this immutable collection.
      Returns:
      a modifiable copy of this immutable collection.

    • equals

      boolean equals(Object obj)
      Force to redefine equals for the implementations of immutable collection classes.
      Overrides:
      equals in class Object
      Parameters:
      obj - Object; the object to compare this collection with
      Returns:
      whether the objects are equal

    • hashCode

      int hashCode()
      Force to redefine hashCode for the implementations of immutable collection classes.
      Overrides:
      hashCode in class Object
      Returns:
      the calculated hashCode

    • isWrap

      boolean isWrap()
      Return whether the internal storage is a wrapped pointer to the original collection. If true, this means that anyone holding a pointer to this data structure can still change it. The users of the ImmutableCollection itself can, however, not make any changes.
      Returns:
      boolean; whether the internal storage is a wrapped pointer to the original collection

    • isCopy

      default boolean isCopy()
      Return whether the internal storage is a (shallow) copy of the original collection. If true, this means that anyone holding a pointer to the original of the data structure can not change it anymore. Nor can the users of the ImmutableCollection itself make any changes.
      Returns:
      boolean; whether the internal storage is a safe copy of the original collection