Class IntegerList

All Implemented Interfaces:
Serializable, Cloneable, Iterable<Integer>, Collection<Integer>, List<Integer>, RandomAccess, SequencedCollection<Integer>

public class IntegerList extends AbstractList<Integer> implements RandomAccess, Serializable, Cloneable
A list of unsigned integer values. This class packs the values in the minimal amount of bits required for storing unsigned integers of the given maximal value.

This class is not thread-safe. Synchronizations (if wanted) are user's responsibility.

Since:
0.7
Version:
1.1
See Also:
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • VALUE_SIZE

      private static final int VALUE_SIZE
      The size of the primitive type used for the values array.
      See Also:
    • BASE_SHIFT

      private static final int BASE_SHIFT
      The shift to apply on index in order to produce a result equivalent to index / 64. The following relation must hold: (1 << BASE_SHIFT) == VALUE_SIZE.
      See Also:
    • OFFSET_MASK

      private static final int OFFSET_MASK
      The mask to apply on index in order to produce a result equivalent to index % 64.
      See Also:
    • values

      private long[] values
      The packed values. We use the long type instead of int since 64 bits machines are common now.
    • bitCount

      private final int bitCount
      The bit count for values.
    • mask

      private final int mask
      The mask computed as (1 << bitCount) - 1.
    • size

      private int size
      The list size. Initially 0.
      See Also:
  • Constructor Details

    • IntegerList

      public IntegerList(int initialCapacity, int maximalValue)
      Creates an initially empty list with the given initial capacity.
      Parameters:
      initialCapacity - the initial capacity.
      maximalValue - the maximal value to be allowed, inclusive.
    • IntegerList

      public IntegerList(int initialCapacity, int maximalValue, boolean fill)
      Creates a new list with the given initial size. The value of all elements are initialized to 0.
      Parameters:
      initialCapacity - the initial capacity.
      maximalValue - the maximal value to be allowed, inclusive.
      fill - if true, the initial size is set to the initial capacity with all values set to 0.
  • Method Details

    • length

      private int length(int capacity)
      Returns the array length required for holding a list of the given size.
      Parameters:
      capacity - the desired list size.
      Returns:
      the array length for holding a list of the given size.
    • maximalValue

      public int maximalValue()
      Returns the maximal value that can be stored in this list. May be slightly higher than the value given to the constructor.
      Returns:
      the maximal value, inclusive.
    • size

      public int size()
      Returns the current number of values in this list.
      Specified by:
      size in interface Collection<Integer>
      Specified by:
      size in interface List<Integer>
      Specified by:
      size in class AbstractCollection<Integer>
      Returns:
      the number of values.
    • resize

      public void resize(int size)
      Sets the list size to the given value. If the new size is lower than previous size, then the elements after the new size are discarded. If the new size is greater than the previous one, then the extra elements are initialized to 0.
      Parameters:
      size - the new size.
      See Also:
    • fill

      public void fill(int value)
      Fills the list with the given value. Every existing values are overwritten from index 0 inclusive up to size() exclusive.
      Parameters:
      value - the value to set.
    • clear

      public void clear()
      Discards all elements in this list.
      Specified by:
      clear in interface Collection<Integer>
      Specified by:
      clear in interface List<Integer>
      Overrides:
      clear in class AbstractList<Integer>
    • add

      public boolean add(Integer value) throws IllegalArgumentException
      Adds the given element to this list.
      Specified by:
      add in interface Collection<Integer>
      Specified by:
      add in interface List<Integer>
      Overrides:
      add in class AbstractList<Integer>
      Parameters:
      value - the value to add.
      Returns:
      always true.
      Throws:
      NullPointerException - if the given value is null.
      IllegalArgumentException - if the given value is out of bounds.
    • addInt

      public void addInt(int value) throws IllegalArgumentException
      Adds the given element as the int primitive type.
      Parameters:
      value - the value to add.
      Throws:
      IllegalArgumentException - if the given value is out of bounds.
      See Also:
    • get

      public Integer get(int index) throws IndexOutOfBoundsException
      Returns the element at the given index.
      Specified by:
      get in interface List<Integer>
      Specified by:
      get in class AbstractList<Integer>
      Parameters:
      index - the element index.
      Returns:
      the value at the given index.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
    • getInt

      public int getInt(int index) throws IndexOutOfBoundsException
      Returns the element at the given index as the int primitive type.
      Parameters:
      index - the element index.
      Returns:
      the value at the given index.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
    • getUnchecked

      private int getUnchecked(int index)
      Returns the element at the given index as the int primitive type. This argument does not check argument validity, since the verification is assumed already done.
      Parameters:
      index - the element index.
      Returns:
      the value at the given index.
    • set

      public Integer set(int index, Integer value) throws IndexOutOfBoundsException
      Sets the element at the given index.
      Specified by:
      set in interface List<Integer>
      Overrides:
      set in class AbstractList<Integer>
      Parameters:
      index - the element index.
      value - the value at the given index.
      Returns:
      the previous value at the given index.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      IllegalArgumentException - if the given value is out of bounds.
      NullPointerException - if the given value is null.
    • setInt

      public void setInt(int index, int value) throws IndexOutOfBoundsException
      Sets the element at the given index as the int primitive type.
      Parameters:
      index - the element index.
      value - the value at the given index.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
      IllegalArgumentException - if the given value is out of bounds.
    • setUnchecked

      private void setUnchecked(int index, int value)
      Sets the element at the given index as the int primitive type. This argument does not check argument validity, since the verification is assumed already done.
      Parameters:
      index - the element index.
      value - the value at the given index.
    • remove

      public Integer remove(int index) throws IndexOutOfBoundsException
      Removes the element at the given index.
      Specified by:
      remove in interface List<Integer>
      Overrides:
      remove in class AbstractList<Integer>
      Parameters:
      index - the index of the element to remove.
      Returns:
      the previous value of the element at the given index.
      Throws:
      IndexOutOfBoundsException - if the given index is out of bounds.
    • removeLast

      public int removeLast() throws NoSuchElementException
      Retrieves and remove the last element of this list.
      Specified by:
      removeLast in interface List<Integer>
      Specified by:
      removeLast in interface SequencedCollection<Integer>
      Returns:
      the tail of this list.
      Throws:
      NoSuchElementException - if this list is empty.
    • removeRange

      protected void removeRange(int lower, int upper)
      Removes all values in the given range of index. Shifts any succeeding elements to the left (reduces their index).
      Overrides:
      removeRange in class AbstractList<Integer>
      Parameters:
      lower - index of the first element to remove, inclusive.
      upper - index after the last element to be removed.
    • occurrence

      public int occurrence(int value)
      Returns the occurrence of the given value in this list.
      Parameters:
      value - the value to search for.
      Returns:
      the number of time the given value occurs in this list.
    • iterator

      public PrimitiveIterator.OfInt iterator()
      Returns an iterator over the elements in this list in increasing index order. The iterator is fail-fast and supports the remove operation.
      Specified by:
      iterator in interface Collection<Integer>
      Specified by:
      iterator in interface Iterable<Integer>
      Specified by:
      iterator in interface List<Integer>
      Overrides:
      iterator in class AbstractList<Integer>
      Returns:
      iterator over the integer values in this list.
      Since:
      0.8-jdk8
    • spliterator

      public Spliterator.OfInt spliterator()
      Returns an spliterator over the elements in this list in increasing index order. The iterator is fail-fast.
      Specified by:
      spliterator in interface Collection<Integer>
      Specified by:
      spliterator in interface Iterable<Integer>
      Specified by:
      spliterator in interface List<Integer>
      Returns:
      spliterator over the integer values in this list.
      Since:
      0.8-jdk8
    • stream

      public IntStream stream(boolean parallel)
      Returns a stream of integers with this IntegerList as its source. This method is similar to Collection.stream(), but does not box the values. The returned stream is fail-fast, meaning that any modification to the list while using the stream will cause a ConcurrentModificationException to be thrown.

      The default implementation creates a parallel or sequential stream from spliterator().

      Parameters:
      parallel - true for a parallel stream, or false for a sequential stream.
      Returns:
      a stream of values in this list as primitive types.
      Since:
      0.8-jdk8
    • writeObject

      private void writeObject(ObjectOutputStream out) throws IOException
      Invokes trimToSize() before serialization in order to make the stream more compact.
      Parameters:
      out - the output stream where to serialize this list.
      Throws:
      IOException - if an I/O error occurred while writing.
    • trimToSize

      public void trimToSize()
      Trims the capacity of this list to be its current size.
      See Also:
    • equals

      public boolean equals(Object other)
      Compares the content of this list with the given object. This method overrides the default implementation for performance reasons.
      Specified by:
      equals in interface Collection<Integer>
      Specified by:
      equals in interface List<Integer>
      Overrides:
      equals in class AbstractList<Integer>
      Parameters:
      other - the other object to compare with this list.
      Returns:
      true if both object are equal.
      Since:
      1.1
    • clone

      public IntegerList clone()
      Returns a clone of this list.
      Overrides:
      clone in class Object
      Returns:
      a clone of this list.