edu.stanford.nlp.util.Index Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of stanford-corenlp Show documentation

Stanford CoreNLP provides a set of natural language analysis tools which can take raw English language text input and give the base forms of words, their parts of speech, whether they are names of companies, people, etc., normalize dates, times, and numeric quantities, mark up the structure of sentences in terms of phrases and word dependencies, and indicate which noun phrases refer to the same entities. It provides the foundational building blocks for higher level text understanding applications.

There is a newer version: 4.5.7

Show newest version

package edu.stanford.nlp.util;

import java.io.Serializable;
import java.io.Writer;
import java.io.IOException;
import java.util.Collection;
import java.util.List;

/**
 * A collection that maps between a vocabulary of type E and a
 * continuous non-negative integer index series beginning (inclusively) at 0.
 *
 * Often one uses a List to associate a unique index with each Object
 * (e.g. controlled vocabulary, feature map, etc.). Index offers constant-time
 * performance for both index -> Object ({@link #get(int)}) and 
 * Object -> index ({@link #indexOf(Object)}) as well as for {@link #contains(Object)}.
 * Otherwise it behaves like a normal list. Index also
 * supports {@link #lock()} and {@link #unlock()} to ensure that it's
 * only modified when desired.
 *
 * @author Daniel Cer
 *
 * @param  The type of objects in the Index
 */
public interface Index extends Iterable, Serializable {

  /**
   * Returns the number of indexed objects.
   * @return the number of indexed objects.
   */
  public abstract int size();

  /**
   * Gets the object whose index is the integer argument.
   * @param i the integer index to be queried for the corresponding argument
   * @return the object whose index is the integer argument.
   */
  public abstract E get(int i);

  /**
   * Returns the integer index of the Object in the Index or -1 if the Object
   * is not already in the Index. This operation never changes the Index.
   *
   * @param o The Object whose index is desired.
   * @return The index of the Object argument. Returns -1 if the object is not in the index.
   */
  public abstract int indexOf(E o);

  /**
   * Takes an Object and returns the integer index of the Object.
   * If the object was already in the index, it returns its existing
   * index, otherwise it adds it to the index first.
   * Except if the index is locked, and then it returns -1 if the
   * object is not already in the index.
   *
   * @param o the Object whose index is desired.
   * @return the index of the Object argument. Normally a non-negative integer.
   *     Returns -1 if the object is not in the index and the Index is locked.
   */
  public abstract int addToIndex(E o);

  /**
   * 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.
   * (Note: indexOf(x, true) is the direct replacement for the number(x)
   * method in the old Numberer class.)
   *
   * @param o the Object whose index is desired.
   * @param add Whether it is okay to add new items to the index
   * @return the index of the Object argument.  Returns -1 if the object is not in the index
   *     or if the Index is locked.
   * @deprecated You should use either the addToIndex(E) or indexOf(E) methods instead
   */
  @Deprecated
  public abstract int indexOf(E o, boolean add);


  // mg2009. Methods below were temporarily added when IndexInterface was renamed
  // to Index. These methods are currently (2009-03-09) needed in order to have core classes
  // of JavaNLP (Dataset, LinearClassifier, etc.) use Index instead of HashIndex.
  // Possible JavaNLP task: delete some of these methods.

  /**
   * Returns a complete {@link List} of indexed objects, in the order of their indices.
   *
   * @return a complete {@link List} of indexed objects
   */
  public List objectsList();

  /**
   * Looks up the objects corresponding to an array of indices, and returns them in a {@link Collection}.
   *
   * @param indices An array of indices
   * @return a {@link Collection} of the objects corresponding to the indices argument.
   */
  public Collection objects(int[] indices);

  /**
   * Queries the Index for whether it's locked or not.
   * @return whether or not the Index is locked
   */
  public boolean isLocked();

  /**
   * Locks the Index.  A locked index cannot have new elements added to it (calls to {@link #add} will
   * leave the Index unchanged and return false).
   */
  public void lock();

  /**
   * Unlocks the Index.  A locked index cannot have new elements added to it (calls to {@link #add} will
   * leave the Index unchanged and return false).
   * */
  public void unlock();

  /**
   * Save the contents of this index into string form, as part of a larger
   * text-serialization.
   *
   * @param out Writer to save to.
   * @throws IOException Exception thrown if cannot save.
   */
  public void saveToWriter(Writer out) throws IOException;

  /**
   * Save the contents of this index into a file.
   *
   * @param s File name.
   */
  public void saveToFilename(String s);


  // Subset of the Collection interface.  These come from old uses of HashIndex. Avoid using these.

  public boolean contains(Object o);   // cdm: keep this, it seems reasonable

  public boolean add(E e);  // cdm: Many, many uses; could be replaced with indexOf, but why bother?

  public boolean addAll(Collection c);  // okay to have.

  public void clear();  // cdm: barely used.

}