com.bluegosling.collections.lists

Interface AssociativeList<E,K>

Type Parameters:

E - the type of element in the list

K - the type of optional associative keys

All Superinterfaces:

Collection<E>, Iterable<E>, List<E>

All Known Implementing Classes:

AssociativeArrayList

public interface AssociativeList<E,K>
extends List<E>

A List that can have associative keys and can be viewed as a Map. Each item in the list can have an optional associative key and can be queried either by its position or by that associative key.

Method Summary

Modifier and Type	Method and Description
int	add(E element, K key) Adds an element with an associative key.
int	add(int index, E element, K key) Adds an element with an associative key.
Map<K,Integer>	addAll(AssociativeList<? extends E,? extends K> mappedElements) Adds a collection of mapped entries from another AssociativeList.
Map<K,Integer>	addAll(int index, AssociativeList<? extends E,? extends K> mappedElements) Adds a collection of mapped entries from another AssociativeList.
Map<K,Integer>	addAll(int index, Map<? extends K,? extends E> mappedElements) Adds a collection of mapped entries from a map.
Map<K,Integer>	addAll(Map<? extends K,? extends E> mappedElements) Adds a collection of mapped entries from a map.
Map<K,E>	asMap() Returns a view of the associative mappings in this list.
K	clearKey(int index) Clears an associative key from a given list index.
boolean	containsKey(K key) Determines if the specified key is associated with an element in the list.
int	createKey(K key, int index) Adds a key for an existing list element.
int	forgetKey(K key) Removes an associative key but leaves the list and associated element in tact.
E	getByKey(K key) Retrieves a list element via its associative key.
int	getKeyIndex(K key) Finds the list index associated with a given key.
boolean	hasKey(int index) Determines if the specified list index is associated with a key.
ListIterator<Map.Entry<K,E>>	keyedEntryIterator() Returns an iterator over the associative mappings in the list in proper order.
ListIterator<K>	keyIterator() Returns an iterator over the associative keys in the list in proper order.
int	nextKeyedIndex(int start) Returns the next index in the list, that is greater than or equal to the specified index, that has an associated key.
Map.Entry<Integer,E>	removeByKey(K key) Removes an element via its associative key.
AssociativeList<E,K>	subList(int fromIndex, int toIndex) Returns a view of a subset of this list.

Methods inherited from interface java.util.List

add, add, addAll, addAll, clear, contains, containsAll, equals, get, hashCode, indexOf, isEmpty, iterator, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, replaceAll, retainAll, set, size, sort, spliterator, toArray, toArray

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

add

int add(E element,
        K key)

Adds an element with an associative key. If the specified key was previously associated with a different element, the index of that element is returned.

Parameters:

element - the new element to add to the end of the list

key - an associative key for the new element

Returns:

the index previously associated with the specified key or -1 if it was not previously mapped

add

int add(int index,
        E element,
        K key)

Adds an element with an associative key. If the specified key was previously associated with a different element, the index of that element is returned.

Parameters:

index - the index at which the new element is inserted

element - the new element to add to the end of the list

key - an associative key for the new element

Returns:

the index previously associated with the specified key or -1 if it was not previously mapped

Throws:

IndexOutOfBoundsException - if the specified index is negative or is greater than the size of this list

addAll

Map<K,Integer> addAll(Map<? extends K,? extends E> mappedElements)

Adds a collection of mapped entries from a map. The elements are added in whatever iteration order is for the specified map. They are added to the end of the list. Any key that was already associated with an element in the list will instead be associated with its corresponding value in the specified map. The returned map, if not empty, contains any such overwritten keys along with their previously associated list index.

Parameters:

mappedElements - the values and associated keys to add to the list

Returns:

a map of keys to previously associated indices

addAll

Map<K,Integer> addAll(int index,
                      Map<? extends K,? extends E> mappedElements)

Adds a collection of mapped entries from a map. The elements are added in whatever iteration order is for the specified map. Any key that was already associated with an element in the list will instead be associated with its corresponding value in the specified map. The returned map, if not empty, contains any such overwritten keys along with their previously associated list index.

Parameters:

index - the index at which the new elements are inserted

mappedElements - the values and associated keys to add to the list

Returns:

a map of keys to previously associated indices

Throws:

IndexOutOfBoundsException - if the specified index is negative or is greater than the size of this list

addAll

Map<K,Integer> addAll(AssociativeList<? extends E,? extends K> mappedElements)

Adds a collection of mapped entries from another AssociativeList. They are added to the end of the list. Any key that was already associated with an element in the list will instead be associated with its corresponding value in the specified map. The returned map, if not empty, contains any such overwritten keys along with their previously associated list index.

Parameters:

mappedElements - the values and associated keys to add to the list

Returns:

a map of keys to previously associated indices

addAll

Map<K,Integer> addAll(int index,
                      AssociativeList<? extends E,? extends K> mappedElements)

Adds a collection of mapped entries from another AssociativeList. Any key that was already associated with an element in the list will instead be associated with its corresponding value in the specified map. The returned map, if not empty, contains any such overwritten keys along with their previously associated list index.

Parameters:

index - the index at which the new elements are inserted

mappedElements - the values and associated keys to add to the list

Returns:

a map of keys to previously associated indices

Throws:

IndexOutOfBoundsException - if the specified index is negative or is greater than the size of this list

createKey

int createKey(K key,
              int index)

Adds a key for an existing list element. If the key was already associated with an element, that previous list index is returned.

Parameters:

key - the associative key

index - the list index to associate with the key

Returns:

the index previously associated with the specified key or -1 if it was not previously mapped

Throws:

IndexOutOfBoundsException - if the specified index is negative or is greater than the largest valid index in this list

getByKey

E getByKey(K key)

Retrieves a list element via its associative key.

Parameters:

key - the associative key

Returns:

the associated list element or null if no such associative key exists

getKeyIndex

int getKeyIndex(K key)

Finds the list index associated with a given key.

Parameters:

key - the associative key

Returns:

the associated list index or -1 if no such associative key exists

removeByKey

Map.Entry<Integer,E> removeByKey(K key)

Removes an element via its associative key.

Parameters:

key - the associative key

Returns:

both the value and the index at which it was located for the removed element or null if no such associative key exists

forgetKey

int forgetKey(K key)

Removes an associative key but leaves the list and associated element in tact. This just removes the association of the key and the element.

Parameters:

key - the associative key

Returns:

the index that was associated with the specified key or -1 if it was not previously mapped

clearKey

K clearKey(int index)

Clears an associative key from a given list index. The list and associated element is left in tact. This just removes the association of the key and the element.

Parameters:

index - the index

Returns:

the key that was associated with the specified index or null if it was not previously mapped

Throws:

IndexOutOfBoundsException - if the specified index is negative or is greater than the largest valid index in this list

hasKey

boolean hasKey(int index)

Determines if the specified list index is associated with a key.

Parameters:

index - index into the list

Returns:

true if the specified index has an associative key; false otherwise

Throws:

IndexOutOfBoundsException - if the specified index is negative or is greater than the largest valid index in this list

containsKey

boolean containsKey(K key)

Determines if the specified key is associated with an element in the list.

Parameters:

key - the associative key

Returns:

true if the associative key exists; false otherwise

keyIterator

ListIterator<K> keyIterator()

Returns an iterator over the associative keys in the list in proper order. The iterator skips over list indexes that are not mapped.

Returns:

an iterator over the associative keys in the list

keyedEntryIterator

ListIterator<Map.Entry<K,E>> keyedEntryIterator()

Returns an iterator over the associative mappings in the list in proper order. The iterator skips over list indexes that are not mapped.

Returns:

an iterator over the associative mappings in the list

nextKeyedIndex

int nextKeyedIndex(int start)

Returns the next index in the list, that is greater than or equal to the specified index, that has an associated key. The following code construct can be used to iterate through the indexes with associative keys:

 for (int i = list.nextKeyedIndex(0); i >= 0; i = list.nextKeyedIndex(i + 1)) {
   // i is an index associated with a key
 }
 

Parameters:

start - the starting index for searching for an index with a key

Returns:

the next index with a key that is greater than or equal to the specified starting index or -1 if no more keys exist

Throws:

IndexOutOfBoundsException - if the specified index is negative or is greater than the size of the list

asMap

Map<K,E> asMap()

Returns a view of the associative mappings in this list. The returned map is a read-only view. All mutation operations will throw a UnsupportedOperationException.

Returns:

a view of the mappings in this list

subList

AssociativeList<E,K> subList(int fromIndex,
                             int toIndex)

Returns a view of a subset of this list. The returned view is also an associative list.

Specified by:

subList in interface List<E>