# `Calendrical.Coptic`

Implementation of the Coptic calendar.

The Coptic calendar is a 13-month calendar derived from the
ancient Egyptian calendar, currently used by the Coptic
Orthodox Church of Alexandria. The first twelve months each
have 30 days; the thirteenth month (the *epagomenal* month
Pi Kogi Enavot) has 5 days, or 6 in a leap year.

The epoch is the start of the Era of Martyrs (anno martyrum),
29 August 284 CE in the Julian calendar.

# `day`

```elixir
@type day() :: 1..30
```

# `month`

```elixir
@type month() :: 1..13
```

# `year`

```elixir
@type year() :: -9999..-1 | 1..9999
```

# `calendar_base`

Identifies whether this calendar is month
or week based.

# `calendar_year`

```elixir
@spec calendar_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.year()
```

Returns the calendar year as displayed
on rendered calendars.

# `cldr_calendar_type`

Defines the CLDR calendar type for this calendar.

This type is used in support of `Calendrical.
localize/3`.

# `cyclic_year`

```elixir
@spec cyclic_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.year()
```

Returns the cyclic year as displayed
on rendered calendars.

# `date_from_iso_days`

```elixir
@spec date_from_iso_days(integer()) :: {year(), month(), day()}
```

Returns a Coptic `{year, month, day}` tuple for the given ISO day
number.

### Arguments

* `iso_days` is an integer count of days since the proleptic
  ISO epoch.

### Returns

* A three-tuple `{year, month, day}` in the Coptic calendar.

### Examples

    iex> Calendrical.Coptic.date_from_iso_days(740_000)
    {1742, 5, 11}

# `date_to_iso_days`

```elixir
@spec date_to_iso_days(year(), month(), day()) :: integer()
```

Returns the number of ISO days for the given Coptic `year`,
`month`, and `day`.

### Arguments

* `year` is any Coptic year as an integer.

* `month` is a Coptic month in the range `1..13`.

* `day` is a Coptic day-of-month.

### Returns

* An integer count of days since the proleptic ISO epoch.

### Examples

    iex> Calendrical.Coptic.date_to_iso_days(1742, 1, 1)
    739870

# `day_of_era`

```elixir
@spec day_of_era(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {day :: Calendar.day(), era :: Calendar.era()}
@spec day_of_era(year(), month(), day()) :: {non_neg_integer(), 0..1}
```

Returns the day-of-era and era for the given Coptic `year`,
`month`, and `day`.

### Arguments

* `year` is any Coptic year as an integer.

* `month` is a Coptic month in the range `1..13`.

* `day` is a Coptic day-of-month.

### Returns

* A two-tuple `{day_in_era, era}` where `era` is `0` or `1`.

### Examples

    iex> Calendrical.Coptic.day_of_era(1742, 1, 1)
    {635901, 1}

    iex> Calendrical.Coptic.day_of_era(1, 1, 1)
    {1, 1}

# `day_of_week`

```elixir
@spec day_of_week(
  Calendar.year(),
  Calendar.month(),
  Calendar.day(),
  :default | atom()
) ::
  {Calendar.day_of_week(), first_day_of_week :: non_neg_integer(),
   last_day_of_week :: non_neg_integer()}
@spec day_of_week(
  year(),
  month(),
  day(),
  :default
  | :monday
  | :tuesday
  | :wednesday
  | :thursday
  | :friday
  | :saturday
  | :sunday
) :: {1..7, 1 | 6, 5 | 7}
```

Returns the day of the week for the given Coptic `year`, `month`,
and `day`.

Coptic weeks begin on Saturday, so the returned tuple has
`first_day_of_week = 6` and `last_day_of_week = 5`.

### Arguments

* `year` is any Coptic year as an integer.

* `month` is a Coptic month in the range `1..13`.

* `day` is a Coptic day-of-month.

* `starting_on` is `:default` for the calendar's natural week
  boundary (Saturday).

### Returns

* A three-tuple `{day_of_week, first_day_of_week, last_day_of_week}`.

### Examples

    iex> Calendrical.Coptic.day_of_week(1742, 1, 1, :default)
    {4, 6, 5}

# `day_of_year`

```elixir
@spec day_of_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.day()
```

Calculates the day of the year from the given
`year`, `month`, and `day`.

# `days_in_month`

```elixir
@spec days_in_month(Calendar.month()) ::
  Calendar.month()
  | {:ambiguous, Range.t() | [pos_integer()]}
  | {:error, :undefined}
```

Returns how many days there are in the given month.

Must be implemented in derived calendars because
we cannot know what the calendar format is.

# `days_in_month`

```elixir
@spec days_in_month(Calendar.year(), Calendar.month()) :: Calendar.month()
@spec days_in_month(year(), month()) :: 5..30
```

Returns the number of days in the given Coptic `year` and `month`.

Months 1-12 always have 30 days; month 13 has 5 days, or 6
in a leap year.

### Arguments

* `year` is any Coptic year as an integer.

* `month` is a Coptic month in the range `1..13`.

### Returns

* An integer number of days.

### Examples

    iex> Calendrical.Coptic.days_in_month(1742, 1)
    30

    iex> Calendrical.Coptic.days_in_month(1742, 13)
    5

    iex> Calendrical.Coptic.days_in_month(1743, 13)
    6

# `days_in_week`

Returns the number days in a a week.

# `days_in_year`

```elixir
@spec days_in_year(year()) :: 365..366
```

Returns the number of days in the given Coptic `year`.

### Arguments

* `year` is any Coptic year as an integer.

### Returns

* `365` for an ordinary year or `366` for a leap year.

### Examples

    iex> Calendrical.Coptic.days_in_year(1742)
    365

    iex> Calendrical.Coptic.days_in_year(1743)
    366

# `epoch`

# `epoch_day_of_week`

# `extended_year`

```elixir
@spec extended_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.year()
```

Returns the extended year as displayed
on rendered calendars.

# `first_day_of_week`

# `iso_week_of_year`

```elixir
@spec iso_week_of_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {:error, :not_defined}
```

Calculates the ISO week of the year from the
given `year`, `month`, and `day`.

By default this function always returns
`{:error, :not_defined}`.

# `last_day_of_week`

# `leap_year?`

```elixir
@spec leap_year?(year()) :: boolean()
```

Returns whether the given Coptic `year` is a leap year.

A Coptic year is a leap year when it is one less than a multiple
of four (i.e. `rem(year, 4) == 3`).

### Arguments

* `year` is any Coptic year as an integer.

### Returns

* `true` if the year contains 366 days; otherwise `false`.

### Examples

    iex> Calendrical.Coptic.leap_year?(1743)
    true

    iex> Calendrical.Coptic.leap_year?(1742)
    false

# `month`

Returns a `t:Date.Range.t/0` representing
a given month of a year.

# `month_of_year`

```elixir
@spec month_of_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.month() | {Calendar.month(), Calendrical.leap_month?()}
```

Returns the month of the year from the given
`year`, `month`, and `day`.

# `months_in_leap_year`

Returns the number of months in a leap year.

# `months_in_ordinary_year`

Returns the number of months in a normal year.

# `months_in_year`

Returns the number of months in a year, without a year.

Returns an integer when every year has the same number of
months, or `{:ambiguous, first..last}` for lunisolar calendars
whose year length varies (e.g. the Hebrew calendar's 12 or 13
months).

# `months_in_year`

Returns the number of months in a
given `year`.

# `naive_datetime_from_iso_days`

```elixir
@spec naive_datetime_from_iso_days(Calendar.iso_days()) ::
  {Calendar.year(), Calendar.month(), Calendar.day(), Calendar.hour(),
   Calendar.minute(), Calendar.second(), Calendar.microsecond()}
```

Converts the `t:Calendar.iso_days` format to the
datetime format specified by this calendar.

# `naive_datetime_to_iso_days`

```elixir
@spec naive_datetime_to_iso_days(
  Calendar.year(),
  Calendar.month(),
  Calendar.day(),
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond()
) :: Calendar.iso_days()
```

Returns the `t:Calendar.iso_days` format of
the specified date.

# `periods_in_year`

Returns the number of periods in a given
`year`. A period corresponds to a month
in month-based calendars and a week in
week-based calendars.

# `plus`

Adds an `increment` number of `date_part`s
to a `year-month-day`.

`date_part` can be `:years`, `:months`, `:weeks` or `:days`.

# `quarter`

Returns a `t:Date.Range.t/0` representing
a given quarter of a year.

# `quarter_of_year`

```elixir
@spec quarter_of_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendrical.quarter()
```

Returns `{:error, :not_defined}` because the Coptic calendar
does not define quarters; the year has 13 months and so does not
divide evenly into four quarters.

### Arguments

* `year` is any Coptic year as an integer.

* `month` is a Coptic month in the range `1..13`.

* `day` is a Coptic day-of-month.

### Returns

* `{:error, :not_defined}`.

### Examples

    iex> Calendrical.Coptic.quarter_of_year(1742, 1, 1)
    {:error, :not_defined}

# `related_gregorian_year`

```elixir
@spec related_gregorian_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.year()
@spec related_gregorian_year(year(), month(), day()) :: Calendar.year()
```

Returns the Gregorian year that contains the given Coptic date.

### Arguments

* `year` is any Coptic year as an integer.

* `month` is a Coptic month in the range `1..13`.

* `day` is a Coptic day-of-month.

### Returns

* An integer Gregorian year.

### Examples

    iex> Calendrical.Coptic.related_gregorian_year(1742, 1, 1)
    2025

# `valid_date?`

```elixir
@spec valid_date?(year(), month(), day()) :: boolean()
```

Returns whether the supplied `year`, `month`, and `day` is a valid
Coptic date.

### Arguments

* `year` is any Coptic year as an integer.

* `month` is a Coptic month in the range `1..13`.

* `day` is a Coptic day-of-month. Months `1..12` have 30 days;
  month 13 has 5 days, or 6 in a leap year.

### Returns

* `true` if the date is valid; otherwise `false`.

### Examples

    iex> Calendrical.Coptic.valid_date?(1742, 1, 30)
    true

    iex> Calendrical.Coptic.valid_date?(1743, 13, 6)
    true

    iex> Calendrical.Coptic.valid_date?(1742, 13, 6)
    false

# `week`

Returns a `t:Date.Range.t/0` representing
a given week of a year.

# `week_of_month`

```elixir
@spec week_of_month(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {pos_integer(), pos_integer()} | {:error, :not_defined}
```

Calculates the week of the year from the given
`year`, `month`, and `day`.

By default this function always returns
`{:error, :not_defined}`.

# `week_of_year`

```elixir
@spec week_of_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {:error, :not_defined}
```

Calculates the week of the year from the given
`year`, `month`, and `day`.

By default this function always returns
`{:error, :not_defined}`.

# `weeks_in_year`

Returns the number of weeks in a
given `year`.

# `year`

Returns a `t:Date.Range.t/0` representing
a given year.

# `year_of_era`

```elixir
@spec year_of_era(Calendar.year()) :: {year :: Calendar.year(), era :: Calendar.era()}
@spec year_of_era(year()) :: {pos_integer(), 0..1}
```

Returns the year and era for the given Coptic `year`.

The Coptic calendar has two eras: the current era which starts
in year 1 and is defined as era `1` (anno martyrum); and a
second era for years less than 1, defined as era `0`.

### Arguments

* `year` is any Coptic year as an integer.

### Returns

* A two-tuple `{year_in_era, era}` where `era` is `0` or `1`.

### Examples

    iex> Calendrical.Coptic.year_of_era(1742)
    {1742, 1}

    iex> Calendrical.Coptic.year_of_era(-50)
    {50, 0}

# `year_of_era`

```elixir
@spec year_of_era(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {year :: Calendar.year(), era :: Calendar.era()}
@spec year_of_era(year(), month(), day()) :: {pos_integer(), 0..1}
```

Returns the year and era for the Coptic date given by `year`,
`month`, and `day`.

### Arguments

* `year` is any Coptic year as an integer.

* `month` is a Coptic month in the range `1..13`.

* `day` is a Coptic day-of-month.

### Returns

* A two-tuple `{year_in_era, era}` where `era` is `0` or `1`.

### Examples

    iex> Calendrical.Coptic.year_of_era(1742, 1, 1)
    {1742, 1}

---

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