# `Islands.Coord`
[🔗](https://github.com/RaymondLoranger/islands_coord/blob/main/lib/islands/coord.ex#L4)

A coordinates struct and functions for the _Game of Islands_.

The coordinates struct contains the fields

  - `row`
  - `col`

representing the coordinates of a square in the _Game of Islands_.

##### Based on the book [Functional Web Development](https://pragprog.com/titles/lhelph/functional-web-development-with-elixir-otp-and-phoenix/) by Lance Halvorsen.

# `col`

```elixir
@type col() :: 1..10
```

Column number

# `row`

```elixir
@type row() :: 1..10
```

Row number

# `square`

```elixir
@type square() :: 1..100
```

Square number: (row - 1) * 10 + col

# `t`

```elixir
@type t() :: %Islands.Coord{col: col(), row: row()}
```

A coordinates struct for the Game of Islands

# `compare`

```elixir
@spec compare(t(), t()) :: :lt | :eq | :gt
```

Compares two coordinates structs based on their square numbers.

## Examples
    iex> alias Islands.Coord
    iex> Coord.compare(Coord.new!(4, 7), Coord.new!(5, 7))
    :lt

# `new`

```elixir
@spec new(square()) :: {:ok, t()} | {:error, atom()}
```

Returns `{:ok, coord}` or `{:error, reason}` if given an invalid `square`.

## Examples

    iex> alias Islands.Coord
    iex> Coord.new(99)
    {:ok, %Coord{row: 10, col: 9}}

    iex> alias Islands.Coord
    iex> Coord.new(0)
    {:error, :invalid_square_number}

# `new`

```elixir
@spec new(row(), col()) :: {:ok, t()} | {:error, atom()}
```

Returns `{:ok, coord}` or `{:error, reason}` if given an invalid `row` or
`col`.

## Examples

    iex> alias Islands.Coord
    iex> Coord.new(10, 10)
    {:ok, %Coord{col: 10, row: 10}}

    iex> alias Islands.Coord
    iex> Coord.new(0, 10)
    {:error, :invalid_coordinates}

# `new!`

```elixir
@spec new!(square()) :: t()
```

Returns a coordinates struct or raises if given an invalid `square`.

## Examples

    iex> alias Islands.Coord
    iex> Coord.new!(99)
    %Coord{row: 10, col: 9}

    iex> alias Islands.Coord
    iex> Coord.new!(101)
    ** (ArgumentError) cannot create coord, reason: :invalid_square_number

# `new!`

```elixir
@spec new!(row(), col()) :: t()
```

Returns a coordinates struct or raises if given an invalid `row` or `col`.

## Examples

    iex> alias Islands.Coord
    iex> Coord.new!(10, 10)
    %Coord{row: 10, col: 10}

    iex> alias Islands.Coord
    iex> Coord.new!(0, 1)
    ** (ArgumentError) cannot create coord, reason: :invalid_coordinates

# `to_row_col`

```elixir
@spec to_row_col(t()) :: String.t() | {:error, atom()}
```

Returns "<row> <col>" or `{:error, reason}` if given an invalid `coord`.

## Examples

    iex> alias Islands.Coord
    iex> {:ok, coord} = Coord.new(2, 9)
    iex> Coord.to_row_col(coord)
    "2 9"

    iex> alias Islands.Coord
    iex> Coord.to_row_col({1, 2})
    {:error, :invalid_coord_struct}

# `to_square`

```elixir
@spec to_square(t()) :: square() | {:error, atom()}
```

Returns a square number or `{:error, reason}` if given an invalid `coord`.

## Examples

    iex> alias Islands.Coord
    iex> {:ok, coord} = Coord.new(2, 9)
    iex> Coord.to_square(coord)
    19

    iex> alias Islands.Coord
    iex> Coord.to_square({1, 2})
    {:error, :invalid_coord_struct}

---

*Consult [api-reference.md](api-reference.md) for complete listing*