@type bce() :: 0

"Before the Current Era" or "Before the Common Era" (BCE), for those years less than1.

@type ce() :: 1

The "Current Era" or the "Common Era" (CE) which starts in year1.

@type day_of_week() :: 1..7

Integer that represents the day of the week, where 1 is Monday and 7 is Sunday.

@type era() ::bce() |ce()

The calendar era.

The ISO calendar has two eras:

• CE - which starts in year1 and is defined as era1.
• BCE - for those years less than1 and is defined as era0.

@type microsecond() :: {0..999_999, 0..6}

Microseconds with stored precision.

The precision represents the number of digits that must be used whenrepresenting the microseconds to external format. If the precision is 0,it means microseconds must be skipped.

@spec date_to_string(year(),month(),day(), :basic | :extended) ::String.t()

Converts the given date into a string.

By default, returns dates formatted in the "extended" format,for human readability. It also supports the "basic" formatby passing the:basic option.

Examples

iex>Calendar.ISO.date_to_string(2015,2,28)"2015-02-28"iex>Calendar.ISO.date_to_string(2017,8,1)"2017-08-01"iex>Calendar.ISO.date_to_string(-99,1,31)"-0099-01-31"iex>Calendar.ISO.date_to_string(2015,2,28,:basic)"20150228"iex>Calendar.ISO.date_to_string(-99,1,31,:basic)"-00990131"

@spec datetime_to_string(year(),month(),day(),Calendar.hour(),Calendar.minute(),Calendar.second(),Calendar.microsecond(),Calendar.time_zone(),Calendar.zone_abbr(),Calendar.utc_offset(),Calendar.std_offset(),  :basic | :extended) ::String.t()

Converts the datetime (with time zone) into a string.

By default, returns datetimes formatted in the "extended" format,for human readability. It also supports the "basic" formatby passing the:basic option.

Examples

iex>time_zone="Etc/UTC"iex>Calendar.ISO.datetime_to_string(2017,8,1,1,2,3,{4,5},time_zone,"UTC",0,0)"2017-08-01 01:02:03.00000Z"iex>Calendar.ISO.datetime_to_string(2017,8,1,1,2,3,{4,5},time_zone,"UTC",3600,0)"2017-08-01 01:02:03.00000+01:00"iex>Calendar.ISO.datetime_to_string(2017,8,1,1,2,3,{4,5},time_zone,"UTC",3600,3600)"2017-08-01 01:02:03.00000+02:00"iex>time_zone="Europe/Berlin"iex>Calendar.ISO.datetime_to_string(2017,8,1,1,2,3,{4,5},time_zone,"CET",3600,0)"2017-08-01 01:02:03.00000+01:00 CET Europe/Berlin"iex>Calendar.ISO.datetime_to_string(2017,8,1,1,2,3,{4,5},time_zone,"CDT",3600,3600)"2017-08-01 01:02:03.00000+02:00 CDT Europe/Berlin"iex>time_zone="America/Los_Angeles"iex>Calendar.ISO.datetime_to_string(2015,2,28,1,2,3,{4,5},time_zone,"PST",-28800,0)"2015-02-28 01:02:03.00000-08:00 PST America/Los_Angeles"iex>Calendar.ISO.datetime_to_string(2015,2,28,1,2,3,{4,5},time_zone,"PDT",-28800,3600)"2015-02-28 01:02:03.00000-07:00 PDT America/Los_Angeles"iex>time_zone="Europe/Berlin"iex>Calendar.ISO.datetime_to_string(2017,8,1,1,2,3,{4,5},time_zone,"CET",3600,0,:basic)"20170801 010203.00000+0100 CET Europe/Berlin"

@spec day_of_era(year(),month(),day()) ::Calendar.day_of_era()

Calculates the day and era from the givenyear,month, andday.

Examples

iex>Calendar.ISO.day_of_era(0,1,1){366,0}iex>Calendar.ISO.day_of_era(1,1,1){1,1}iex>Calendar.ISO.day_of_era(0,12,31){1,0}iex>Calendar.ISO.day_of_era(0,12,30){2,0}iex>Calendar.ISO.day_of_era(-1,12,31){367,0}

@spec day_of_week(year(),month(),day(), :default |weekday()) ::  {day_of_week(), 1, 7}

Calculates the day of the week from the givenyear,month, andday.

It is an integer from 1 to 7, where 1 is the givenstarting_on weekday.For example, ifstarting_on is set to:monday, then 1 is Monday and7 is Sunday.

starting_on can also be:default, which is equivalent to:monday.

Examples

iex>Calendar.ISO.day_of_week(2016,10,31,:monday){1,1,7}iex>Calendar.ISO.day_of_week(2016,11,1,:monday){2,1,7}iex>Calendar.ISO.day_of_week(2016,11,2,:monday){3,1,7}iex>Calendar.ISO.day_of_week(2016,11,3,:monday){4,1,7}iex>Calendar.ISO.day_of_week(2016,11,4,:monday){5,1,7}iex>Calendar.ISO.day_of_week(2016,11,5,:monday){6,1,7}iex>Calendar.ISO.day_of_week(2016,11,6,:monday){7,1,7}iex>Calendar.ISO.day_of_week(-99,1,31,:monday){4,1,7}iex>Calendar.ISO.day_of_week(2016,10,31,:sunday){2,1,7}iex>Calendar.ISO.day_of_week(2016,11,1,:sunday){3,1,7}iex>Calendar.ISO.day_of_week(2016,11,2,:sunday){4,1,7}iex>Calendar.ISO.day_of_week(2016,11,3,:sunday){5,1,7}iex>Calendar.ISO.day_of_week(2016,11,4,:sunday){6,1,7}iex>Calendar.ISO.day_of_week(2016,11,5,:sunday){7,1,7}iex>Calendar.ISO.day_of_week(2016,11,6,:sunday){1,1,7}iex>Calendar.ISO.day_of_week(-99,1,31,:sunday){5,1,7}iex>Calendar.ISO.day_of_week(2016,10,31,:saturday){3,1,7}

@spec day_of_year(year(),month(),day()) ::day_of_year()

Calculates the day of the year from the givenyear,month, andday.

It is an integer from 1 to 366.

Examples

iex>Calendar.ISO.day_of_year(2016,1,31)31iex>Calendar.ISO.day_of_year(-99,2,1)32iex>Calendar.ISO.day_of_year(2018,2,28)59

@spec day_rollover_relative_to_midnight_utc() :: {0, 1}

SeeCalendar.day_rollover_relative_to_midnight_utc/0 for documentation.

@spec days_in_month(year(),month()) :: 28..31

Returns how many days there are in the given year-month.

Examples

iex>Calendar.ISO.days_in_month(1900,1)31iex>Calendar.ISO.days_in_month(1900,2)28iex>Calendar.ISO.days_in_month(2000,2)29iex>Calendar.ISO.days_in_month(2001,2)28iex>Calendar.ISO.days_in_month(2004,2)29iex>Calendar.ISO.days_in_month(2004,4)30iex>Calendar.ISO.days_in_month(-1,5)31

@spec iso_days_to_beginning_of_day(Calendar.iso_days()) ::Calendar.iso_days()

Converts theCalendar.iso_days/0 to the first moment of the day.

Examples

iex>Calendar.ISO.iso_days_to_beginning_of_day({0,{0,86400000000}}){0,{0,86400000000}}iex>Calendar.ISO.iso_days_to_beginning_of_day({730485,{43200000000,86400000000}}){730485,{0,86400000000}}iex>Calendar.ISO.iso_days_to_beginning_of_day({730485,{46800000000,86400000000}}){730485,{0,86400000000}}

@spec iso_days_to_end_of_day(Calendar.iso_days()) ::Calendar.iso_days()

Converts theCalendar.iso_days/0 to the last moment of the day.

Examples

iex>Calendar.ISO.iso_days_to_end_of_day({0,{0,86400000000}}){0,{86399999999,86400000000}}iex>Calendar.ISO.iso_days_to_end_of_day({730485,{43200000000,86400000000}}){730485,{86399999999,86400000000}}iex>Calendar.ISO.iso_days_to_end_of_day({730485,{46800000000,86400000000}}){730485,{86399999999,86400000000}}

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

Returns if the given year is a leap year.

Examples

iex>Calendar.ISO.leap_year?(2000)trueiex>Calendar.ISO.leap_year?(2001)falseiex>Calendar.ISO.leap_year?(2004)trueiex>Calendar.ISO.leap_year?(1900)falseiex>Calendar.ISO.leap_year?(-4)true

@spec months_in_year(year()) :: 12

Returns how many months there are in the given year.

Example

iex>Calendar.ISO.months_in_year(2004)12

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

Converts theCalendar.iso_days/0 format to the datetime format specified by this calendar.

Examples

iex>Calendar.ISO.naive_datetime_from_iso_days({0,{0,86400}}){0,1,1,0,0,0,{0,6}}iex>Calendar.ISO.naive_datetime_from_iso_days({730_485,{0,86400}}){2000,1,1,0,0,0,{0,6}}iex>Calendar.ISO.naive_datetime_from_iso_days({730_485,{43200,86400}}){2000,1,1,12,0,0,{0,6}}iex>Calendar.ISO.naive_datetime_from_iso_days({-365,{0,86400000000}}){-1,1,1,0,0,0,{0,6}}

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

Returns theCalendar.iso_days/0 format of the specified date.

Examples

iex>Calendar.ISO.naive_datetime_to_iso_days(0,1,1,0,0,0,{0,6}){0,{0,86400000000}}iex>Calendar.ISO.naive_datetime_to_iso_days(2000,1,1,12,0,0,{0,6}){730485,{43200000000,86400000000}}iex>Calendar.ISO.naive_datetime_to_iso_days(2000,1,1,13,0,0,{0,6}){730485,{46800000000,86400000000}}iex>Calendar.ISO.naive_datetime_to_iso_days(-1,1,1,0,0,0,{0,6}){-365,{0,86400000000}}

@spec naive_datetime_to_string(year(),month(),day(),Calendar.hour(),Calendar.minute(),Calendar.second(),Calendar.microsecond(),  :basic | :extended) ::String.t()

Converts the datetime (without time zone) into a string.

By default, returns datetimes formatted in the "extended" format,for human readability. It also supports the "basic" formatby passing the:basic option.

Examples

iex>Calendar.ISO.naive_datetime_to_string(2015,2,28,1,2,3,{4,6})"2015-02-28 01:02:03.000004"iex>Calendar.ISO.naive_datetime_to_string(2017,8,1,1,2,3,{4,5})"2017-08-01 01:02:03.00000"iex>Calendar.ISO.naive_datetime_to_string(2015,2,28,1,2,3,{4,6},:basic)"20150228 010203.000004"

@spec parse_date(String.t()) :: {:ok, {year(),month(),day()}} | {:error,atom()}

Parses a datestring in the:extended format.

For more information on supported strings, see how thismodule implementsISO 8601.

Examples

iex>Calendar.ISO.parse_date("2015-01-23"){:ok,{2015,1,23}}iex>Calendar.ISO.parse_date("2015:01:23"){:error,:invalid_format}iex>Calendar.ISO.parse_date("2015-01-32"){:error,:invalid_date}

@spec parse_date(String.t(),format()) ::  {:ok, {year(),month(),day()}} | {:error,atom()}

Parses a datestring according to a givenformat.

Theformat can either be:basic or:extended.

For more information on supported strings, see how thismodule implementsISO 8601.

Examples

iex>Calendar.ISO.parse_date("20150123",:basic){:ok,{2015,1,23}}iex>Calendar.ISO.parse_date("20150123",:extended){:error,:invalid_format}

@spec parse_duration(String.t()) :: {:ok, [Duration.unit_pair()]} | {:error,atom()}

Parses an ISO 8601 formatted duration string to a list ofDuration compabitble unit pairs.

SeeDuration.from_iso8601/1.

@spec parse_naive_datetime(String.t()) ::  {:ok, {year(),month(),day(),hour(),minute(),second(),microsecond()}}  | {:error,atom()}

Parses a naive datetimestring in the:extended format.

For more information on supported strings, see how thismodule implementsISO 8601.

Examples

iex>Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07"){:ok,{2015,1,23,23,50,7,{0,0}}}iex>Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07Z"){:ok,{2015,1,23,23,50,7,{0,0}}}iex>Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07-02:30"){:ok,{2015,1,23,23,50,7,{0,0}}}iex>Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07.0"){:ok,{2015,1,23,23,50,7,{0,1}}}iex>Calendar.ISO.parse_naive_datetime("2015-01-23 23:50:07,0123456"){:ok,{2015,1,23,23,50,7,{12345,6}}}

@spec parse_naive_datetime(String.t(),format()) ::  {:ok, {year(),month(),day(),hour(),minute(),second(),microsecond()}}  | {:error,atom()}

Parses a naive datetimestring according to a givenformat.

Theformat can either be:basic or:extended.

For more information on supported strings, see how thismodule implementsISO 8601.

Examples

iex>Calendar.ISO.parse_naive_datetime("20150123 235007",:basic){:ok,{2015,1,23,23,50,7,{0,0}}}iex>Calendar.ISO.parse_naive_datetime("20150123 235007",:extended){:error,:invalid_format}

@spec parse_time(String.t()) ::  {:ok, {hour(),minute(),second(),microsecond()}} | {:error,atom()}

Parses a timestring in the:extended format.

For more information on supported strings, see how thismodule implementsISO 8601.

Examples

iex>Calendar.ISO.parse_time("23:50:07"){:ok,{23,50,7,{0,0}}}iex>Calendar.ISO.parse_time("23:50:07Z"){:ok,{23,50,7,{0,0}}}iex>Calendar.ISO.parse_time("T23:50:07Z"){:ok,{23,50,7,{0,0}}}

@spec parse_time(String.t(),format()) ::  {:ok, {hour(),minute(),second(),microsecond()}} | {:error,atom()}

Parses a timestring according to a givenformat.

Theformat can either be:basic or:extended.

For more information on supported strings, see how thismodule implementsISO 8601.

Examples

iex>Calendar.ISO.parse_time("235007",:basic){:ok,{23,50,7,{0,0}}}iex>Calendar.ISO.parse_time("235007",:extended){:error,:invalid_format}

@spec parse_utc_datetime(String.t()) ::  {:ok, {year(),month(),day(),hour(),minute(),second(),microsecond()},utc_offset()}  | {:error,atom()}

Parses a UTC datetimestring in the:extended format.

For more information on supported strings, see how thismodule implementsISO 8601.

Examples

iex>Calendar.ISO.parse_utc_datetime("2015-01-23 23:50:07Z"){:ok,{2015,1,23,23,50,7,{0,0}},0}iex>Calendar.ISO.parse_utc_datetime("2015-01-23 23:50:07+02:30"){:ok,{2015,1,23,21,20,7,{0,0}},9000}iex>Calendar.ISO.parse_utc_datetime("2015-01-23 23:50:07"){:error,:missing_offset}

@spec parse_utc_datetime(String.t(),format()) ::  {:ok, {year(),month(),day(),hour(),minute(),second(),microsecond()},utc_offset()}  | {:error,atom()}

Parses a UTC datetimestring according to a givenformat.

Theformat can either be:basic or:extended.

For more information on supported strings, see how thismodule implementsISO 8601.

Examples

iex>Calendar.ISO.parse_utc_datetime("20150123 235007Z",:basic){:ok,{2015,1,23,23,50,7,{0,0}},0}iex>Calendar.ISO.parse_utc_datetime("20150123 235007Z",:extended){:error,:invalid_format}

@spec quarter_of_year(year(),month(),day()) ::quarter_of_year()

Calculates the quarter of the year from the givenyear,month, andday.

It is an integer from 1 to 4.

Examples

iex>Calendar.ISO.quarter_of_year(2016,1,31)1iex>Calendar.ISO.quarter_of_year(2016,4,3)2iex>Calendar.ISO.quarter_of_year(-99,9,31)3iex>Calendar.ISO.quarter_of_year(2018,12,28)4

@spec shift_date(year(),month(),day(),Duration.t()) :: {year(),month(),day()}

Shifts Date by Duration according to its calendar.

Examples

iex>Calendar.ISO.shift_date(2016,1,3,Duration.new!(month:2)){2016,3,3}iex>Calendar.ISO.shift_date(2016,2,29,Duration.new!(month:1)){2016,3,29}iex>Calendar.ISO.shift_date(2016,1,31,Duration.new!(month:1)){2016,2,29}iex>Calendar.ISO.shift_date(2016,1,31,Duration.new!(year:4,day:1)){2020,2,1}

@spec shift_naive_datetime(year(),month(),day(),hour(),minute(),second(),microsecond(),Duration.t()) :: {year(),month(),day(),hour(),minute(),second(),microsecond()}

Shifts NaiveDateTime by Duration according to its calendar.

Examples

iex>Calendar.ISO.shift_naive_datetime(2016,1,3,0,0,0,{0,0},Duration.new!(hour:1)){2016,1,3,1,0,0,{0,0}}iex>Calendar.ISO.shift_naive_datetime(2016,1,3,0,0,0,{0,0},Duration.new!(hour:30)){2016,1,4,6,0,0,{0,0}}iex>Calendar.ISO.shift_naive_datetime(2016,1,3,0,0,0,{0,0},Duration.new!(microsecond:{100,6})){2016,1,3,0,0,0,{100,6}}

@spec shift_time(hour(),minute(),second(),microsecond(),Duration.t()) ::  {hour(),minute(),second(),microsecond()}

Shifts Time by Duration units according to its calendar.

Examples

iex>Calendar.ISO.shift_time(13,0,0,{0,0},Duration.new!(hour:2)){15,0,0,{0,0}}iex>Calendar.ISO.shift_time(13,0,0,{0,0},Duration.new!(microsecond:{100,6})){13,0,0,{100,6}}

@spec time_from_day_fraction(Calendar.day_fraction()) ::  {hour(),minute(),second(),microsecond()}

Converts a day fraction to this Calendar's representation of time.

Examples

iex>Calendar.ISO.time_from_day_fraction({1,2}){12,0,0,{0,6}}iex>Calendar.ISO.time_from_day_fraction({13,24}){13,0,0,{0,6}}

@spec time_to_day_fraction(Calendar.hour(),Calendar.minute(),Calendar.second(),Calendar.microsecond()) ::Calendar.day_fraction()

Returns the normalized day fraction of the specified time.

Examples

iex>Calendar.ISO.time_to_day_fraction(0,0,0,{0,6}){0,86400000000}iex>Calendar.ISO.time_to_day_fraction(12,34,56,{123,6}){45296000123,86400000000}

@spec time_to_string(Calendar.hour(),Calendar.minute(),Calendar.second(),Calendar.microsecond(),  :basic | :extended) ::String.t()

Converts the given time into a string.

By default, returns times formatted in the "extended" format,for human readability. It also supports the "basic" formatby passing the:basic option.

Examples

iex>Calendar.ISO.time_to_string(2,2,2,{2,6})"02:02:02.000002"iex>Calendar.ISO.time_to_string(2,2,2,{2,2})"02:02:02.00"iex>Calendar.ISO.time_to_string(2,2,2,{2,0})"02:02:02"iex>Calendar.ISO.time_to_string(2,2,2,{2,6},:basic)"020202.000002"iex>Calendar.ISO.time_to_string(2,2,2,{2,6},:extended)"02:02:02.000002"

@spec time_unit_to_precision(System.time_unit()) :: 0..6

Converts aSystem.time_unit/0 to precision.

Integer-based time units always get maximum precision.

Examples

iex>Calendar.ISO.time_unit_to_precision(:nanosecond)6iex>Calendar.ISO.time_unit_to_precision(:second)0iex>Calendar.ISO.time_unit_to_precision(1)6

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

Determines if the date given is valid according to the proleptic Gregorian calendar.

Examples

iex>Calendar.ISO.valid_date?(2015,2,28)trueiex>Calendar.ISO.valid_date?(2015,2,30)falseiex>Calendar.ISO.valid_date?(-1,12,31)trueiex>Calendar.ISO.valid_date?(-1,12,32)false

@spec valid_time?(Calendar.hour(),Calendar.minute(),Calendar.second(),Calendar.microsecond()) ::boolean()

Determines if the date given is valid according to the proleptic Gregorian calendar.

Leap seconds are not supported by the built-in Calendar.ISO.

Examples

iex>Calendar.ISO.valid_time?(10,50,25,{3006,6})trueiex>Calendar.ISO.valid_time?(23,59,60,{0,0})falseiex>Calendar.ISO.valid_time?(24,0,0,{0,0})false

@spec year_of_era(year()) :: {1..10000,era()}

Calculates the year and era from the givenyear.

The ISO calendar has two eras: the "current era" (CE) whichstarts in year1 and is defined as era1. And "before the currentera" (BCE) for those years less than1, defined as era0.

Examples

iex>Calendar.ISO.year_of_era(1){1,1}iex>Calendar.ISO.year_of_era(2018){2018,1}iex>Calendar.ISO.year_of_era(0){1,0}iex>Calendar.ISO.year_of_era(-1){2,0}

@spec year_of_era(year(),month(),day()) :: {1..10000,era()}

Calendar callback to compute the year and era from thegivenyear,month andday.

In the ISO calendar, the new year coincides with the new era,so themonth andday arguments are discarded. If you onlyhave the year available, you canyear_of_era/1 instead.

Examples

iex>Calendar.ISO.year_of_era(1,1,1){1,1}iex>Calendar.ISO.year_of_era(2018,12,1){2018,1}iex>Calendar.ISO.year_of_era(0,1,1){1,0}iex>Calendar.ISO.year_of_era(-1,12,1){2,0}