Package: IC4BoardSlim

IC4BoardSlim

Coverage

1: package de.fhdw.gaming.ipspiel23.c4.domain;
2:
3: import java.util.Set;
4:
5:
6: /**
7: * The lightweight internal representation of the connect four board, somewhat optimized for performance.
8: */
9: public interface IC4BoardSlim extends IC4BoardBase {
10: /**
11: * A lightweight representation of the board-state in a single contiguous region of memory (data locality)
12: * for fast memory access and better data locality. Has getRowCount() rows and getColumnCount() columns.
13: * This method exposes the internal board state and should be used with care.
14: */
15: int[] getBoardStateUnsafe();
16:
17: /**
18: * Retrieves the token used to represent an empty field.
19: */
20: int emptyToken();
21:
22: /**
23: * Retrieves the token at the specified position without checking the bounds.
24: *
25: * @param row the row of the position
26: * @param column the column of the position
27: * @return the token at the specified position
28: * @throws ArrayIndexOutOfBoundsException if {@code row * getColumnCount() + column} is out of bounds;
29: * other row or column violations are not checked
30: */
31: int getTokenUnsafe(int row, int column);
32:
33: /**
34: * Updates the token at the specified position without checking the bounds.
35: *
36: * @param row the row index of the position
37: * @param column the column index of the position
38: * @param token the token to write to the specified position
39: * @throws ArrayIndexOutOfBoundsException if {@code position.getRow() * getColumnCount() + position.getColumn()}
40: * is out of bounds;
41: * other row or column violations are not checked
42: */
43: void updateTokenUnsafe(int row, int column, int token);
44:
45: /**
46: * Retrieves the player uniquely identified by the specified token.
47: * @param token the token
48: * @return the player, or null if no player is associated with the token
49: */
50: IC4Player getPlayerByToken(int token);
51:
52: /**
53: * Resets all caches of the solution analyzers causing lines determined being free of any
54: * solutions to be re-analyzed the next time a solution is searched.
55: */
56: void resetSolutionAnalyzerCaches();
57:
58: /**
59: * Lazy evaluation for the first solution, e.g. the first n-in-a-row (where n is the number of
60: * tokens in a row required to win)
61: * @return the first solution, or null if no solution exists for the current board state
62: */
63: IC4SolutionSlim tryFindFirstSolution();
64:
65: /**
66: * Lazy evaluation for the first solution, e.g. the first n-in-a-row (where n is the number of
67: * tokens in a row required to win)
68: * @param updateCache Whether to update the solution cache, preventing lines determined to not
69: * contain any solutions from being scanned again.
70: * @return the first solution, or null if no solution exists for the current board state
71: */
72: IC4SolutionSlim tryFindFirstSolution(boolean updateCache);
73:
74: /**
75: * Eager evaluation for all solutions, e.g. all n-in-a-row (where n is the number of
76: * tokens in a row required to win)
77: * @return all solutions, or an empty set if no solution exists for the current board state
78: */
79: Set<IC4SolutionSlim> findAllSolutions();
80:
81: /**
82: * Eager evaluation for all solutions, e.g. all n-in-a-row (where n is the number of
83: * tokens in a row required to win)
84: * @param updateCache Whether to update the solution cache, preventing lines determined to not
85: * contain any solutions from being scanned again.
86: * @return all solutions, or an empty set if no solution exists for the current board state
87: */
88: Set<IC4SolutionSlim> findAllSolutions(boolean updateCache);
89:
90: /**
91: * Checks whether the specified position is empty without checking the bounds.
92: *
93: * @param row the row of the position
94: * @param column the column of the position
95: * @return true if the specified position is empty, false otherwise
96: * @throws ArrayIndexOutOfBoundsException if {@code row * getColumnCount() + column} is out of bounds;
97: * other row or column violations are not checked
98: */
99: boolean isEmptyUnsafe(int row, int column);
100:
101: /**
102: * Checks whether the specified position is "solid" without checking the bounds.
103: * A position is solid if it is not empty, or if it is one row below the bottom row (i.e., it is the "floor")
104: *
105: * @param row the row of the position
106: * @param column the column of the position
107: * @return true if the specified position is solid, false if it is empty ("air") or out of bounds
108: */
109: boolean isSolidUnsafe(int row, int column);
110:
111: @Override
112: IC4BoardSlim deepCopy();
113:
114: /**
115: * Writes the positions of all tokens matching the specified token to the specified buffer.
116: * Positions are written in a "dematerialized" format, i.e. the row and column of each position are written
117: * as a single long value, where the row is stored in the upper 32 bits and the column in the lower 32 bits.
118: * This format is used to improve performance by not having to allocate a new object for each position.
119: * Also complies with the data locality principle, i.e. all positions are written to a single contiguous region
120: * of memory for faster memory access.
121: * @param buffer a reference to the buffer to write the positions to
122: * @param token the token to match
123: * @return the number of positions written to the buffer
124: * @see C4PositionMaterializer
125: * @throws ArrayIndexOutOfBoundsException if the buffer is too small to hold all positions.
126: */
127: int getDematPositionsByTokenUnsafe(long[] buffer, int token);
128:
129: /**
130: * Writes the positions of all empty fields to the specified buffer.
131: * Positions are written in a "dematerialized" format, i.e. the row and column of each position are written
132: * as a single long value, where the row is stored in the upper 32 bits and the column in the lower 32 bits.
133: * This format is used to improve performance by not having to allocate a new object for each position.
134: * Also complies with the data locality principle, i.e. all positions are written to a single contiguous region
135: * of memory for faster memory access.
136: * @param buffer A reference to the buffer to write the positions to
137: * @return the number of positions written to the buffer
138: * @see C4PositionMaterializer
139: * @throws ArrayIndexOutOfBoundsException if the buffer is too small to hold all positions.
140: */
141: // suppress "UseVarargs: Consider using varargs for methods or constructors which take
142: // an array the last parameter."
143: // using varargs here would be fatal because results are returned via the buffer...
144: @SuppressWarnings("PMD.UseVarargs")
145: int getLegalDematPositionsUnsafe(long[] buffer);
146: }