## edu.stanford.nlp.util
Class HashIndex<E>

    java.lang.Object
      java.util.AbstractCollection<E>
          edu.stanford.nlp.util.HashIndex<E>

All Implemented Interfaces:
  Index<E>, Serializable, Iterable<E>, Collection<E>, RandomAccess

    public class HashIndex<E>

extends AbstractCollection<E>
implements Index<E>, RandomAccess

An Index is a collection that maps between an Object vocabulary and a contiguous non-negative integer index series beginning (inclusively) at 0. It supports constant-time lookup in both directions (via `get(int)` and `indexOf(E)`. The `indexOf(E)` 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
Author:
  Dan Klein, Eric Yeh (added write to/load from buffer)
See Also:
  `AbstractCollection`, Serialized Form

Constructor Summary
`HashIndex()` Creates a new Index.
`HashIndex(Collection<? extends E> c)` Creates a new Index and adds every member of c to it.
`HashIndex(int capacity)` Creates a new Index.

Method Summary
`boolean` `add(E o)` Adds an object to the Index.
`boolean` `addAll(Collection<? extends E> c)` Adds every member of Collection to the Index.
`void` `clear()` Clears this Index.
`boolean` `contains(Object o)` Checks whether an Object already has an index in the Index
`E` `get(int i)` Gets the object whose index is the integer argument.
`int` `indexOf(E o)` Returns the integer index of the Object in the Index or -1 if the Object is not already in the Index.
`int` `indexOf(E o, boolean add)` Takes an Object and returns the integer index of the Object, perhaps adding it to the index first.
`int[]` `indices(Collection<E> elems)` Returns the index of each elem in a List.
`boolean` `isLocked()` Queries the Index for whether it's locked or not.
`Iterator<E>` `iterator()` Returns an iterator over the elements of the collection.
`static Index<String>` `loadFromFilename(String file)`
`static Index<String>` `loadFromReader(BufferedReader br)` This is the analogue of `loadFromFilename`, and is intended to be included in a routine that unpacks a text-serialized form of an object that incorporates an Index.
`void` `lock()` Locks the Index.
`static void` `main(String[] args)`
`Collection<E>` `objects(int[] indices)` Looks up the objects corresponding to an array of indices, and returns them in a `Collection`.
`List<E>` `objectsList()` Returns a complete `List` of indexed objects, in the order of their indices.
`boolean` `remove(Object o)` Removes an object from the index, if it exists (otherwise nothing happens).
`void` `saveToFilename(String file)` Save the contents of this index into a file.
`void` `saveToWriter(Writer bw)` This saves the contents of this index into string form, as part of a larger text-serialization.
`int` `size()` Returns the number of indexed objects.
`String` `toString()` Returns a readable version of the Index contents
`String` `toString(int n)` Returns a readable version of at least part of the Index contents.
`String` `toStringOneEntryPerLine()`
`String` `toStringOneEntryPerLine(int n)`
`void` `unlock()` Unlocks the Index.
`HashIndex<E>` `unmodifiableView()` Returns an 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 edu.stanford.nlp.util.Index
`toArray`

Methods inherited from interface java.util.Collection
`equals, hashCode`

Constructor Detail

### HashIndex

    public HashIndex()

  Creates a new Index.

### HashIndex

    public HashIndex(int capacity)

  Creates a new Index.

  Parameters:
    `capacity` - Initial capacity of Index.

### HashIndex

    public HashIndex(Collection<? extends E> c)

  Creates a new Index and adds every member of c to it.

  Parameters:
    `c` - A collection of objects

Method Detail

### clear

    public void clear()

  Clears this Index.

  Specified by:
    `clear` in interface `Index<E>`
  Specified by:
    `clear` in interface `Collection<E>`
  Overrides:
    `clear` in class `AbstractCollection<E>`

### indices

    public int[] indices(Collection<E> elems)

  Returns the index of each elem in a List.

  Parameters:
    `elems` - The list of items
  Returns:
    An array of indices

### objects

    public Collection<E> objects(int[] indices)

  Looks up the objects corresponding to an array of indices, and returns them in a `Collection`. This collection is not a copy, but accesses the data structures of the Index.

  Specified by:
    `objects` in interface `Index<E>`
  Parameters:
    `indices` - An array of indices
  Returns:
    a `Collection` of the objects corresponding to the indices argument.

### size

    public int size()

  Returns the number of indexed objects.

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

### get

    public E get(int i)

  Gets the object whose index is the integer argument.

  Specified by:
    `get` in interface `Index<E>`
  Parameters:
    `i` - the integer index to be queried for the corresponding argument
  Returns:
    the object whose index is the integer argument.

### objectsList

    public 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)

  Specified by:
    `objectsList` in interface `Index<E>`
  Returns:
    a complete `List` of indexed objects

### isLocked

    public boolean isLocked()

  Queries the Index for whether it's locked or not.

  Specified by:
    `isLocked` in interface `Index<E>`
  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`).

  Specified by:
    `lock` in interface `Index<E>`

### 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`).

  Specified by:
    `unlock` in interface `Index<E>`

### indexOf

    public int indexOf(E o)

  Returns the integer index of the Object in the Index or -1 if the Object is not already in the Index.

  Specified by:
    `indexOf` in interface `Index<E>`
  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(E o,
                       boolean add)

  Takes an Object and returns the integer index of the Object, perhaps adding it to the index first. Returns -1 if the Object is not in the Index.

  Notes: The method indexOf(x, true) is the direct replacement for the number(x) method in the old Numberer class. This method now uses a Semaphore object to make the index safe for concurrent multithreaded usage. (CDM: Is this better than using a syncronized block?)

  Specified by:
    `indexOf` in interface `Index<E>`
  Parameters:
    `o` - the Object whose index is desired.
    `add` - Whether it is okay to add new items to the index
  Returns:
    The index of the Object argument. Returns -1 if the object is not in the index.

### addAll

    public boolean addAll(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 `Index<E>`
  Specified by:
    `addAll` in interface `Collection<E>`
  Overrides:
    `addAll` in class `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 `Index<E>`
  Specified by:
    `add` in interface `Collection<E>`
  Overrides:
    `add` in class `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(Object o)

  Checks whether an Object already has an index in the Index

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

### saveToFilename

    public void saveToFilename(String file)

  Description copied from interface: `Index`
  Save the contents of this index into a file.

  Specified by:
    `saveToFilename` in interface `Index<E>`
  Parameters:
    `file` - File name.

### loadFromFilename

    public static Index<String> loadFromFilename(String file)

### saveToWriter

    public void saveToWriter(Writer bw)
                      throws IOException

  This saves the contents of this index into string form, as part of a larger text-serialization. This is not intended to act as a standalone routine, instead being called from the text-serialization routine for a component that makes use of an Index, so everything can be stored in one file. This is similar to `saveToFileName`. NOTE: adds an extra newline at the end of the sequence.

  Specified by:
    `saveToWriter` in interface `Index<E>`
  Parameters:
    `bw` - Writer to save to.
  Throws:
    `IOException` - Exception thrown if cannot save.

### loadFromReader

    public static Index<String> loadFromReader(BufferedReader br)
                                        throws Exception

  This is the analogue of `loadFromFilename`, and is intended to be included in a routine that unpacks a text-serialized form of an object that incorporates an Index. NOTE: presumes that the next readLine() will read in the first line of the portion of the text file representing the saved Index. Currently reads until it encounters a blank line, consuming that line and returning the Index. TODO: figure out how best to terminate: currently a blank line is considered to be a terminator.

  Parameters:
    `br` - The Reader to read the index from
  Returns:
    An Index read from a file
  Throws:
    `Exception`

### toString

    public String toString()

  Returns a readable version of the Index contents

  Overrides:
    `toString` in class `AbstractCollection<E>`
  Returns:
    A String showing the full index contents

### toStringOneEntryPerLine

    public String toStringOneEntryPerLine()

### toString

    public String toString(int n)

  Returns a readable version of at least part of the Index contents.

  Parameters:
    `n` - Show the first n items in the Index
  Returns:
    A String rshowing some of the index contents

### toStringOneEntryPerLine

    public String toStringOneEntryPerLine(int n)

### main

    public static void main(String[] args)

### iterator

    public Iterator<E> iterator()

  Returns an iterator over the elements of the collection.

  Specified by:
    `iterator` in interface `Iterable<E>`
  Specified by:
    `iterator` in interface `Collection<E>`
  Specified by:
    `iterator` in class `AbstractCollection<E>`
  Returns:
    An iterator over the objects indexed

### remove

    public boolean remove(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 `Index<E>`
  Specified by:
    `remove` in interface `Collection<E>`
  Overrides:
    `remove` in class `AbstractCollection<E>`
  Parameters:
    `o` - the object to remove
  Returns:
    whether anything was removed

### unmodifiableView

    public HashIndex<E> unmodifiableView()

  Returns an 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 exception). Trying to unlock it will throw an UnsupportedOperationException. If the underlying Index is modified, the change will "write-through" to the view.

  Returns:
    An unmodifiable view of the Index

Stanford NLP Group