Package org.javimmutable.collections

Interface IArray<T>

All Superinterfaces:
ICollection<IMapEntry<Integer,T>>, Indexed<T>, InvariantCheckable, IStreamable<IMapEntry<Integer,T>>, Iterable<IMapEntry<Integer,T>>, Serializable, SplitableIterable<IMapEntry<Integer,T>>
All Known Implementing Classes:
TrieArray
@Immutable public interface IArray<T> extends Indexed<T>, ICollection<IMapEntry<Integer,T>>, InvariantCheckable, Serializable
Immutable sparse array implementation using integers as keys. Keys are traversed in signed integer order by Iterators so negative values are visited before positive values. Implementations are allowed to restrict the range of allowable indexes for performance or other reasons. Implementations should throw IndexOutOfBounds exceptions if presented with an invalid index.

Arrays are sparse meaning that they can contain elements at any valid index with no need to keep them consecutive (like a List). Memory is managed to use no more than necessary for the number of elements currently in the array.

  • Method Details

    • get

      @Nullable T get(int index)
      Return the value associated with index or null if no value is associated. Note that if null is an acceptable value to the container then this method will be ambiguous and find() should be used instead.
      Specified by:
      get in interface Indexed<T>
      Parameters:
      index - identifies the value to retrieve
      Returns:
      value associated with index or null if no value is associated

    • getValueOr

      T getValueOr(int index, @Nullable T defaultValue)
      Return the value associated with index or defaultValue if no value is associated. Note that if defaultValue is an acceptable value to the container then this method will be ambiguous and find() should be used instead.
      Parameters:
      index - identifies the value to retrieve
      defaultValue - value to return if no entry exists for index
      Returns:
      value associated with index or defaultValue if no value is associated

    • find

      @Nonnull Maybe<T> find(int index)
      Return a Holder containing the value associated wth the index or an empty Holder if no value is associated with the index.
      Specified by:
      find in interface Indexed<T>
      Parameters:
      index - identifies the value to retrieve
      Returns:
      possibly empty Holder containing any value associated with the index

    • findEntry

      @Nonnull Maybe<IMapEntry<Integer,T>> findEntry(int index)
      Search for an Entry within the map and return a Holder indicating if the Entry was found and, if it was found, the Entry itself.
      Parameters:
      index - index to search for
      Returns:
      empty Holder if not found, otherwise filled Holder with Entry

    • insert

      @Nonnull IArray<T> insert(IMapEntry<Integer,T> value)
      Description copied from interface: ICollection
      Add value to the container in some manner appropriate to the implementation.
      Specified by:
      insert in interface ICollection<T>

    • insertAll

      @Nonnull IArray<T> insertAll(@Nonnull Iterator<? extends IMapEntry<Integer,T>> iterator)
      Description copied from interface: ICollection
      Add all values to the container in some manner appropriate to the implementation.
      Specified by:
      insertAll in interface ICollection<T>

    • insertAll

      @Nonnull IArray<T> insertAll(@Nonnull Iterable<? extends IMapEntry<Integer,T>> iterable)
      Description copied from interface: ICollection
      Add all values to the container in some manner appropriate to the implementation.
      Specified by:
      insertAll in interface ICollection<T>

    • assign

      @Nonnull IArray<T> assign(int index, @Nullable T value)
      Sets the value associated with a specific index. Index must be non-null but value can be null. If the index already has a value in the map the old value is discarded and the new value is stored in its place. Returns a new IMap reflecting any changes. The original map is always left unchanged.
      Parameters:
      index - index
      value - possibly null value
      Returns:
      new map reflecting the change

    • delete

      @Nonnull IArray<T> delete(int index)
      Deletes the entry for the specified index (if any). Returns a new map if the value was deleted or the current map if the index was not contained in the map.
      Parameters:
      index - index
      Returns:
      same or different map depending on whether index was removed

    • deleteAll

      @Nonnull IArray<T> deleteAll()
      Specified by:
      deleteAll in interface ICollection<T>
      Returns:
      an equivalent collection with no values

    • getMap

      @Nonnull Map<Integer,T> getMap()
      Creates an unmodifiable java.util.Map reflecting the values of the IMap backing the array.
      Returns:
      Map view of this IMap

    • keys

      @Nonnull IStreamable<Integer> keys()
      Creates an IStreamable to access all of the array's keys.

    • values

      @Nonnull IStreamable<T> values()
      Creates an IStreamable to access all of the array's values.

    • forEach

      void forEach(@Nonnull IndexedProc1<T> proc)
      Visits every element in the array in order by index and passes the index and value to the provided lambda. Unlike indexedForEach method the index values passed to the lambda are the actual key value in the array.

    • forEachThrows

      <E extends Exception> void forEachThrows(@Nonnull IndexedProc1Throws<T,E> proc) throws E
      Visits every element in the array in order by index and passes the index and value to the provided lambda. Unlike indexedForEach method the index values passed to the lambda are the actual key value in the array.
      Throws:
      E

    • toBuilder

      @Nonnull IArrayBuilder<T> toBuilder()
      Creates and returns a new Builder object for the same value type as this array.
      Returns:
      An empty Builder object ready for use to create a new IArray.