# `Buzzword.Bingo.Square`
[🔗](https://github.com/RaymondLoranger/buzzword_bingo_square/blob/main/lib/buzzword/bingo/square.ex#L4)

A square struct and functions for the _Multi-Player Buzzword Bingo_ game.

The square struct contains the fields:

  - `phrase`
  - `points`
  - `marked_by`

representing the properties of a square in the _Multi-Player Buzzword Bingo_
game.

##### Based on the course [Multi-Player Bingo](https://pragmaticstudio.com/courses/unpacked-bingo) by Mike and Nicole Clark.

# `phrase`

```elixir
@type phrase() :: String.t()
```

Square phrase

# `points`

```elixir
@type points() :: pos_integer()
```

Square points

# `t`

```elixir
@type t() :: %Buzzword.Bingo.Square{
  marked_by: Buzzword.Bingo.Player.t() | nil,
  phrase: phrase(),
  points: points()
}
```

A square struct for the Multi-Player Buzzword Bingo game

# `mark`

```elixir
@spec mark(t(), phrase(), Buzzword.Bingo.Player.t()) :: t()
```

Marks a virgin `square` having the given `phrase` with the given `player`.

## Examples

    iex> alias Buzzword.Bingo.{Player, Square}
    iex> square = Square.new("Bottom Line", 375)
    iex> arthur = Player.new("Arthur", "green_yellow")
    iex> Square.mark(square, "Bottom Line", arthur)
    %Square{
      phrase: "Bottom Line",
      points: 375,
      marked_by: %Player{name: "Arthur", color: "green_yellow"}
    }

    iex> alias Buzzword.Bingo.{Player, Square}
    iex> square = Square.new("Big Picture", 225)
    iex> arnold = Player.new("Arnold", "bright_turquoise")
    iex> Square.mark(square, "Best of Breed", arnold)
    %Square{phrase: "Big Picture", points: 225, marked_by: nil}

    iex> alias Buzzword.Bingo.{Player, Square}
    iex> square = Square.new("Best of Breed", 525)
    iex> joe = Player.new("Joe", "light_cyan")
    iex> jim = Player.new("Jim", "light_yellow")
    iex> square = Square.mark(square, "Best of Breed", joe)
    iex> Square.mark(square, "Best of Breed", jim)
    %Square{
      phrase: "Best of Breed",
      points: 525,
      marked_by: %Player{name: "Joe", color: "light_cyan"}
    }

# `new`

```elixir
@spec new(Buzzword.Cache.buzzword()) :: t() | {:error, atom()}
```

Creates a square struct from the given `buzzword`.

## Examples

    iex> alias Buzzword.Bingo.Square
    iex> Square.new({"Bottom Line", 375})
    %Square{phrase: "Bottom Line", points: 375}

    iex> alias Buzzword.Bingo.Square
    iex> Square.new({"Bottom Line", 0})
    {:error, :invalid_square_args}

# `new`

```elixir
@spec new(phrase(), points()) :: t() | {:error, atom()}
```

Creates a square struct from the given `phrase` and `points`.

## Examples

    iex> alias Buzzword.Bingo.Square
    iex> Square.new("Bottom Line", 375)
    %Square{phrase: "Bottom Line", points: 375}

    iex> alias Buzzword.Bingo.Square
    iex> Square.new("Bottom Line", 0)
    {:error, :invalid_square_args}

---

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