Package com.mckoi.util

## Interface IntegerListInterface

All Known Implementing Classes:
  `AbstractBlockIntegerList`, `BlockIntegerList`

    public interface IntegerListInterface

An interface for querying and accessing a list of primitive integers. The list may or may not be sorted or may be sorted over an IndexComparator. This interface exposes general list querying/inserting/removing methods.

How the list is physically stored is dependant on the implementation of the interface. An example of an implementation is 'BlockIntegerList'.

Author:
  Tobias Downer

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `add​(int val)` Adds an int to the end of the list.
`void` `add​(int val, int pos)` Adds an integet to the given position in the list.
`boolean` `contains​(int val)` Assuming the list is sorted, this performs a binary search and returns true if the value is found, otherwise returns false.
`boolean` `contains​(java.lang.Object key, IndexComparator c)` Assuming the list is sorted, this performs a binary search and returns true if the key value is found, otherwise returns false.
`int` `get​(int pos)` Returns the int at the given position (0 first, 1 second, etc) in the list.
`void` `insertSort​(int val)` Inserts plain 'int' values into the list in sorted order.
`void` `insertSort​(java.lang.Object key, int val, IndexComparator c)` Inserts the key/index pair into the list at the correct sorted position (determine by the IndexComparator).
`boolean` `isImmutable()` Returns true if this interface is immutable.
`IntegerIterator` `iterator()` Returns an IntegerIterator that will walk from the start to the end this list.
`IntegerIterator` `iterator​(int start_offset, int end_offset)` Returns an IntegerIterator that will walk from the start offset (inclusive) to the end offset (inclusive) of this list.
`int` `remove​(int pos)` Removes an int from the given position in the list.
`boolean` `removeSort​(int val)` Removes a plain 'int' value from the sorted position in the list only if it's already in the list.
`int` `removeSort​(java.lang.Object key, int val, IndexComparator c)` Removes the key/val pair from the list by first searching for it, and then removing it from the list.
`int` `searchFirst​(java.lang.Object key, IndexComparator c)` Returns the index of the first value in this set that equals the given value.
`int` `searchLast​(java.lang.Object key, IndexComparator c)` Returns the index of the last value in this set that equals the given value.
`void` `setImmutable()` Makes this list immutable effectively making it read-only.
`int` `size()` The number of integers that are in the list.
`boolean` `uniqueInsertSort​(int val)` Inserts plain 'int' value into the sorted position in the list only if it isn't already in the list.

### Method Detail

#### setImmutable

    void setImmutable()

Makes this list immutable effectively making it read-only. After this method, any calls to methods that modify the list will throw an error.

Once 'setImmutable' is called, the list can not be changed back to being mutable.

#### isImmutable

    boolean isImmutable()

Returns true if this interface is immutable.

#### size

    int size()

The number of integers that are in the list.

#### get

    int get​(int pos)

Returns the int at the given position (0 first, 1 second, etc) in the list. If the position is out of bounds an exception is thrown.

#### add

    void add​(int val,
             int pos)

Adds an integet to the given position in the list. If the position is out of bounds an exception is thrown. Any values after the given position are shifted forward.

#### add

    void add​(int val)

Adds an int to the end of the list.

#### remove

    int remove​(int pos)

Removes an int from the given position in the list. Returns the value that was removed from the removed position. If the position is out of bounds an exception is thrown.

#### contains

    boolean contains​(int val)

Assuming the list is sorted, this performs a binary search and returns true if the value is found, otherwise returns false. If the list is not sorted then this may return false even if the list does contain the value.

#### insertSort

    void insertSort​(int val)

Inserts plain 'int' values into the list in sorted order.

#### uniqueInsertSort

    boolean uniqueInsertSort​(int val)

Inserts plain 'int' value into the sorted position in the list only if it isn't already in the list. If the value is inserted it returns true, otherwise if the value wasn't inserted because it's already in the list, it returns false.

#### removeSort

    boolean removeSort​(int val)

Removes a plain 'int' value from the sorted position in the list only if it's already in the list. If the value is removed it returns true, otherwise if the value wasn't removed because it couldn't be found in the list, it returns false.

#### contains

    boolean contains​(java.lang.Object key,
                     IndexComparator c)

Assuming the list is sorted, this performs a binary search and returns true if the key value is found, otherwise returns false.

#### insertSort

    void insertSort​(java.lang.Object key,
                    int val,
                    IndexComparator c)

Inserts the key/index pair into the list at the correct sorted position (determine by the IndexComparator). If the list already contains identical key then the value is add to the end of the set of identical values in the list. This way, the sort is stable (the order of identical elements does not change).

#### removeSort

    int removeSort​(java.lang.Object key,
                   int val,
                   IndexComparator c)

Removes the key/val pair from the list by first searching for it, and then removing it from the list. This method uses the IndexComparator object to compare an index position in the list to an object to compare against.

#### searchLast

    int searchLast​(java.lang.Object key,
                   IndexComparator c)

Returns the index of the last value in this set that equals the given value. This method uses the IndexComparator object to compare an index position in the list to an object to compare against.

#### searchFirst

    int searchFirst​(java.lang.Object key,
                    IndexComparator c)

Returns the index of the first value in this set that equals the given value. This method uses the IndexComparator object to compare an index position in the list to an object to compare against.

#### iterator

    IntegerIterator iterator​(int start_offset,
                             int end_offset)

Returns an IntegerIterator that will walk from the start offset (inclusive) to the end offset (inclusive) of this list.

#### iterator

    IntegerIterator iterator()

Returns an IntegerIterator that will walk from the start to the end this list.