# `Koyomi.ISOWeek`
[🔗](https://github.com/hattoriai/koyomi/blob/v0.2.1/lib/koyomi/iso_week.ex#L1)

ISO 8601 weeks: weeks start on Monday, and week 1 of a year is the week
that holds the year's first Thursday. A week is written `2027-W11`.

The week picker posts weeks in this form, and `Koyomi.Week` stores the
Monday of the week in a `:date` column.

# `from_iso8601`

```elixir
@spec from_iso8601(String.t()) :: {:ok, Date.t()} | :error
```

Reads `YYYY-Www` (or `YYYYWww`) into the Monday of the week.

## Examples

    iex> Koyomi.ISOWeek.from_iso8601("2027-W11")
    {:ok, ~D[2027-03-15]}
    iex> Koyomi.ISOWeek.from_iso8601("2027-W54")
    :error

# `monday`

```elixir
@spec monday(integer(), integer()) :: {:ok, Date.t()} | :error
```

The Monday of an ISO week, or `:error` when the year has no such week.

## Examples

    iex> Koyomi.ISOWeek.monday(2026, 53)
    {:ok, ~D[2026-12-28]}
    iex> Koyomi.ISOWeek.monday(2027, 53)
    :error

# `to_iso8601`

```elixir
@spec to_iso8601(Date.t()) :: String.t()
```

Writes the week of a day as `YYYY-Www`.

## Examples

    iex> Koyomi.ISOWeek.to_iso8601(~D[2027-03-17])
    "2027-W11"

# `week`

```elixir
@spec week(Date.t()) :: {integer(), 1..53}
```

The ISO year and week number of a day.

## Examples

    iex> Koyomi.ISOWeek.week(~D[2027-01-01])
    {2026, 53}
    iex> Koyomi.ISOWeek.week(~D[2027-03-15])
    {2027, 11}

# `weeks_in_year`

```elixir
@spec weeks_in_year(integer()) :: 52 | 53
```

The number of ISO weeks of a year: 52 or 53.

## Examples

    iex> Koyomi.ISOWeek.weeks_in_year(2026)
    53

---

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