Astronomical (Calendars v0.2.4) View Source

The Astronomical calendar module.

From Wikipedia, 2020-07-24:

Astronomical year numbering is based on AD/CE year numbering, but follows normal decimal integer numbering more strictly. Thus, it has a year 0; the years before that are designated with negative numbers and the years after that are designated with positive numbers. Astronomers use the Julian calendar for years before 1582, including the year 0, and the Gregorian calendar for years after 1582, as exemplified by Jacques Cassini (1740), Simon Newcomb (1898) and Fred Espenak (2007).

Link to this section Summary

Types

astronomical_date()

astronomical_day()

astronomical_month()

astronomical_year()

fixed()

t()

Functions

add_days(cal_date, days, type \\ :fixed)

Adds the number of days to a fixed day or Astronomical date.

as_date(cal_date)

Returns a fixed day or Astronomical date as a Astronomical date.

as_fixed(cal_date)

Returns a fixed day or Astronomical date as a fixed day.

as_type(cal_date, type \\ :fixed)

Returns a fixed day or Astronomical date either as a fixed day or a Astronomical date.

compare(date1, date2)

Compares two Astronomical dates and returns...

date(year, month, day)

Returns a Astronomical date from its fields year, month, day.

date_diff(cal_date1, cal_date2)

Returns the difference (= number of days) between two Astronomical dates.

day(cal_date, type \\ :value)

Returns the day field of a Astronomical date.

epoch()

Returns the epoch of the Astronomical calendar.

eq(date1, date2)

Returns true if Astronomical date1 is equal Astronomical date2, otherwise false.

field_atom(field_index)

Returns the name of the field atom in a Astronomical date at field_index.

field_atoms()

Returns a list of the field atoms (names) of a Astronomical date.

field_count()

Returns the number of fields in a Astronomical date

field_index(field_atom)

Returns the index (= position) of the field_atom in a Astronomical date.

from_date(other_date, other_calendar)

Converts the other_date of the other_calendar into the equivalent date of the Astronomical calendar.

from_fixed(fixed)

Converts a fixed day to a Astronomical date.

from_jd(day)

Converts a Julian Day into the equivalent Astronomical date.

from_rata_die(rd)

Converts a RataDie date into the equivalent Astronomical date.

from_unix(unix_date)

Converts a Unix date into the equivalent Astronomical date.

ge(date1, date2)

Returns true if Astronomical date1 is greater (= later) than or equal Astronomical date2, otherwise false.

gt(date1, date2)

Returns true if Astronomical date1 is greater (= later) than Astronomical date2, otherwise false.

keyword()

Returns the internal keyword of the Astronomical calendar.

le(date1, date2)

Returns true if Astronomical date1 is smaller (= earlier) than or equal Astronomical date2, otherwise false.

leap_year?(year)

Returns true if the Astronomical year is a leap year, otherwise false.

lt(date1, date2)

Returns true if Astronomical date1 is smaller (= earlier) than Astronomical date2, otherwise false.

module()

Returns the module of the Astronomical calendar.

month(cal_date, type \\ :value)

Returns the month field of a Astronomical date.

name()

Returns the internal name of the Astronomical calendar.

range(date1, date2)

Returns the distance between two Astronomical dates as a range of fixed days.

start_of_day()

Returns the start of the day in the Astronomical calendar.

switch_over()

Returns the switch over date from the Julian to the Gregorian calendar as a fixed day.

to_date(date, other_calendar)

Converts a Astronomical date into the equivalent date of the other_calendar.

to_fixed(date)

Converts a Astronomical date tuple into a fixed day.

to_fixed(year, month, day)

Converts a Astronomical date given by year, month, day into a fixed day.

to_jd(cal_date)

Converts a Astronomical date into the equivalent Julian Day.

to_jd(year, month, day)

Converts a Astronomical date given by year, month, day into the equivalent Julian Day.

to_rata_die(date)

Converts a Astronomical date into the equivalent RataDie date.

to_rata_die(year, month, day)

Converts a Astronomical date given by year, month, day into the equivalent RataDie date.

to_unix(cal_date)

Converts a Astronomical date into the equivalent Unix date.

to_unix(year, month, day)

Converts a Astronomical date given by year, month, day into the equivalent Unix date.

today(type \\ :fixed)

Returns the current date either as a fixed day or a Astronomical date.

year(cal_date, type \\ :value)

Returns the year field of a Astronomical date.

Link to this section Types

astronomical_date()

Specs

astronomical_date() ::
  {astronomical_year(), astronomical_month(), astronomical_day()}

astronomical_day()

Specs

astronomical_day() :: 1..31

astronomical_month()

Specs

astronomical_month() :: 1..12

astronomical_year()

Specs

astronomical_year() :: integer()

fixed()

Specs

fixed() :: integer()

t()

Specs

t() :: astronomical_date()

Link to this section Functions

add_days(cal_date, days, type \\ :fixed)

Specs

add_days(fixed() | astronomical_date(), integer(), :fixed | :date) ::
  fixed() | astronomical_date()

Adds the number of days to a fixed day or Astronomical date.

If days is negative, the days will be subtracted.

The type parameter determines the type of the returned value:

:fixed returns a fixed day (default),
:date returns a Astronomical date.

Examples

  iex>Elixir.Astronomical.add_days(730739, 100)
  730839
  iex>Elixir.Astronomical.add_days(730739, -100)
  730639

  iex>Elixir.Astronomical.add_days(730739, 100, :fixed)
  730839
  iex>Elixir.Astronomical.add_days(730739, -100, :fixed)
  730639

  iex>Elixir.Astronomical.add_days(730739, 100, :date)
  {2001, 12, 20}
  iex>Elixir.Astronomical.add_days(730739, -100, :date)
  {2001, 6, 3}

  iex>Elixir.Astronomical.add_days({2001, 9, 11}, 100)
  730839
  iex>Elixir.Astronomical.add_days({2001, 9, 11}, -100)
  730639

  iex>Elixir.Astronomical.add_days({2001, 9, 11}, 100, :fixed)
  730839
  iex>Elixir.Astronomical.add_days({2001, 9, 11}, -100, :fixed)
  730639

  iex>Elixir.Astronomical.add_days({2001, 9, 11}, 100, :date)
  {2001, 12, 20}
  iex>Elixir.Astronomical.add_days({2001, 9, 11}, -100, :date)
  {2001, 6, 3}

as_date(cal_date)

Specs

as_date(fixed() | astronomical_date()) :: astronomical_date()

Returns a fixed day or Astronomical date as a Astronomical date.

This is a convenience function to simplify certain function calls.

Examples

  iex>Elixir.Astronomical.as_date(730739)
  {2001, 9, 11}
  iex>Elixir.Astronomical.as_date({2001, 9, 11})
  {2001, 9, 11}

as_fixed(cal_date)

Specs

as_fixed(fixed() | astronomical_date()) :: fixed()

Returns a fixed day or Astronomical date as a fixed day.

This is a convenience function to simplify certain function calls.

Examples

  iex>Elixir.Astronomical.as_fixed(730739)
  730739
  iex>Elixir.Astronomical.as_fixed({2001, 9, 11})
  730739

as_type(cal_date, type \\ :fixed)

Specs

as_type(fixed() | astronomical_date(), :fixed | :date) ::
  fixed() | astronomical_date()

Returns a fixed day or Astronomical date either as a fixed day or a Astronomical date.

The type parameter determines the type of the returned value:

:fixed returns a fixed day (default),
:date returns a Astronomical date.

Examples

  iex>Elixir.Astronomical.as_type(730739)
  730739
  iex>Elixir.Astronomical.as_type(730739, :fixed)
  730739
  iex>Elixir.Astronomical.as_type(730739, :date)
  {2001, 9, 11}
  iex>Elixir.Astronomical.as_type({2001, 9, 11})
  730739
  iex>Elixir.Astronomical.as_type({2001, 9, 11}, :fixed)
  730739
  iex>Elixir.Astronomical.as_type({2001, 9, 11}, :date)
  {2001, 9, 11}

compare(date1, date2)

Specs

compare(astronomical_date(), astronomical_date()) :: :lt | :eq | :gt

Compares two Astronomical dates and returns...

:lt if date1 is smaller (= earlier) than date2,
:eq if date1 is equal date2,
:gt if date1 is larger (= later) than date2.

Examples

  iex>Elixir.Astronomical.compare({2001, 9, 11}, {2001, 9, 11})
  :eq
  iex>Elixir.Astronomical.compare({2001, 9, 11}, {2001, 12, 20})
  :lt
  iex>Elixir.Astronomical.compare({2001, 12, 20}, {2001, 9, 11})
  :gt

date(year, month, day)

Specs

date(astronomical_year(), astronomical_month(), astronomical_day()) :: t()

Returns a Astronomical date from its fields year, month, day.

Example

  iex>Elixir.Astronomical.date(2001, 9, 11)
  {2001, 9, 11}

date_diff(cal_date1, cal_date2)

Specs

date_diff(fixed() | astronomical_date(), fixed() | astronomical_date()) ::
  integer()

Returns the difference (= number of days) between two Astronomical dates.

The dates can be given as fixed days or Astronomical dates in arbitrary combination. The difference is calculated by date2 - date1.

If cal_date2 is larger (= later) than cal_date1 the result is positive.

If cal_date2 is smaller (= earlier) than cal_date1 the result is negative.

Examples

  iex>Elixir.Astronomical.date_diff(730739, 730839)
  100
  iex>Elixir.Astronomical.date_diff(730839, 730739)
  -100
  iex>Elixir.Astronomical.date_diff({2001, 9, 11}, {2001, 12, 20})
  100
  iex>Elixir.Astronomical.date_diff({2001, 12, 20}, {2001, 9, 11})
  -100
  iex>Elixir.Astronomical.date_diff(730739, {2001, 12, 20})
  100
  iex>Elixir.Astronomical.date_diff({2001, 9, 11}, 730839)
  100

day(cal_date, type \\ :value)

Specs

day(fixed() | astronomical_date(), :atom | :index | :name | :value) ::
  :atom | integer() | String.t() | number()

Returns the day field of a Astronomical date.

The type parameter determines the type of the returned day:

:atom returns the internal name of day,
:index returns the position of the day field within the date,
:name returns the common name of the day,
:value returns the value of the day (default).

Examples

  iex>Elixir.Astronomical.day(730739)
  11
  iex>Elixir.Astronomical.day(730739, :atom)
  :day
  iex>Elixir.Astronomical.day(730739, :index)
  2
  iex>Elixir.Astronomical.day(730739, :name)
  "Day"
  iex>Elixir.Astronomical.day(730739, :value)
  11

  iex>Elixir.Astronomical.day({2001, 9, 11})
  11
  iex>Elixir.Astronomical.day({2001, 9, 11}, :atom)
  :day
  iex>Elixir.Astronomical.day({2001, 9, 11}, :index)
  2
  iex>Elixir.Astronomical.day({2001, 9, 11}, :name)
  "Day"
  iex>Elixir.Astronomical.day({2001, 9, 11}, :value)
  11

epoch()

Specs

epoch() :: number()

Returns the epoch of the Astronomical calendar.

Example

  iex>Elixir.Astronomical.epoch()
  1

eq(date1, date2)

Specs

eq(astronomical_date(), astronomical_date()) :: boolean()

Returns true if Astronomical date1 is equal Astronomical date2, otherwise false.

Examples

  iex>Elixir.Astronomical.eq({2001, 9, 11}, {2001, 9, 11})
  true
  iex>Elixir.Astronomical.eq({2001, 9, 11}, {2001, 12, 20})
  false
  iex>Elixir.Astronomical.eq({2001, 12, 20}, {2001, 9, 11})
  false

field_atom(field_index)

Specs

field_atom(integer()) :: atom()

Returns the name of the field atom in a Astronomical date at field_index.

Examples

  iex>Elixir.Astronomical.field_atom(0)
  :year
  iex>Elixir.Astronomical.field_atom(1)
  :month
  iex>Elixir.Astronomical.field_atom(2)
  :day

field_atoms()

Specs

field_atoms() :: [atom()]

Returns a list of the field atoms (names) of a Astronomical date.

Example

  iex>Elixir.Astronomical.field_atoms()
  [:year, :month, :day]

field_count()

Specs

field_count() :: integer()

Returns the number of fields in a Astronomical date

Example

  iex>Elixir.Astronomical.field_count()
  3

field_index(field_atom)

Specs

field_index(atom()) :: integer()

Returns the index (= position) of the field_atom in a Astronomical date.

Examples

  iex>Elixir.Astronomical.field_index(:year)
  0
  iex>Elixir.Astronomical.field_index(:month)
  1
  iex>Elixir.Astronomical.field_index(:day)
  2

from_date(other_date, other_calendar)

Specs

from_date(tuple(), module()) :: astronomical_date()

from_date(tuple(), module()) :: {:error, String.t()}

Converts the other_date of the other_calendar into the equivalent date of the Astronomical calendar.

Example

  iex>Elixir.Astronomical.from_date({2001, 9, 11}, Gregorian)
  {2001, 9, 11}

from_fixed(fixed)

Specs

from_fixed(fixed()) :: astronomical_date()

Converts a fixed day to a Astronomical date.

Example

  iex>Elixir.Astronomical.from_fixed(730739)
  {2001, 9, 11}

from_jd(day)

Specs

from_jd(tuple() | number()) :: astronomical_date()

Converts a Julian Day into the equivalent Astronomical date.

The Julian Day can be given as a tuple or by a Julian day.

Examples

  iex>Elixir.Astronomical.from_jd({2452163.5})
  {2001, 9, 11}
  iex>Elixir.Astronomical.from_jd(2452163.5)
  {2001, 9, 11}

from_rata_die(rd)

Specs

from_rata_die(tuple() | integer()) :: astronomical_date()

Converts a RataDie date into the equivalent Astronomical date.

The RataDie date can be given as a tuple or by a RataDie rd.

Examples

  iex>Elixir.Astronomical.from_rata_die({730739})
  {2001, 9, 11}
  iex>Elixir.Astronomical.from_rata_die(730739)
  {2001, 9, 11}

from_unix(unix_date)

Specs

from_unix(tuple() | integer()) :: astronomical_date()

Converts a Unix date into the equivalent Astronomical date.

The Unix date can be given as a tuple or by Unix seconds.

Examples

  iex>Elixir.Astronomical.from_unix({1000166400})
  {2001, 9, 11}
  iex>Elixir.Astronomical.from_unix(1000166400)
  {2001, 9, 11}

ge(date1, date2)

Specs

ge(astronomical_date(), astronomical_date()) :: boolean()

Returns true if Astronomical date1 is greater (= later) than or equal Astronomical date2, otherwise false.

Examples

  iex>Elixir.Astronomical.ge({2001, 9, 11}, {2001, 9, 11})
  true
  iex>Elixir.Astronomical.ge({2001, 9, 11}, {2001, 12, 20})
  false
  iex>Elixir.Astronomical.ge({2001, 12, 20}, {2001, 9, 11})
  true

gt(date1, date2)

Specs

gt(astronomical_date(), astronomical_date()) :: boolean()

Returns true if Astronomical date1 is greater (= later) than Astronomical date2, otherwise false.

Examples

  iex>Elixir.Astronomical.gt({2001, 9, 11}, {2001, 9, 11})
  false
  iex>Elixir.Astronomical.gt({2001, 9, 11}, {2001, 12, 20})
  false
  iex>Elixir.Astronomical.gt({2001, 12, 20}, {2001, 9, 11})
  true

keyword()

Specs

keyword() :: atom()

Returns the internal keyword of the Astronomical calendar.

Example

  iex>Elixir.Astronomical.keyword()
  :astronomical

le(date1, date2)

Specs

le(astronomical_date(), astronomical_date()) :: boolean()

Returns true if Astronomical date1 is smaller (= earlier) than or equal Astronomical date2, otherwise false.

Examples

  iex>Elixir.Astronomical.le({2001, 9, 11}, {2001, 9, 11})
  true
  iex>Elixir.Astronomical.le({2001, 9, 11}, {2001, 12, 20})
  true
  iex>Elixir.Astronomical.le({2001, 12, 20}, {2001, 9, 11})
  false

leap_year?(year)

Specs

leap_year?(astronomical_year()) :: boolean()

Returns true if the Astronomical year is a leap year, otherwise false.

Examples

  iex>Elixir.Astronomical.leap_year?(2000)
  true
  iex>Elixir.Astronomical.leap_year?(2001)
  false
  iex>Elixir.Astronomical.leap_year?(2002)
  false
  iex>Elixir.Astronomical.leap_year?(2003)
  false

lt(date1, date2)

Specs

lt(astronomical_date(), astronomical_date()) :: boolean()

Returns true if Astronomical date1 is smaller (= earlier) than Astronomical date2, otherwise false.

Examples

  iex>Elixir.Astronomical.lt({2001, 9, 11}, {2001, 9, 11})
  false
  iex>Elixir.Astronomical.lt({2001, 9, 11}, {2001, 12, 20})
  true
  iex>Elixir.Astronomical.lt({2001, 12, 20}, {2001, 9, 11})
  false

module()

Specs

module() :: module()

Returns the module of the Astronomical calendar.

Example

  iex>Elixir.Astronomical.module()
  Astronomical

month(cal_date, type \\ :value)

Specs

month(fixed() | astronomical_date(), :atom | :index | :name | :value) ::
  :atom | integer() | String.t() | number()

Returns the month field of a Astronomical date.

The type parameter determines the type of the returned month:

:atom returns the internal name of month,
:index returns the position of the month field within the date,
:name returns the common name of the month,
:value returns the value of the month (default).

Examples

  iex>Elixir.Astronomical.month(730739)
  9
  iex>Elixir.Astronomical.month(730739, :atom)
  :month
  iex>Elixir.Astronomical.month(730739, :index)
  1
  iex>Elixir.Astronomical.month(730739, :name)
  "Month"
  iex>Elixir.Astronomical.month(730739, :value)
  9

  iex>Elixir.Astronomical.month({2001, 9, 11})
  9
  iex>Elixir.Astronomical.month({2001, 9, 11}, :atom)
  :month
  iex>Elixir.Astronomical.month({2001, 9, 11}, :index)
  1
  iex>Elixir.Astronomical.month({2001, 9, 11}, :name)
  "Month"
  iex>Elixir.Astronomical.month({2001, 9, 11}, :value)
  9

name()

Specs

name() :: atom()

Returns the internal name of the Astronomical calendar.

Example

  iex>Elixir.Astronomical.name()
  "Astronomical"

range(date1, date2)

Specs

range(astronomical_date(), astronomical_date()) :: integer()

Returns the distance between two Astronomical dates as a range of fixed days.

Example

  iex>Elixir.Astronomical.range({2001, 9, 11}, {2001, 12, 20})
  730739..730839

start_of_day()

Specs

start_of_day() :: :midnight | :sunset | :sunrise | :noon

Returns the start of the day in the Astronomical calendar.

Possible return values are:

:midnight,
:noon,
:sunrise,
:sunset,

Example

  iex>Elixir.Astronomical.start_of_day()
  :midnight

switch_over()

Specs

switch_over() :: fixed()

Returns the switch over date from the Julian to the Gregorian calendar as a fixed day.

Example

iex>Elixir.Astronomical.switch_over()
577736

to_date(date, other_calendar)

Specs

to_date(astronomical_date(), module()) :: tuple()

Converts a Astronomical date into the equivalent date of the other_calendar.

For the following example to work the Gregorian calendar must be available.

Example

  iex>Elixir.Astronomical.to_date({2001, 9, 11}, Gregorian)
  {2001, 9, 11}

to_fixed(date)

Specs

to_fixed(astronomical_date()) :: fixed()

Converts a Astronomical date tuple into a fixed day.

Example

  iex>Elixir.Astronomical.to_fixed({2001, 9, 11})
  730739

to_fixed(year, month, day)

Specs

to_fixed(astronomical_year(), astronomical_month(), astronomical_day()) ::
  fixed()

Converts a Astronomical date given by year, month, day into a fixed day.

Example

  iex>Elixir.Astronomical.to_fixed(2001, 9, 11)
  730739

to_jd(cal_date)

Specs

to_jd(astronomical_date()) :: {number()}

Converts a Astronomical date into the equivalent Julian Day.

Example

  iex>Elixir.Astronomical.to_jd({2001, 9, 11})
  {2452163.5}

to_jd(year, month, day)

Specs

to_jd(astronomical_year(), astronomical_month(), astronomical_day()) ::
  {number()}

Converts a Astronomical date given by year, month, day into the equivalent Julian Day.

Example

  iex>Elixir.Astronomical.to_jd(2001, 9, 11)
  {2452163.5}

to_rata_die(date)

Specs

to_rata_die(astronomical_date()) :: {integer()}

Converts a Astronomical date into the equivalent RataDie date.

Example

  iex>Elixir.Astronomical.to_rata_die({2001, 9, 11})
  {730739}

to_rata_die(year, month, day)

Specs

to_rata_die(astronomical_year(), astronomical_month(), astronomical_day()) ::
  {integer()}

Converts a Astronomical date given by year, month, day into the equivalent RataDie date.

Example

  iex>Elixir.Astronomical.to_rata_die(2001, 9, 11)
  {730739}

to_unix(cal_date)

Specs

to_unix(astronomical_date()) :: {integer()}

Converts a Astronomical date into the equivalent Unix date.

Example

  iex>Elixir.Astronomical.to_unix({2001, 9, 11})
  {1000166400}

to_unix(year, month, day)

Specs

to_unix(astronomical_year(), astronomical_month(), astronomical_day()) ::
  {integer()}

Converts a Astronomical date given by year, month, day into the equivalent Unix date.

Example

  iex>Elixir.Astronomical.to_unix(2001, 9, 11)
  {1000166400}

today(type \\ :fixed)

Specs

today(:fixed | :date) :: fixed() | astronomical_date()

Returns the current date either as a fixed day or a Astronomical date.

(This cannot be doctested, because today is a moving target.)

The type parameter determines the type of the returned value:

:fixed returns a fixed day (default),
:date returns a Astronomical date.

Examples

  Elixir.Astronomical.today()
  730739
  Elixir.Astronomical.today(:fixed)
  730739
  Elixir.Astronomical.today(:date)
  {2001, 9, 11}

year(cal_date, type \\ :value)

Specs

year(fixed() | astronomical_date(), :atom | :index | :name | :value) ::
  :atom | integer() | String.t() | number()

Returns the year field of a Astronomical date.

The type parameter determines the type of the returned year:

:atom returns the internal name of year,
:index returns the position of the year field within the date,
:name returns the common name of the year,
:value returns the value of the year (default).

Examples

  iex>Elixir.Astronomical.year(730739)
  2001
  iex>Elixir.Astronomical.year(730739, :atom)
  :year
  iex>Elixir.Astronomical.year(730739, :index)
  0
  iex>Elixir.Astronomical.year(730739, :name)
  "Year"
  iex>Elixir.Astronomical.year(730739, :value)
  2001

  iex>Elixir.Astronomical.year({2001, 9, 11})
  2001
  iex>Elixir.Astronomical.year({2001, 9, 11}, :atom)
  :year
  iex>Elixir.Astronomical.year({2001, 9, 11}, :index)
  0
  iex>Elixir.Astronomical.year({2001, 9, 11}, :name)
  "Year"
  iex>Elixir.Astronomical.year({2001, 9, 11}, :value)
  2001