Board

java.lang.Object
- edu.kit.iti.lfm.spotlight.Board

All Implemented Interfaces:

Iterable<Field>
```
public class Board
extends Object
implements Iterable<Field>
```
The board class is used to provide all necessary information on a Spotlight board which is a rectangular matrix of Field elements.
Coordinates
Fields on a board are referenced by a pair of coordinates. The first coordinate is the row and the second is the column beginning from the upper-left corner, like in the following schema:
```
 +-------+-------+-------+-- ... --+-------+
 |  1,1  |  1,2  |  1,3  |         |  1,C  | 
 +-------+-------+-------+-- ... --+-------+
 |  2,1  |  2,2  |  2,3  |         |  2,C  |
 +-------+-------+-------+-- ... --+-------+
    ...     ...     ...               ...
 +-------+-------+-------+-- ... --+-------+
 |  R,1  |  R,2  |  R,3  |         |  R,C  |
 +-------+-------+-------+-- ... --+-------+
 
```
with C=countColumns() and R=countRows().
Iteration and sequential indexing is done row-wise, from left to right and from top to bottom. The sequential index of the upper-left corner is 1.
Import
Boards can be read from Strings or from Files. The format is according to the grammar:
```
   Board ::= Rows ";" Columns ";" ( Field )+
   Field ::= Direction ":" Constraint
   Rows,Columns ::= positive integer
   Constraint ::= non-negative integer 
   Direction ::= "N" | "NE" | "E" | "SE" | "S" | "SW" | "W" | "NW"
 
```
where exactly height⋅width many field declarations must be given.
Author:

Mattias Ulbrich, David Farago

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`colorFields(int[] coloring)`
`void`	`colorFields(String coloring)`
`boolean`	`containsCoordinates(int row, int column)` Check whether the coordinates refer to a field on the board.
`int`	`countColumns()` Get the number of columns on the board, i.e., its width.
`int`	`countRows()` Get the number of rows on the board, i.e., its height.
`static Board`	`fromFile(File file)` Extract a board from the contents of file.
`static Board`	`fromStringDescription(String descr)` Extract a board from a string description.
`String`	`getColoringString()` Gets a string representation of the coloured board.
`Field`	`getField(int row, int column)` Gets a field on the board
`List<Field>`	`getRegionForField(int row, int column)` Get the region an arrow points to.
`int`	`getSequentialIndex(Field field)` The sequential index of a field in the board, e.g. for usage as propositional atom.
`Iterator<Field>`	`iterator()` Get an iterator going over all fields on the board.
`static String`	`readFileAsString(File file)` Read a file into a string.
`String`	`toDescriptionString()` Boards (i.e., signs and constraints, but not colors) can be written to a file.
`String`	`toString()`
`void`	`visualise()` Open a new frame and visualize the current board in this frame.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - countColumns
```
public int countColumns()
```
    Get the number of columns on the board, i.e., its width.
    
    Returns:
    a positive integer representing the column quantity of the board, i.e. its width.
  - countRows
```
public int countRows()
```
    Get the number of rows on the board, i.e., its height.
    
    Returns:
    a positive integer representing the row quantity of the board, i.e. its height.
  - containsCoordinates
```
public boolean containsCoordinates(int row,
                          int column)
```
    Check whether the coordinates refer to a field on the board.
    
    Parameters:
    row - the row coordinate
    column - the column coordinate
    
    Returns:
    true if and only if the row ∈ [1, getHeight()] and col ∈ [1, getWidth()].
  - getField
```
public Field getField(int row,
             int column)
```
    Gets a field on the board
    
    Parameters:
    row - a row coordinate between 1 and countRows()
    column - a column coordinate between 1 and countColumns()
    
    Returns:
    the non-null field at (row, column) on this board
    
    Throws:
    
    IllegalArgumentException - if parameters specify a coordinate not on board.
  - getRegionForField
```
public List<Field> getRegionForField(int row,
                            int column)
```
    Get the region an arrow points to.
    The region is the list of Fields to which the arrow in field points to. field itself is not included in the result.
    
    Returns:
    a freshly created list of the fields that the arrow on field points to.
  - getSequentialIndex
```
public int getSequentialIndex(Field field)
```
    The sequential index of a field in the board, e.g. for usage as propositional atom.
  - iterator
```
public Iterator<Field> iterator()
```
    Get an iterator going over all fields on the board.
    The fields are iterated in the order of sequential indexing: row-wise from left to right, top to bottom.
    
    Specified by:
    
    iterator in interface Iterable<Field>
    
    Returns:
    a freshly created iterator over the fields.
  - visualise
```
public void visualise()
```
    Open a new frame and visualize the current board in this frame. (Particularly useful for debugging)
  - getColoringString
```
public String getColoringString()
```
    Gets a string representation of the coloured board.
    For the result the fields are iterated in the order of the fields' sequential index and their colour is represented by a character each: 1 for white, 0 for black and - for uncolored.
    
    Returns:
    a non-null string representing the coloring of the board.
  - colorFields
```
public void colorFields(String coloring)
```
  - colorFields
```
public void colorFields(int[] coloring)
```
  - fromStringDescription
```
public static Board fromStringDescription(String descr)
                                   throws SpotlightException
```
    Extract a board from a string description.
    Boards (i.e., signs and constraints, but not colours) can be read from a text description. The format is defined in the above grammar.
    
    Parameters:
    descr - a String describing a board according to the grammar
    
    Returns:
    a freshly created board corresponding to the textual description of descr.
    
    Throws:
    
    SpotlightException - if descr is not correctly formatted.
  - fromFile
```
public static Board fromFile(File file)
                      throws SpotlightException,
                             IOException
```
    Extract a board from the contents of file. Boards (i.e., signs and constraints, but not colours) can be read from a text description. The format is defined in the above grammar. To use this method, the file must be readable and its content must exactly have the described format. No extra characters are allowed.
    
    Parameters:
    file - the file to read the description from
    
    Returns:
    a freshly created board corresponding to the textual description in file
    
    Throws:
    
    SpotlightException - if file is not correctly formatted.
    
    IOException - if the file does not exist, cannot be opened or read
  - readFileAsString
```
public static String readFileAsString(File file)
                               throws IOException
```
    Read a file into a string. A buffer in the length of the file is created, the entire content read in one go and the result used to create a String object. The default character encoding is used to decode the string.
    
    Parameters:
    file - the file to be read, must be readable
    
    Returns:
    a string holding the content of the file.
    
    Throws:
    
    IOException - Signals that an I/O exception has occurred.
  - toDescriptionString
```
public String toDescriptionString()
```
    Boards (i.e., signs and constraints, but not colors) can be written to a file. The format is defined in the above grammar.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class Board

Coordinates

Import

Method Summary

Methods inherited from class java.lang.Object

Method Detail

countColumns

countRows

containsCoordinates

getField

getRegionForField

getSequentialIndex

iterator

visualise

getColoringString

colorFields

colorFields

fromStringDescription

fromFile

readFileAsString

toDescriptionString

toString