Month

v2.1.0

Month v2.1.0 Month View Source

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]]

Link to this section 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 either year/month or another struct that has year and month fields, such as Date or DateTime

new(year, month)
new!(map)

Sames as new/2 but returns result or throws

new!(year, month)
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

Link to this section Types

Link to this type

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

Link to this section Functions

Link to this function

add(month, num_months) View Source 
add(Month.t(), integer()) :: {:ok, Month.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]}
Link to this function

add!(month, num_months) View Source 
add!(Month.t(), integer()) :: Month.t()

Same as add/2 but returns result or throws.

Link to this function

compare(a, b) View Source 
compare(Month.t(), Month.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
Link to this function

dates(date) View Source 
dates(Date.t()) :: [Date.t()]
dates(Month.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]]
Link to this function

new(map) View Source 
new(map()) :: {:ok, Month.t()} | {:error, String.t()}

Creates a new Month struct, using either year/month or another struct that has year and month fields, such as Date or DateTime.

Link to this function

new(year, month) View Source 
new(integer(), integer()) :: {:ok, Month.t()} | {:error, String.t()}

Link to this function

new!(map) View Source 
new!(map()) :: Month.t()

Sames as new/2 but returns result or throws.

Link to this function

new!(year, month) View Source 
new!(integer(), integer()) :: Month.t()

Link to this function

now(tz) View Source

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]}
Link to this function

now!(tz) View Source

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

Link to this function

subtract(month, num_months) View Source

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]}
Link to this function

subtract!(month, num_months) View Source 
subtract!(Month.t(), integer()) :: Month.t()

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

Link to this function

to_string(map) View Source

Converts given %Month{} to a string.

Examples 

iex> Month.to_string(~M[2019-03])
"2019-03"
Link to this function

utc_now() View Source

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

Link to this function

utc_now!() View Source

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