Month (Month v2.2.0)

A data structure and a set of methods for those who work exclusively with months and month ranges.

Please check the documentation for Month as well as Month.Period and Month.Range, which cover some extra use cases.

Using the ~M sigil

To use the ~M sigil, please import Month.Sigils like so:

defmodule SomeModule do
  import Month.Sigils
  # ...
end

Then you can do

date = ~M[2000-01]

Examples

iex> ~M[2019-03].month
3

iex> ~M[2019-03].year
2019

iex> range = Month.Range.new!(~M[2019-01], ~M[2019-03])
#Month.Range<~M[2019-01], ~M[2019-03]>

iex> range.months
[~M[2019-01], ~M[2019-02], ~M[2019-03]]

Summary

Types

t()

Functions

add(month, num_months)

Adds or subtracts months from given month.

add!(month, num_months)

Same as add/2 but returns result or throws.

compare(a, b)

Compares two months and returns if first one is greater (after), equal or less (before) the second one.

dates(date)

Returns list of dates in a month.

new(map)

Creates a new Month struct, using a map that has year and month fields. Intended to be used with Date or DateTime structs.

new(year, month)

Creates a new Month struct using given year and month.

new!(map)

Sames as new/1 but returns result or throws.

new!(year, month)

Sames as new/2 but returns result or throws.

now(tz)

Returns a %Month{} representing current month, according to the given timezone.

now!(tz)

Same as now/1 but returns result directly or throws.

subtract(month, num_months)

Subtracts the given positive number of months from the month.

subtract!(month, num_months)

Same as subtract/2 but either returns result or throws.

to_string(map)

Converts given %Month{} to a string.

utc_now()

Returns a %Month{} representing current month, according to the Etc/UTC timezone.

utc_now!()

Same as utc_now/0 but returns result directly or throws.

Types

t()

@type t() :: %Month{
  first_date: Date.t(),
  last_date: Date.t(),
  month: integer(),
  year: integer()
}

Functions

add(month, num_months)

@spec add(t(), integer()) :: {:ok, t()} | {:error, String.t()}

Adds or subtracts months from given month.

You can pass a negative number of months to subtract.

Examples

iex> {:ok, month} = Month.new(2019, 3)
{:ok, ~M[2019-03]}

iex> Month.add(month, 3)
{:ok, ~M[2019-06]}

add!(month, num_months)

@spec add!(t(), integer()) :: t()

Same as add/2 but returns result or throws.

compare(a, b)

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

Compares two months and returns if first one is greater (after), equal or less (before) the second one.

Examples

iex> Month.compare(~M[2020-03], ~M[2019-12])
:gt

dates(date)

@spec dates(Date.t()) :: [Date.t()]

@spec dates(t()) :: [Date.t()]

Returns list of dates in a month.

Examples

iex> Month.dates(~M[2019-02])
[~D[2019-02-01], ~D[2019-02-02], ~D[2019-02-03], ~D[2019-02-04], ~D[2019-02-05],
 ~D[2019-02-06], ~D[2019-02-07], ~D[2019-02-08], ~D[2019-02-09], ~D[2019-02-10],
 ~D[2019-02-11], ~D[2019-02-12], ~D[2019-02-13], ~D[2019-02-14], ~D[2019-02-15],
 ~D[2019-02-16], ~D[2019-02-17], ~D[2019-02-18], ~D[2019-02-19], ~D[2019-02-20],
 ~D[2019-02-21], ~D[2019-02-22], ~D[2019-02-23], ~D[2019-02-24], ~D[2019-02-25],
 ~D[2019-02-26], ~D[2019-02-27], ~D[2019-02-28]]

new(map)

@spec new(map()) :: {:ok, t()} | {:error, String.t()}

Creates a new Month struct, using a map that has year and month fields. Intended to be used with Date or DateTime structs.

Examples

iex> Month.new(Date.utc_today())
{:ok, ~M[2019-03]}

iex> Month.new(DateTime.utc_now())
{:ok, ~M[2019-03]}

iex> Month.new(%{year: 2019, month: 3})
{:ok, ~M[2019-03]}

new(year, month)

@spec new(integer(), integer()) :: {:ok, t()} | {:error, String.t()}

Creates a new Month struct using given year and month.

Examples

iex> Month.new(2019, 3)
{:ok, ~M[2019-03]}

new!(map)

@spec new!(map()) :: t()

Sames as new/1 but returns result or throws.

new!(year, month)

@spec new!(integer(), integer()) :: t()

Sames as new/2 but returns result or throws.

now(tz)

Returns a %Month{} representing current month, according to the given timezone.

This requires Elixir 1.8+ and a configured timezone database (such as tzdata).

Examples

iex> Month.now("America/New_York")
{:ok, ~M[2019-03]}

now!(tz)

Same as now/1 but returns result directly or throws.

subtract(month, num_months)

Subtracts the given positive number of months from the month.

Same as add/2 when you give it a negative number of months.

Examples

iex> Month.subtract(~M[2019-03], 3)
{:ok, ~M[2018-12]}

subtract!(month, num_months)

@spec subtract!(t(), integer()) :: t()

Same as subtract/2 but either returns result or throws.

to_string(map)

Converts given %Month{} to a string.

Examples

iex> Month.to_string(~M[2019-03])
"2019-03"

utc_now()

Returns a %Month{} representing current month, according to the Etc/UTC timezone.

utc_now!()

Same as utc_now/0 but returns result directly or throws.