/*
 * Copyright 2010 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.gwt.dev.util.editdistance;

/**
 * An engine definition for computing string edit distances, and
 * implementation generators.
 *
 * Generally, edit distance is the minimum number of edit operations required
 * to transform one string into another.  Being a minimum transform, it
 * forms a metric space (one that is non-negative, symmetric, and obeys
 * triangle inequality).
 *
 * The most common form is Levenshtein distance, where the set of operations
 * consists of:
 *   deleting one character;
 *   inserting one character; or,
 *   substituting one character for another,
 * each having a "cost" of 1.
 *
 * Another common form is Damerau-Levenshtein distance, which adds
 *   transpose two adjacent characters
 * to the set of operations.  Note that many implementations of
 * Damerau distance do not account for insertion after transposition;
 * this "restricted" Damerau distance does not obey triangle inequality,
 * but is substantially easier to compute than the unrestricted metric.
 *
 * Another variation is to apply differential costs for the various
 * operations.  For example, substitutions could be weighted by
 * character type (e.g., vowel<=>vowel being a cheaper edit than
 * vowel<=>consonant).
 *
 * This class defines an engine for computing edit distance from
 * a fixed ("pattern") string to other ("target") strings.  The pattern
 * is fixed at instantiation time; this allows an implementation to
 * perform precomputations to make individual target computations faster.
 *
 * To allow further performance optimization, the GeneralEditDistance
 * contract does not require thread-safety.  A <tt>duplicate</tt> method is
 * defined to allow additional equivalent instances to be created
 * for separate threads; it is essentially a type-knowledgeable <tt>clone</tt>.
 */
public interface GeneralEditDistance {
  /**
   * Creates a duplicate (clone) of this distance engine, typically
   * in order to use it in another thread (as the GeneralEditDistance
   * contract does not specify thread safety).
   *
   * This method differs from Object.clone() in two ways:
   * it is typed (to GeneralEditDistance); and, it must not throw
   * an exception.
   *
   * @return     a clone of this instance.
   */
  GeneralEditDistance duplicate();

  /**
   * Computes edit distance from the pattern string (used to
   * construct this GeneralEditDistance instance) to a given target
   * string, bounded by a limit of interest.
   *
   * The specified limit must be non-negative.  If the actual distance
   * exceeds the limit, this method may return *any* value above the limit;
   * it need not be the actual distance.  The behavior of
   * illegal limit values is undefined; an implementation may
   * return an incorrect result or raise a runtime exception.
   *
   * @param target string for which distance is to be compared
   *        against a predefined pattern
   * @param limit maximum distance for which exact result is
   *        required (and beyond which any over-limit result
   *        can be returned)
   * @return edit distance from the predefined pattern to the
   *        target (or any value above limit, if the actual distance
   *        exceeds the prescribed limit)
   */
  int getDistance(CharSequence target, int limit);
}