package knightstour;

/**
 * This interface specifies required functionality for a class that represents
 * a chess board and is able to solve the so-called open knight's tour problem.
 * <br>
 * Knight's tour problem: The objective is to find a sequence of moves performed
 * by a knight on an n x n chess board from a given initial position such that
 * every square on the board is visited exactly once.
 * Note that the knight is able to perform a move that consists of 2 squares
 * in one direction followed by 1 square to the right or left of the first
 * direction. This interface is for the so-called open knight's tour problem,
 * which means that the tour does not describe a cycle.
 * If the tour happens to end at a position such that the knight can proceed
 * to the initial position (the path describes a cycle), then the tour is
 * called closed. This property is not of interest in this context.
 * <br>
 * An interface can not require a particular type of constructor for an
 * implementing class. However, note that the current environment assumes
 * that there is a constructor with no parameters!
 * @author kemper
 *
 */
public interface Tour {
	/**
	 * This method sets the dimension of the board.
	 * @param n is the dimension, 0 <= n is expected.
	 * If n < 0 the dimension is set to 0.
	 */
	void setDimension(int n);
	/**
	 * This method returns the dimension of the board.
	 * getDimension() == setDimension(n) for the last call of
	 * setDimension(n) if 0 <= n and getDimension() == 0 otherwise.
	 * @return dimension n, 0 <= n
	 */
	int getDimension();
	/**
	 * This method computes an open knight's tour for a given starting
	 * position.
	 * If such a tour does not exists, it returns an empty array.
	 * If such a tour exists, it consists of (n x n) positions on the
	 * board.
	 * Each position is a pair of coordinates (row, col) and the
	 * returned array encodes a sequence of such pairs of coordinates.
	 * The returned array is then of length 2 * (n * n)
	 * and simply enumerates the integer values (row,col) for the
	 * coordinates.
	 * @param startRow specifies the initial row position,
	 * 0 <= startRow < n
	 * @param startCol specifies the initial column position,
	 * 0 <= startCol < n
	 * @return an array of  length 2 * n * n
	 * such that a pair of adjacent entries [2k,2k+1] provides
	 * a position of the knight for values of k, 0 <= k < n,
	 * and the sequence of pairs describes the knight's tour.
	 * The array is empty (length 0) if the computation failed.
	 */
	int[] getTour(int startRow, int startCol);
	/**
	 * This method is a convenience method to output a knight's tour.
	 * It returns the result of getTour()
	 * in a string format ready for printing or to be put on display.
	 * The format mimics the form of a chess board such that position
	 * indices are omitted and
	 * numerical index values for the sequence of steps are arranged
	 * in a square pattern following the chess board.
	 * If there is no tour, the method returns an empty string.
	 * @param startRow specifies the initial row position,
	 * 0 <= startRow < n
	 * @param startCol specifies the initial column position,
	 * 0 <= startCol < n
	 * @return formatted string that describes the tour,
	 * empty if tour does not exists.
	 */
	String printTour(int startRow, int startCol);
}
