/*
 *   This program is free software: you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation, either version 3 of the License, or
 *   (at your option) any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

/*
 *    DenseInstance.java
 *    Copyright (C) 1999-2012 University of Waikato, Hamilton, New Zealand
 *
 */

package weka.core;

import java.io.Serializable;
import java.util.Enumeration;

/**
 * Abstract class providing common functionality for the original instance
 * implementations.
 * 
 * @author Eibe Frank (eibe@cs.waikato.ac.nz)
 * @version $Revision: 9134 $
 */
public abstract class AbstractInstance implements Instance, Serializable,
    RevisionHandler {

  /** for serialization */
  static final long serialVersionUID = 1482635194499365155L;

  /**
   * The dataset the instance has access to. Null if the instance doesn't have
   * access to any dataset. Only if an instance has access to a dataset, it
   * knows about the actual attribute types.
   */
  protected/* @spec_public@ */Instances m_Dataset;

  /** The instance's attribute values. */
  protected/* @spec_public non_null@ */double[] m_AttValues;

  /** The instance's weight. */
  protected double m_Weight;

  /** Default max number of digits after the decimal point for numeric values */
  public static int s_numericAfterDecimalPoint = 6;

  /**
   * Returns the attribute with the given index.
   * 
   * @param index the attribute's index
   * @return the attribute at the given position
   * @throws UnassignedDatasetException if instance doesn't have access to a
   *           dataset
   */
  // @ requires m_Dataset != null;
  @Override
  public/* @pure@ */Attribute attribute(int index) {

    if (m_Dataset == null) {
      throw new UnassignedDatasetException(
          "DenseInstance doesn't have access to a dataset!");
    }
    return m_Dataset.attribute(index);
  }

  /**
   * Returns the attribute with the given index in the sparse representation.
   * 
   * @param indexOfIndex the index of the attribute's index
   * @return the attribute at the given position
   * @throws UnassignedDatasetException if instance doesn't have access to a
   *           dataset
   */
  // @ requires m_Dataset != null;
  @Override
  public/* @pure@ */Attribute attributeSparse(int indexOfIndex) {

    if (m_Dataset == null) {
      throw new UnassignedDatasetException(
          "DenseInstance doesn't have access to a dataset!");
    }
    return m_Dataset.attribute(index(indexOfIndex));
  }

  /**
   * Returns class attribute.
   * 
   * @return the class attribute
   * @throws UnassignedDatasetException if the class is not set or the instance
   *           doesn't have access to a dataset
   */
  // @ requires m_Dataset != null;
  @Override
  public/* @pure@ */Attribute classAttribute() {

    if (m_Dataset == null) {
      throw new UnassignedDatasetException(
          "DenseInstance doesn't have access to a dataset!");
    }
    return m_Dataset.classAttribute();
  }

  /**
   * Returns the class attribute's index.
   * 
   * @return the class index as an integer
   * @throws UnassignedDatasetException if instance doesn't have access to a
   *           dataset
   */
  // @ requires m_Dataset != null;
  // @ ensures \result == m_Dataset.classIndex();
  @Override
  public/* @pure@ */int classIndex() {

    if (m_Dataset == null) {
      throw new UnassignedDatasetException(
          "DenseInstance doesn't have access to a dataset!");
    }
    return m_Dataset.classIndex();
  }

  /**
   * Tests if an instance's class is missing.
   * 
   * @return true if the instance's class is missing
   * @throws UnassignedClassException if the class is not set or the instance
   *           doesn't have access to a dataset
   */
  // @ requires classIndex() >= 0;
  @Override
  public/* @pure@ */boolean classIsMissing() {

    if (classIndex() < 0) {
      throw new UnassignedClassException("Class is not set!");
    }
    return isMissing(classIndex());
  }

  /**
   * Returns an instance's class value in internal format. (ie. as a
   * floating-point number)
   * 
   * @return the corresponding value as a double (If the corresponding attribute
   *         is nominal (or a string) then it returns the value's index as a
   *         double).
   * @throws UnassignedClassException if the class is not set or the instance
   *           doesn't have access to a dataset
   */
  // @ requires classIndex() >= 0;
  @Override
  public/* @pure@ */double classValue() {

    if (classIndex() < 0) {
      throw new UnassignedClassException("Class is not set!");
    }
    return value(classIndex());
  }

  /**
   * Returns the dataset this instance has access to. (ie. obtains information
   * about attribute types from) Null if the instance doesn't have access to a
   * dataset.
   * 
   * @return the dataset the instance has accesss to
   */
  // @ ensures \result == m_Dataset;
  @Override
  public/* @pure@ */Instances dataset() {

    return m_Dataset;
  }

  /**
   * Deletes an attribute at the given position (0 to numAttributes() - 1). Only
   * succeeds if the instance does not have access to any dataset because
   * otherwise inconsistencies could be introduced.
   * 
   * @param position the attribute's position
   * @throws RuntimeException if the instance has access to a dataset
   */
  // @ requires m_Dataset != null;
  @Override
  public void deleteAttributeAt(int position) {

    if (m_Dataset != null) {
      throw new RuntimeException("DenseInstance has access to a dataset!");
    }
    forceDeleteAttributeAt(position);
  }

  /**
   * Returns an enumeration of all the attributes.
   * 
   * @return enumeration of all the attributes
   * @throws UnassignedDatasetException if the instance doesn't have access to a
   *           dataset
   */
  // @ requires m_Dataset != null;
  @Override
  public/* @pure@ */Enumeration enumerateAttributes() {

    if (m_Dataset == null) {
      throw new UnassignedDatasetException(
          "DenseInstance doesn't have access to a dataset!");
    }
    return m_Dataset.enumerateAttributes();
  }

  /**
   * Tests if the headers of two instances are equivalent.
   * 
   * @param inst another instance
   * @return true if the header of the given instance is equivalent to this
   *         instance's header
   * @throws UnassignedDatasetException if instance doesn't have access to any
   *           dataset
   */
  // @ requires m_Dataset != null;
  @Override
  public/* @pure@ */boolean equalHeaders(Instance inst) {

    if (m_Dataset == null) {
      throw new UnassignedDatasetException(
          "DenseInstance doesn't have access to a dataset!");
    }
    return m_Dataset.equalHeaders(inst.dataset());
  }

  /**
   * Checks if the headers of two instances are equivalent. If not, then returns
   * a message why they differ.
   * 
   * @param dataset another instance
   * @return null if the header of the given instance is equivalent to this
   *         instance's header, otherwise a message with details on why they
   *         differ
   */
  @Override
  public String equalHeadersMsg(Instance inst) {
    if (m_Dataset == null)
      throw new UnassignedDatasetException(
          "DenseInstance doesn't have access to a dataset!");

    return m_Dataset.equalHeadersMsg(inst.dataset());
  }

  /**
   * Tests whether an instance has a missing value. Skips the class attribute if
   * set.
   * 
   * @return true if instance has a missing value.
   * @throws UnassignedDatasetException if instance doesn't have access to any
   *           dataset
   */
  // @ requires m_Dataset != null;
  @Override
  public/* @pure@ */boolean hasMissingValue() {

    if (m_Dataset == null) {
      throw new UnassignedDatasetException(
          "DenseInstance doesn't have access to a dataset!");
    }
    for (int i = 0; i < numValues(); i++) {
      if (index(i) != classIndex()) {
        if (isMissingSparse(i)) {
          return true;
        }
      }
    }
    return false;
  }

  /**
   * Inserts an attribute at the given position (0 to numAttributes()). Only
   * succeeds if the instance does not have access to any dataset because
   * otherwise inconsistencies could be introduced.
   * 
   * @param position the attribute's position
   * @throws RuntimeException if the instance has accesss to a dataset
   * @throws IllegalArgumentException if the position is out of range
   */
  // @ requires m_Dataset == null;
  // @ requires 0 <= position && position <= numAttributes();
  @Override
  public void insertAttributeAt(int position) {

    if (m_Dataset != null) {
      throw new RuntimeException("DenseInstance has accesss to a dataset!");
    }
    if ((position < 0) || (position > numAttributes())) {
      throw new IllegalArgumentException("Can't insert attribute: index out "
          + "of range");
    }
    forceInsertAttributeAt(position);
  }

  /**
   * Tests if a specific value is "missing".
   * 
   * @param attIndex the attribute's index
   * @return true if the value is "missing"
   */
  @Override
  public/* @pure@ */boolean isMissing(int attIndex) {

    if (Utils.isMissingValue(value(attIndex))) {
      return true;
    }
    return false;
  }

  /**
   * Tests if a specific value is "missing", given an index in the sparse
   * representation.
   * 
   * @param indexOfIndex the index of the attribute's index
   * @return true if the value is "missing"
   */
  @Override
  public/* @pure@ */boolean isMissingSparse(int indexOfIndex) {

    if (Utils.isMissingValue(valueSparse(indexOfIndex))) {
      return true;
    }
    return false;
  }

  /**
   * Tests if a specific value is "missing". The given attribute has to belong
   * to a dataset.
   * 
   * @param att the attribute
   * @return true if the value is "missing"
   */
  @Override
  public/* @pure@ */boolean isMissing(Attribute att) {

    return isMissing(att.index());
  }

  /**
   * Returns the number of class labels.
   * 
   * @return the number of class labels as an integer if the class attribute is
   *         nominal, 1 otherwise.
   * @throws UnassignedDatasetException if instance doesn't have access to any
   *           dataset
   */
  // @ requires m_Dataset != null;
  @Override
  public/* @pure@ */int numClasses() {

    if (m_Dataset == null) {
      throw new UnassignedDatasetException(
          "DenseInstance doesn't have access to a dataset!");
    }
    return m_Dataset.numClasses();
  }

  /**
   * Sets the class value of an instance to be "missing". A deep copy of the
   * vector of attribute values is performed before the value is set to be
   * missing.
   * 
   * @throws UnassignedClassException if the class is not set
   * @throws UnassignedDatasetException if the instance doesn't have access to a
   *           dataset
   */
  // @ requires classIndex() >= 0;
  @Override
  public void setClassMissing() {

    if (classIndex() < 0) {
      throw new UnassignedClassException("Class is not set!");
    }
    setMissing(classIndex());
  }

  /**
   * Sets the class value of an instance to the given value (internal
   * floating-point format). A deep copy of the vector of attribute values is
   * performed before the value is set.
   * 
   * @param value the new attribute value (If the corresponding attribute is
   *          nominal (or a string) then this is the new value's index as a
   *          double).
   * @throws UnassignedClassException if the class is not set
   * @throws UnaddignedDatasetException if the instance doesn't have access to a
   *           dataset
   */
  // @ requires classIndex() >= 0;
  @Override
  public void setClassValue(double value) {

    if (classIndex() < 0) {
      throw new UnassignedClassException("Class is not set!");
    }
    setValue(classIndex(), value);
  }

  /**
   * Sets the class value of an instance to the given value. A deep copy of the
   * vector of attribute values is performed before the value is set.
   * 
   * @param value the new class value (If the class is a string attribute and
   *          the value can't be found, the value is added to the attribute).
   * @throws UnassignedClassException if the class is not set
   * @throws UnassignedDatasetException if the dataset is not set
   * @throws IllegalArgumentException if the attribute is not nominal or a
   *           string, or the value couldn't be found for a nominal attribute
   */
  // @ requires classIndex() >= 0;
  @Override
  public final void setClassValue(String value) {

    if (classIndex() < 0) {
      throw new UnassignedClassException("Class is not set!");
    }
    setValue(classIndex(), value);
  }

  /**
   * Sets the reference to the dataset. Does not check if the instance is
   * compatible with the dataset. Note: the dataset does not know about this
   * instance. If the structure of the dataset's header gets changed, this
   * instance will not be adjusted automatically.
   * 
   * @param instances the reference to the dataset
   */
  @Override
  public final void setDataset(Instances instances) {

    m_Dataset = instances;
  }

  /**
   * Sets a specific value to be "missing". Performs a deep copy of the vector
   * of attribute values before the value is set to be missing.
   * 
   * @param attIndex the attribute's index
   */
  @Override
  public final void setMissing(int attIndex) {

    setValue(attIndex, Utils.missingValue());
  }

  /**
   * Sets a specific value to be "missing". Performs a deep copy of the vector
   * of attribute values before the value is set to be missing. The given
   * attribute has to belong to a dataset.
   * 
   * @param att the attribute
   */
  @Override
  public final void setMissing(Attribute att) {

    setMissing(att.index());
  }

  /**
   * Sets a value of a nominal or string attribute to the given value. Performs
   * a deep copy of the vector of attribute values before the value is set.
   * 
   * @param attIndex the attribute's index
   * @param value the new attribute value (If the attribute is a string
   *          attribute and the value can't be found, the value is added to the
   *          attribute).
   * @throws UnassignedDatasetException if the dataset is not set
   * @throws IllegalArgumentException if the selected attribute is not nominal
   *           or a string, or the supplied value couldn't be found for a
   *           nominal attribute
   */
  // @ requires m_Dataset != null;
  @Override
  public final void setValue(int attIndex, String value) {

    int valIndex;

    if (m_Dataset == null) {
      throw new UnassignedDatasetException(
          "DenseInstance doesn't have access to a dataset!");
    }
    if (!attribute(attIndex).isNominal() && !attribute(attIndex).isString()) {
      throw new IllegalArgumentException(
          "Attribute neither nominal nor string!");
    }
    valIndex = attribute(attIndex).indexOfValue(value);
    if (valIndex == -1) {
      if (attribute(attIndex).isNominal()) {
        throw new IllegalArgumentException(
            "Value not defined for given nominal attribute!");
      } else {
        attribute(attIndex).forceAddValue(value);
        valIndex = attribute(attIndex).indexOfValue(value);
      }
    }
    setValue(attIndex, valIndex);
  }

  /**
   * Sets a specific value in the instance to the given value (internal
   * floating-point format). Performs a deep copy of the vector of attribute
   * values before the value is set, so if you are planning on calling setValue
   * many times it may be faster to create a new instance using toDoubleArray.
   * The given attribute has to belong to a dataset.
   * 
   * @param att the attribute
   * @param value the new attribute value (If the corresponding attribute is
   *          nominal (or a string) then this is the new value's index as a
   *          double).
   */
  @Override
  public final void setValue(Attribute att, double value) {

    setValue(att.index(), value);
  }

  /**
   * Sets a value of an nominal or string attribute to the given value. Performs
   * a deep copy of the vector of attribute values before the value is set, so
   * if you are planning on calling setValue many times it may be faster to
   * create a new instance using toDoubleArray. The given attribute has to
   * belong to a dataset.
   * 
   * @param att the attribute
   * @param value the new attribute value (If the attribute is a string
   *          attribute and the value can't be found, the value is added to the
   *          attribute).
   * @throws IllegalArgumentException if the the attribute is not nominal or a
   *           string, or the value couldn't be found for a nominal attribute
   */
  @Override
  public final void setValue(Attribute att, String value) {

    if (!att.isNominal() && !att.isString()) {
      throw new IllegalArgumentException(
          "Attribute neither nominal nor string!");
    }
    int valIndex = att.indexOfValue(value);
    if (valIndex == -1) {
      if (att.isNominal()) {
        throw new IllegalArgumentException(
            "Value not defined for given nominal attribute!");
      } else {
        att.forceAddValue(value);
        valIndex = att.indexOfValue(value);
      }
    }
    setValue(att.index(), valIndex);
  }

  /**
   * Sets the weight of an instance.
   * 
   * @param weight the weight
   */
  @Override
  public final void setWeight(double weight) {

    m_Weight = weight;
  }

  /**
   * Returns the relational value of a relational attribute.
   * 
   * @param attIndex the attribute's index
   * @return the corresponding relation as an Instances object
   * @throws IllegalArgumentException if the attribute is not a relation-valued
   *           attribute
   * @throws UnassignedDatasetException if the instance doesn't belong to a
   *           dataset.
   */
  // @ requires m_Dataset != null;
  @Override
  public final/* @pure@ */Instances relationalValue(int attIndex) {

    if (m_Dataset == null) {
      throw new UnassignedDatasetException(
          "DenseInstance doesn't have access to a dataset!");
    }
    return relationalValue(m_Dataset.attribute(attIndex));
  }

  /**
   * Returns the relational value of a relational attribute.
   * 
   * @param att the attribute
   * @return the corresponding relation as an Instances object, null if missing
   * @throws IllegalArgumentException if the attribute is not a relation-valued
   *           attribute
   * @throws UnassignedDatasetException if the instance doesn't belong to a
   *           dataset.
   */
  @Override
  public final/* @pure@ */Instances relationalValue(Attribute att) {

    int attIndex = att.index();
    if (att.isRelationValued()) {
      if (isMissing(attIndex)) {
        return null;
      }
      return att.relation((int) value(attIndex));
    } else {
      throw new IllegalArgumentException("Attribute isn't relation-valued!");
    }
  }

  /**
   * Returns the value of a nominal, string, date, or relational attribute for
   * the instance as a string.
   * 
   * @param attIndex the attribute's index
   * @return the value as a string
   * @throws IllegalArgumentException if the attribute is not a nominal, string,
   *           date, or relation-valued attribute.
   * @throws UnassignedDatasetException if the instance doesn't belong to a
   *           dataset.
   */
  // @ requires m_Dataset != null;
  @Override
  public final/* @pure@ */String stringValue(int attIndex) {

    if (m_Dataset == null) {
      throw new UnassignedDatasetException(
          "DenseInstance doesn't have access to a dataset!");
    }
    return stringValue(m_Dataset.attribute(attIndex));
  }

  /**
   * Returns the value of a nominal, string, date, or relational attribute for
   * the instance as a string.
   * 
   * @param att the attribute
   * @return the value as a string
   * @throws IllegalArgumentException if the attribute is not a nominal, string,
   *           date, or relation-valued attribute.
   * @throws UnassignedDatasetException if the instance doesn't belong to a
   *           dataset.
   */
  @Override
  public final/* @pure@ */String stringValue(Attribute att) {

    int attIndex = att.index();
    if (isMissing(attIndex)) {
      return "?";
    }
    switch (att.type()) {
    case Attribute.NOMINAL:
    case Attribute.STRING:
      return att.value((int) value(attIndex));
    case Attribute.DATE:
      return att.formatDate(value(attIndex));
    case Attribute.RELATIONAL:
      return att.relation((int) value(attIndex)).stringWithoutHeader();
    default:
      throw new IllegalArgumentException(
          "Attribute isn't nominal, string or date!");
    }
  }

  /**
   * Returns the description of one instance with any numeric values printed at
   * the supplied maximum number of decimal places. If the instance doesn't have
   * access to a dataset, it returns the internal floating-point values. Quotes
   * string values that contain whitespace characters.
   * 
   * @param afterDecimalPoint the maximum number of digits permitted after the
   *          decimal point for a numeric value
   * 
   * @return the instance's description as a string
   */
  @Override
  public final String toStringMaxDecimalDigits(int afterDecimalPoint) {
    StringBuffer text = new StringBuffer(toStringNoWeight(afterDecimalPoint));

    if (m_Weight != 1.0) {
      text.append(",{" + Utils.doubleToString(m_Weight, afterDecimalPoint)
          + "}");
    }

    return text.toString();
  }

  /**
   * Returns the description of one instance. If the instance doesn't have
   * access to a dataset, it returns the internal floating-point values. Quotes
   * string values that contain whitespace characters.
   * 
   * @return the instance's description as a string
   */
  @Override
  public String toString() {

    return toStringMaxDecimalDigits(s_numericAfterDecimalPoint);
  }

  /**
   * Returns the description of one value of the instance as a string. If the
   * instance doesn't have access to a dataset, it returns the internal
   * floating-point value. Quotes string values that contain whitespace
   * characters, or if they are a question mark.
   * 
   * @param attIndex the attribute's index
   * @return the value's description as a string
   */
  @Override
  public final String toString(int attIndex) {
    return toString(attIndex, s_numericAfterDecimalPoint);
  }

  /**
   * Returns the description of one value of the instance as a string. If the
   * instance doesn't have access to a dataset, it returns the internal
   * floating-point value. Quotes string values that contain whitespace
   * characters, or if they are a question mark.
   * 
   * @param attIndex the attribute's index
   * @param afterDecimalPoint the maximum number of digits permitted after the
   *          decimal point for numeric values
   * @return the value's description as a string
   */
  @Override
  public final/* @pure@ */String toString(int attIndex, int afterDecimalPoint) {

    StringBuffer text = new StringBuffer();

    if (isMissing(attIndex)) {
      text.append("?");
    } else {
      if (m_Dataset == null) {
        text.append(Utils.doubleToString(value(attIndex), afterDecimalPoint));
      } else {
        switch (m_Dataset.attribute(attIndex).type()) {
        case Attribute.NOMINAL:
        case Attribute.STRING:
        case Attribute.DATE:
        case Attribute.RELATIONAL:
          text.append(Utils.quote(stringValue(attIndex)));
          break;
        case Attribute.NUMERIC:
          text.append(Utils.doubleToString(value(attIndex), afterDecimalPoint));
          break;
        default:
          throw new IllegalStateException("Unknown attribute type");
        }
      }
    }
    return text.toString();
  }

  /**
   * Returns the description of one value of the instance as a string. If the
   * instance doesn't have access to a dataset it returns the internal
   * floating-point value. Quotes string values that contain whitespace
   * characters, or if they are a question mark. The given attribute has to
   * belong to a dataset.
   * 
   * @param att the attribute
   * @return the value's description as a string
   */
  @Override
  public final String toString(Attribute att) {

    return toString(att.index());
  }

  /**
   * Returns the description of one value of the instance as a string. If the
   * instance doesn't have access to a dataset it returns the internal
   * floating-point value. Quotes string values that contain whitespace
   * characters, or if they are a question mark. The given attribute has to
   * belong to a dataset.
   * 
   * @param att the attribute
   * @param afterDecimalPoint the maximum number of decimal places to print
   * @return the value's description as a string
   */
  @Override
  public final String toString(Attribute att, int afterDecimalPoint) {

    return toString(att.index(), afterDecimalPoint);
  }

  /**
   * Returns an instance's attribute value in internal format. The given
   * attribute has to belong to a dataset.
   * 
   * @param att the attribute
   * @return the specified value as a double (If the corresponding attribute is
   *         nominal (or a string) then it returns the value's index as a
   *         double).
   */
  @Override
  public/* @pure@ */double value(Attribute att) {

    return value(att.index());
  }

  /**
   * Returns an instance's attribute value in internal format, given an index in
   * the sparse representation.
   * 
   * @param indexOfIndex the index of the attribute's index
   * @return the specified value as a double (If the corresponding attribute is
   *         nominal (or a string) then it returns the value's index as a
   *         double).
   */
  @Override
  public/* @pure@ */double valueSparse(int indexOfIndex) {

    return m_AttValues[indexOfIndex];
  }

  /**
   * Returns the instance's weight.
   * 
   * @return the instance's weight as a double
   */
  @Override
  public final/* @pure@ */double weight() {

    return m_Weight;
  }

  /**
   * Returns the revision string.
   * 
   * @return the revision
   */
  @Override
  public String getRevision() {
    return RevisionUtils.extract("$Revision: 9134 $");
  }

  /**
   * Deletes an attribute at the given position (0 to numAttributes() - 1).
   * 
   * @param position the attribute's position
   */
  protected abstract void forceDeleteAttributeAt(int position);

  /**
   * Inserts an attribute at the given position (0 to numAttributes()) and sets
   * its value to be missing.
   * 
   * @param position the attribute's position
   */
  protected abstract void forceInsertAttributeAt(int position);
}
