CitySim Docs
Fall 2025
API

# Grid

o1.grid.Grid
trait Grid[Element](val width: Int, val height: Int)

The trait `Grid` represents rectangular grids that contain elements of a particular kind. Each element in a grid is located at a unique pair of coordinates, represented as a GridPos.

X coordinates run from 0 to `width-1`, y coordinates from 0 to `height-1`. (0,0) corresponds to the upper left corner of the grid.

There are different kinds of grids: the type of element that a grid contains is defined by the grid’s type parameter. For instance, `Grid[Square]` is a grid where each pair of x and y coordinates contains a `Square` object, and `Grid[House]` is a grid containing `House` objects.

A `Grid` is mutable: it is possible to replace an element at a particular `GridPos` with another. (Depending on the element type, the elements may be individually mutable, too.) The width and height of a grid never change, however.

Upon creation, a `Grid` initializes itself by calling initialElements, which produces an initial state for the grid.

This trait has an alias in the top-level package o1, so it’s accessible to students simply via `import o1.*`.

## Parameters

height

  the number of elements in each column of the grid

width

  the number of elements in each row of the grid

## Attributes

Graph
Supertypes
  class Object
  trait Matchable
  class Any
Known subtypes
  class CityMap

## Members list

### Value members

#### Abstract methods

def initialElements: Seq[Element]

Generates the elements that initially occupy the grid. This method is automatically invoked by every `Grid` object upon creation. Subtypes should implement this method as appropriate for the particular sort of grid desired.

Generates the elements that initially occupy the grid. This method is automatically invoked by every `Grid` object upon creation. Subtypes should implement this method as appropriate for the particular sort of grid desired.

Note that since this method produces the `Grid`’s initial contents, it gets called during initialization before the `Grid` actually has any elements as content. Therefore, subtypes’ implementations of this method must not depend on the state of the new `Grid` (by calling `neighbors` or `elementAt`, for instance) or attempt to modify the `Grid` (with `update`, for instance).

This method is meant for initialization purposes only. To access all the elements of an already-initialized `Grid`, call allElements instead.

## Attributes

Returns

  a collection of size `width` times `height` that contains the initial grid elements. The first element in the collection will appear at `GridPos` (0,0), the second at (1,0), and so on, filling in the first row before continuing on the second row at (0,1).

#### Concrete methods

def allElements: Vector[Element]

Returns a collection of all the elements currently in the grid.

Returns a collection of all the elements currently in the grid.

## Attributes

def allPositions: Vector[GridPos]

Returns a collection of all the locations on the grid.

Returns a collection of all the locations on the grid.

## Attributes

def apply(location: GridPos): Element

Returns the element at the given pair of coordinates. (This does the same as `elementAt`.)

Returns the element at the given pair of coordinates. (This does the same as `elementAt`.)

## Parameters

location

  a location on the grid (which must be within range or this method will fail with an error)

## Attributes

def contains(location: GridPos): Boolean

Determines whether the grid contains the given pair of coordinates. For instance, a grid with a width and height of 5 will contain (0, 0) and (4, 4) but not (-1, -1), (4, 5) or (5, 4).

Determines whether the grid contains the given pair of coordinates. For instance, a grid with a width and height of 5 will contain (0, 0) and (4, 4) but not (-1, -1), (4, 5) or (5, 4).

## Attributes

def elementAt(location: GridPos): Element

Returns the element at the given pair of coordinates. (This does the same as `apply`.)

Returns the element at the given pair of coordinates. (This does the same as `apply`.)

## Parameters

location

  a location on the grid (which must be within range or this method will fail with an error)

## Attributes

def neighbors(middleLoc: GridPos, includeDiagonals: Boolean): Vector[Element]

Returns a vector of all the neighboring elements of the element indicated by the first parameter. Depending on the second parameter, either only the four neighbors in cardinal compass directions (north, east, south, west) are considered, or the four diagonals as well.

Returns a vector of all the neighboring elements of the element indicated by the first parameter. Depending on the second parameter, either only the four neighbors in cardinal compass directions (north, east, south, west) are considered, or the four diagonals as well.

Note that an element at the grid’s edge has fewer neighbors than one in the middle. For instance, the element at (0, 0) of a 5-by-5 grid has only three neighbors, diagonals included.

## Parameters

includeDiagonals

  `true` if diagonal neighbors also count (resulting in up to eight neighbors), `false` if only cardinal directions count (resulting in up to four)

middleLoc

  the location between the neighbors

## Attributes

def randomElement(): Element

Returns a random element from the grid. Uses the scala.util.Random singleton.

Returns a random element from the grid. Uses the scala.util.Random singleton.

## Attributes

def randomPos(): GridPos

Returns a random location from the grid. Uses the scala.util.Random singleton.

Returns a random location from the grid. Uses the scala.util.Random singleton.

## Attributes

def swap(location1: GridPos, location2: GridPos): Unit

Swaps the elements at two given locations on the grid. The given locations must be within range or this method will fail with an error.

Swaps the elements at two given locations on the grid. The given locations must be within range or this method will fail with an error.

## Attributes

def update(location: GridPos, newElement: Element): Unit

Modifies the grid by replacing the existing element at the given location with the new element.

Modifies the grid by replacing the existing element at the given location with the new element.

## Parameters

location

  a location on the grid (which must be within range or this method will fail with an error)

newElement

  the new element that replaces the old one at `location`

## Attributes

#### Concrete fields

val height: Int
val size: Int

the number of elements in this grid, in total. (Equals `width` times `height`.)

the number of elements in this grid, in total. (Equals `width` times `height`.)

## Attributes

val width: Int