Internet Chess ToolKit
v0.2.0

ictk.boardgame
Class History

java.lang.Object
  extended byictk.boardgame.History

public class History
extends java.lang.Object

the History class is a data structure resembling a tree. As moves are added to the History they are executed. The next move added is appended to the previous move and so on. By added all the moves for a particular game you end up with a linked list refered to as the Main-Line. This is the true history of how the game was played. You are able to go forward and backward through this list. Going forward with next() executes the next move that was on the main-line. prev() unexecutes the move on the board. At this point the board status is exactly the way it was before the move was played.

History also has the ability to hold variations. This is, of course, where the Tree idea comes in. At any position there might be another another move that could have been played (which isn't the main-line move) that holds some interest. You can add this move to the History by backing up to the previous move and using add() again. This will add a variation and create a branch at the previous move where you could then choose to proceed in either of 2 variations with next(n).

For example:

  History history = game.getHistory();
  history.add(moveA);
  history.add(moveB);
  history.prev();  //returning the when moveA was just played
  history.add(moveC);
  history.add(moveC2);
  

in this case the the moves look like this:
     A-->B
      \->C->C2
  
After added the rest of Continuation C you could return to A by using the move rewindToLastFork();

Any number of variations is allowable. You can even add variations to the very first move.

  history.rewind();  //goes back to the beginning
  history.add(MoveA);
  history.rewind();
  history.add(MoveB);
  
In this game both MoveA and MoveB are ways to start the game.

You can play moves directly on the Board objects but they will not be added to the history list and will FUBAR your board's internal state if you start using History after that.

Moves are played and verified when they are added to the History.


Field Summary
static long DEBUG
           
 
Constructor Summary
History(Game game)
           
History(Game game, int initMoveNum)
           
 
Method Summary
 void add(Move m)
          adds a move to the continuation list.
 void add(Move _move, boolean asMainLine)
          adds a move to the game history, adding a continuation onto wherever the current move pointer is.
 void addVariation(Move m)
          This is the same as add(Move, false)
 boolean deepEquals(History hist, boolean checkAnno)
          this compares all moves on the main-line, and all variations.
 boolean equals(History hist)
          this compares the main-line only.
 int fastforward(int n)
          moves forward on the mainline of the current variation N moves.
 ContinuationList getContinuationList()
          returns the continuationList for the currMove.
 Move getCurrentMove()
          returns the last executed move.
 int getCurrentMoveNumber()
          gets the move number of the last move executed on the board.
 Move getFinalMove(boolean trueMainLine)
          returns the final move played on the main line or the current line.
 Move getFirst()
          gets the first move on the main line of the history list
 ContinuationList getFirstAll()
          this returns the ContinuationList of all the moves that could begin the game.
 int getInitialMoveNumber()
           
 Move getNext()
          returns the next move on the currMove's main line.
 Move getNext(int i)
          returns the next move (variation 'i').
 Move goTo(Move m)
          goes to this move in the history list unexecuting or executing moves as is necessary to reach a game state where m was the last move executed on the board.
 void goToEnd()
          opposite of rewind() this goes to the end of the current branch performing all moves on the branch's main line as it goes.
 int hashCode()
          this returns a static number.
 boolean hasNext()
          this applies to the main line.
 boolean isEmpty()
          is the history list completely empty?
 Move next()
          executes the next move after currMove, or the first move of the list.
 Move next(int i)
          executes the next variation
 Move next(Move m)
          executes m if and only if the move is already in the ContinuationList that follows the current move.
 Move prev()
          unexecutes the last move and backs the currMove up one
 Move removeLastMove()
          unexecutes the last move executed, disposes of all its data then returns the move, which should only contain the cooridinates of the move.
 void rewind()
          undoes any moves already done until we are at the begining
 Move rewindToLastFork()
          rewinds the history until the current move is a move with variations.
 void setInitialMoveNumber(int i)
           
 int size()
          returns the number of moves in the main line
 java.lang.String toString()
           
 Move truncate()
          calls truncate(-1)
 Move truncate(int i)
          deletes all branches from currMove (making currMove a terminal node) for the "i" variation.
 
Methods inherited from class java.lang.Object
equals, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

DEBUG

public static final long DEBUG
Constructor Detail

History

public History(Game game)

History

public History(Game game,
               int initMoveNum)
Parameters:
initMoveNum - the number of the first move. (default: 1)
Method Detail

getInitialMoveNumber

public int getInitialMoveNumber()

setInitialMoveNumber

public void setInitialMoveNumber(int i)

getCurrentMoveNumber

public int getCurrentMoveNumber()
gets the move number of the last move executed on the board.

Returns:
0 if no moves executed on the board.

add

public void add(Move _move,
                boolean asMainLine)
         throws IllegalMoveException,
                java.lang.IndexOutOfBoundsException,
                OutOfTurnException,
                AmbiguousMoveException
adds a move to the game history, adding a continuation onto wherever the current move pointer is. If the parameter asMainLine is true then the move added becomes the main line; all other moves are shifted down one in the variation list. That is, if there existed a mainLine it is now the first variation. The previous first variation is now the second and so on.

If asMainLine is false then the move is appended to the variation list. If there are no moves that follow the current move (no main line, no variations) the mainLine will be null and the move added will be the first variation.

When the move is added History.next() is called on the move and the move is played.

Throws:
IllegalMoveException
java.lang.IndexOutOfBoundsException
OutOfTurnException
AmbiguousMoveException

add

public void add(Move m)
         throws IllegalMoveException,
                java.lang.IndexOutOfBoundsException,
                OutOfTurnException,
                AmbiguousMoveException
adds a move to the continuation list. If there are no continuations then this move becomes the mainline. If there are continuations then this move becomes a variation and is added to the end of the list. If the mainline is null then this will be added as a variation.

Throws:
IllegalMoveException
java.lang.IndexOutOfBoundsException
OutOfTurnException
AmbiguousMoveException

addVariation

public void addVariation(Move m)
                  throws IllegalMoveException,
                         java.lang.IndexOutOfBoundsException,
                         OutOfTurnException,
                         AmbiguousMoveException
This is the same as add(Move, false)

Throws:
IllegalMoveException
java.lang.IndexOutOfBoundsException
OutOfTurnException
AmbiguousMoveException

getFirst

public Move getFirst()
gets the first move on the main line of the history list

Returns:
null if there is no first move

getFirstAll

public ContinuationList getFirstAll()
this returns the ContinuationList of all the moves that could begin the game. All variations are returned as well as the main line. The main line will always be at the Zero index.


next

public Move next()
executes the next move after currMove, or the first move of the list.

Returns:
the move just executed.

next

public Move next(int i)
executes the next variation


next

public Move next(Move m)
executes m if and only if the move is already in the ContinuationList that follows the current move. If it is not the move is no executed, and not added to the History, but an exception is thrown:

Throws:
java.lang.IndexOutOfBoundsException - is thrown if the move is not in the ContinuationList.

getNext

public Move getNext()
returns the next move on the currMove's main line. It returns the move that would be executed by next(0);


getNext

public Move getNext(int i)
returns the next move (variation 'i'). This is just a convientient way of calling history.getCurrentMove().getContinuationList().get(i);

Parameters:
i - is the variation number '0' is the main line
Returns:
null if there are no more moves, or if the list is empty
Throws:
IndexArrayOutOfBounds - if variation asked for doesn't exist

getContinuationList

public ContinuationList getContinuationList()
returns the continuationList for the currMove. Or if there is no current move then the ContinuationList of the start of the game.


prev

public Move prev()
unexecutes the last move and backs the currMove up one

Returns:
null if already at the beginning of the history

goTo

public Move goTo(Move m)
goes to this move in the history list unexecuting or executing moves as is necessary to reach a game state where m was the last move executed on the board.

Parameters:
m - if null a rewind() will be executed

rewind

public void rewind()
undoes any moves already done until we are at the begining


fastforward

public int fastforward(int n)
moves forward on the mainline of the current variation N moves. If there are less than N moves on the line it will stop at the last move.

Parameters:
n - the number of moves to move through.
Returns:
the number of moves actually moved through (in the case of early termination of the line).

goToEnd

public void goToEnd()
opposite of rewind() this goes to the end of the current branch performing all moves on the branch's main line as it goes.


rewindToLastFork

public Move rewindToLastFork()
rewinds the history until the current move is a move with variations.

Returns:
Move - the current move (last move played)

hasNext

public boolean hasNext()
this applies to the main line.

Returns:
false no move follows the last move executed

isEmpty

public boolean isEmpty()
is the history list completely empty?


getCurrentMove

public Move getCurrentMove()
returns the last executed move.

Returns:
null at the beginning of the list

getFinalMove

public Move getFinalMove(boolean trueMainLine)
returns the final move played on the main line or the current line. Note: this does not effect the move pointer (getCurrentMove()).

Parameters:
trueMainLine - do you want the last move on the main line from game (instead of the main line from the current variation).
Returns:
last move from the main line. if trueMainLine is true then this will be the last move from the how the game was played. if trueMainLine is false then the final move from the current variation is returned. If the current variation is the main line then the results are the same no matter the value of trueMainLine.

removeLastMove

public Move removeLastMove()
unexecutes the last move executed, disposes of all its data then returns the move, which should only contain the cooridinates of the move. The move tree is truncated at this point.

Returns:
what's left of the deleted move (dispose was called)

truncate

public Move truncate(int i)
deletes all branches from currMove (making currMove a terminal node) for the "i" variation.

Parameters:
i - - the branch we want to truncate. (-1 to remove all)
Returns:
Move - the current move (same as getLastMove)

truncate

public Move truncate()
calls truncate(-1)


size

public int size()
returns the number of moves in the main line


toString

public java.lang.String toString()

equals

public boolean equals(History hist)
this compares the main-line only. Annotations and variants will not be compared.


deepEquals

public boolean deepEquals(History hist,
                          boolean checkAnno)
this compares all moves on the main-line, and all variations. The order of the variations will not matter (not even the main line) only that they are indeed a continuation. If results are being checked then a null result is considered the same as isUndecided();

Parameters:
checkAnno - if true will compare the annotations, prenotations, and variation results as well. If false the results will also not be checked.

hashCode

public int hashCode()
this returns a static number. And thus isn't terribly useful. But since the data in History changes so often it might be the right thing to do until someone can convince me otherwise.


Submit a bug or feature
Visit the Website
Internet Chess ToolKit is licensed under the GPL v2 .