edu.stanford.nlp.util
Class Index<E>

java.lang.Object
  extended by java.util.AbstractCollection<E>
      extended by edu.stanford.nlp.util.Index<E>
All Implemented Interfaces:
java.io.Serializable, java.lang.Iterable<E>, java.util.Collection<E>, java.util.RandomAccess

public class Index<E>
extends java.util.AbstractCollection<E>
implements java.io.Serializable, java.util.RandomAccess

An Index is a collection that maps between an Object vocabulary and a contiguous non-negative integer index beginning (inclusively) at 0. It supports constant-time lookup in both directions (via get(int) and indexOf(Object). The indexOf(Object) method compares objects by equals, as other Collections.

The typical usage would be:

Index index = new Index(collection);

followed by

int i = index.indexOf(object);

or

Object o = index.get(i);

The source contains a concrete example of use as the main method.

An Index can be locked or unlocked: a locked index cannot have new items added to it.

Since:
1.0
See Also:
AbstractCollection, Serialized Form

Field Summary
protected  java.util.Map<java.lang.Object,java.lang.Integer> indexes
           
protected  boolean locked
           
protected  java.util.List<E> objects
           
 
Constructor Summary
Index()
          Creates a new Index.
Index(java.util.Collection<? extends E> c)
          Creates a new Index and adds every member of c to it.
 
Method Summary
 boolean add(E o)
          Adds an object to the Index.
 boolean addAll(java.util.Collection<? extends E> c)
          Adds every member of Collection to the Index.
 void clear()
          Clears this Index.
 boolean contains(java.lang.Object o)
          Checks whether an Object already has an index in the Index
static Index deserializeReadable(java.lang.String file)
           
 java.lang.String firstNToString(int n)
           
 E get(int i)
          Gets the object whose index is the integer argument.
 int indexOf(java.lang.Object o)
          Takes an Object and returns the integer index of the Object.
 int indexOf(java.lang.Object o, boolean add)
          Takes an Object and returns the integer index of the Object.
 int[] indices(java.util.List<E> elems)
          Returns the index of each elem in an array.
 boolean isLocked()
          Queries the Index for whether it's locked or not.
 java.util.Iterator<E> iterator()
          Returns an iterator over the elements of the collection.
 void lock()
          Locks the Index.
static void main(java.lang.String[] args)
           
 java.util.Collection<E> objects(int[] indices)
          Looks up the objects corresponding to an array of indices, and returns them in a Collection.
 java.util.List<E> objectsList()
          Returns a complete List of indexed objects, in the order of their indices.
 boolean remove(java.lang.Object o)
          Removes an object from the index, if it exists (otherwise nothing happens).
 void serializeReadable(java.lang.String file)
           
 int size()
          Checks the number of indexed objects.
 java.lang.String toString()
           
 void unlock()
          Unlocks the Index.
 Index<E> unmodifiableView()
          Returns and unmodifiable view of the Index.
 
Methods inherited from class java.util.AbstractCollection
containsAll, isEmpty, removeAll, retainAll, toArray, toArray
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Collection
equals, hashCode
 

Field Detail

objects

protected java.util.List<E> objects

indexes

protected java.util.Map<java.lang.Object,java.lang.Integer> indexes

locked

protected boolean locked
Constructor Detail

Index

public Index()
Creates a new Index.


Index

public Index(java.util.Collection<? extends E> c)
Creates a new Index and adds every member of c to it.

Method Detail

clear

public void clear()
Clears this Index.

Specified by:
clear in interface java.util.Collection<E>
Overrides:
clear in class java.util.AbstractCollection<E>

indices

public int[] indices(java.util.List<E> elems)
Returns the index of each elem in an array.


objects

public java.util.Collection<E> objects(int[] indices)
Looks up the objects corresponding to an array of indices, and returns them in a Collection.

Parameters:
indices -
Returns:
a Collection of the objects corresponding to the indices argument.

size

public int size()
Checks the number of indexed objects.

Specified by:
size in interface java.util.Collection<E>
Specified by:
size in class java.util.AbstractCollection<E>
Returns:
the number of indexed objects.

get

public E get(int i)
Gets the object whose index is the integer argument.

Parameters:
i - the integer index to be queried for the corresponding argument
Returns:
the object whose index is the integer argument.

objectsList

public java.util.List<E> objectsList()
Returns a complete List of indexed objects, in the order of their indices. DANGER! The current implementation returns the actual index list, not a defensive copy. Messing with this List can seriously screw up the state of the Index. (perhaps this method needs to be eliminated? I don't think it's ever used in ways that we couldn't use the Index itself for directly. --Roger, 12/29/04)

Returns:
a complete List of indexed objects

isLocked

public boolean isLocked()
Queries the Index for whether it's locked or not.

Returns:
whether or not the Index is locked

lock

public void lock()
Locks the Index. A locked index cannot have new elements added to it (calls to add(E) will leave the Index unchanged and return false).


unlock

public void unlock()
Unlocks the Index. A locked index cannot have new elements added to it (calls to add(E) will leave the Index unchanged and return false).


indexOf

public int indexOf(java.lang.Object o)
Takes an Object and returns the integer index of the Object. Returns -1 if the Object is not in the Index.

Parameters:
o - the Object whose index is desired.
Returns:
the index of the Object argument. Returns -1 if the object is not in the index.

indexOf

public int indexOf(java.lang.Object o,
                   boolean add)
Takes an Object and returns the integer index of the Object. Returns -1 if the Object is not in the Index.

Parameters:
o - the Object whose index is desired.
Returns:
the index of the Object argument. Returns -1 if the object is not in the index.

addAll

public boolean addAll(java.util.Collection<? extends E> c)
Adds every member of Collection to the Index. Does nothing for members already in the Index.

Specified by:
addAll in interface java.util.Collection<E>
Overrides:
addAll in class java.util.AbstractCollection<E>
Returns:
true if some item was added to the index and false if no item was already in the index or if the index is locked

add

public boolean add(E o)
Adds an object to the Index. If it was already in the Index, then nothing is done. If it is not in the Index, then it is added iff the Index hasn't been locked.

Specified by:
add in interface java.util.Collection<E>
Overrides:
add in class java.util.AbstractCollection<E>
Returns:
true if the item was added to the index and false if the item was already in the index or if the index is locked

contains

public boolean contains(java.lang.Object o)
Checks whether an Object already has an index in the Index

Specified by:
contains in interface java.util.Collection<E>
Overrides:
contains in class java.util.AbstractCollection<E>
Parameters:
o - the object to be queried.
Returns:
true iff there is an index for the queried object.

serializeReadable

public void serializeReadable(java.lang.String file)

deserializeReadable

public static Index deserializeReadable(java.lang.String file)

toString

public java.lang.String toString()
Overrides:
toString in class java.util.AbstractCollection<E>

firstNToString

public java.lang.String firstNToString(int n)

main

public static void main(java.lang.String[] args)

iterator

public java.util.Iterator<E> iterator()
Returns an iterator over the elements of the collection.

Specified by:
iterator in interface java.lang.Iterable<E>
Specified by:
iterator in interface java.util.Collection<E>
Specified by:
iterator in class java.util.AbstractCollection<E>
Returns:

remove

public boolean remove(java.lang.Object o)
Removes an object from the index, if it exists (otherwise nothing happens). Note, the indices of other elements will not be changed, so indices will no longer necessarily be contiguous

Specified by:
remove in interface java.util.Collection<E>
Overrides:
remove in class java.util.AbstractCollection<E>
Parameters:
o - the object to remove
Returns:
whether anything was removed

unmodifiableView

public Index<E> unmodifiableView()
Returns and unmodifiable view of the Index. It is just a locked index that cannot be unlocked, so if you try to add something, nothing will happen (it won't throw an excpetion). Trying to unlock it will throw an UnsupportedOperationException. If the underlying Index is modified, the change will "write-through" to the view.