日期 | Date

日期结构和功能。

Date结构包含字段年，月，日和日历。新的日期可以new/3使用函数或使用~Dsigil 来构建：

iex> ~D[2000-01-01]
~D[2000-01-01]

两者new/3和sigil都会返回一个结构，可以直接访问日期字段：

iex> date = ~D[2000-01-01]
iex> date.year
2000
iex> date.month
1

这个模块上的函数和Date结构以及包含与结构相同的字段的任何结构一起工作Date，例如NaiveDateTime和DateTime。这些函数期望Calendar.date/0在它们的类型规范中（而不是t/0）。

开发人员应避免直接创建Date结构，而应依赖此模块提供的功能以及第三方日历库中的功能。

比较日期

在药剂比较使用==，>，<和类似的是结构以及基于所述Date结构字段。为了正确比较日期，请使用该compare/2功能。

使用时代

add/2和diff/2功能可以用于计算日期或检索天量中间人时刻。例如，如果有兴趣计算Unix纪元（1970-01-01）的天数：

iex> Date.diff(~D[2010-04-17], ~D[1970-01-01])
14716

iex> Date.add(~D[1970-01-01], 14716)
~D[2010-04-17]

这些函数经过优化以处理通用时期，例如上述的Unix Epoch或Gregorian Epoch（0000-01-01）。

类型

t()

函数

add(date, days)

将天数添加到给定的date

compare(date1, date2)

比较两个日期结构

convert(date, calendar)

转换给定的date从日历到给定calendar

convert!(date, calendar)

类似于Date.convert/2，但提出了一个ArgumentError如果无法在两个日历之间进行转换

day_of_week(date)

计算给定日期的一周中的某一天。date

days_in_month(date)

返回给定date月份的天数

diff(date1, date2)

计算两个日期之间的差异，以完整的天数为单位。

from_erl(tuple, calendar \ Calendar.ISO)

将Erlang日期元组转换为Date结构

from_erl!(tuple)

=

转换Erlang日期元组，但引发无效日期。

from_iso8601(string, calendar \ Calendar.ISO)

解析扩展的“日期”格式。ISO 8601：2004

from_iso8601!(string, calendar \ Calendar.ISO)

解析扩展的“日期”格式。ISO 8601：2004

leap_year?(date)

如果给定年份中的年份为true，则返回date是闰年

new(year, month, day, calendar \ Calendar.ISO)

建立一个新的ISO日期

range(first, last)

返回日期范围

to_erl(date)

将给定转换为dateErlang日期元组

to_iso8601(date, format \ :extended)

将给定值转换date为ISO 8601：2004

to_string(date)

根据给定日期的日历将给定日期转换为字符串。

utc_today(calendar \ Calendar.ISO)

返回UTC中的当前日期。

t()

t() :: %Date{calendar: Calendar.calendar, day: Calendar.day, month: Calendar.month, year: Calendar.year}

add(date, days)

add(Calendar.date, integer) :: t

添加给定天数date。

这些日子算作公历日。日期在给定的日历中返回。

实例

iex> Date.add(~D[2000-01-03], -2)
~D[2000-01-01]
iex> Date.add(~D[2000-01-01], 2)
~D[2000-01-03]

iex> Date.add(~N[2000-01-01 09:00:00], 2)
~D[2000-01-03]

compare(date1, date2)

compare(Calendar.date, Calendar.date) :: :lt | :eq | :gt

比较两个日期结构。

:gt如果第一个日期晚于第二个日期，则返回:lt，反之亦然。如果两个日期相等，:eq则返回。

实例

iex> Date.compare(~D[2016-04-16], ~D[2016-04-28])
:lt

通过只考虑日期字段，此函数还可用于比较更复杂的日历类型：

iex> Date.compare(~D[2016-04-16], ~N[2016-04-28 01:23:45])
:lt
iex> Date.compare(~D[2016-04-16], ~N[2016-04-16 01:23:45])
:eq
iex> Date.compare(~N[2016-04-16 12:34:56], ~N[2016-04-16 01:23:45])
:eq

convert(date, calendar)

convert(Calendar.date, Calendar.calendar) ::
  {:ok, t} |
  {:error, :incompatible_calendars}

将给定date的日历转换为给定的日历calendar。

{:ok, date}如果日历兼容，或者{:error, :incompatible_calendars}不兼容，则返回。

另见Calendar.compatible_calendars?/2...

实例

想象一下，有人实现Calendar.Holocene了一个基于公历日历的公历日历，该日历公历年正好增加了1万年：

iex> Date.convert(~D[2000-01-01], Calendar.Holocene)
{:ok, %Date{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1}}

convert!(date, calendar)

convert!(Calendar.date, Calendar.calendar) :: t

类似于Date.convert/2，但提出了一个ArgumentError如果无法在两个日历之间进行转换。

实例

想象一下有人Calendar.Holocene，一种基于公历的日历，它将当前的公历年相加整整10000年：

iex> Date.convert!(~D[2000-01-01], Calendar.Holocene)
%Date{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1}

day_of_week(date)

day_of_week(Calendar.date) :: non_neg_integer

计算给定日期的一周中的某一天。date...

以整数形式返回一周中的一天。对于ISO 8601日历%28默认的%29，它是从1到7的整数，其中1是星期一，7是周日。

实例

iex> Date.day_of_week(~D[2016-10-31])
1
iex> Date.day_of_week(~D[2016-11-01])
2
iex> Date.day_of_week(~N[2016-11-01 01:23:45])
2

days_in_month(date)

days_in_month(Calendar.date) :: Calendar.day

返回给定date月份的天数。

实例

iex> Date.days_in_month(~D[1900-01-13])
31
iex> Date.days_in_month(~D[1900-02-09])
28
iex> Date.days_in_month(~N[2000-02-20 01:23:45])
29

diff(date1, date2)

diff(Calendar.date, Calendar.date) :: integer

计算两个日期之间的差异，以完整的天数为单位。

它返回日期之间的公历日数。只Date遵循相同或兼容日历的结构可以这样进行比较。如果两个日历不兼容，则会引发。

实例

iex> Date.diff(~D[2000-01-03], ~D[2000-01-01])
2
iex> Date.diff(~D[2000-01-01], ~D[2000-01-03])
-2

iex> Date.diff(~D[2000-01-01], ~N[2000-01-03 09:00:00])
-2

from_erl(tuple, calendar \ Calendar.ISO)

将Erlang日期元组转换为Date结构。

仅支持转换ISO日历中的日期，或其他日历中的日期，其中的日期也从午夜开始。尝试从其他日历转换日期将返回错误元组。

实例

iex> Date.from_erl({2000, 1, 1})
{:ok, ~D[2000-01-01]}
iex> Date.from_erl({2000, 13, 1})
{:error, :invalid_date}

from_erl!(tuple)

from_erl!(:calendar.date) :: t

转换Erlang日期元组，但引发无效日期。

实例

iex> Date.from_erl!({2000, 1, 1})
~D[2000-01-01]
iex> Date.from_erl!({2000, 13, 1})
** (ArgumentError) cannot convert {2000, 13, 1} to date, reason: :invalid_date

from_iso8601(string, calendar \ Calendar.ISO)

解析ISO 8601：2004所描述的扩展“日期”格式。

实例

iex> Date.from_iso8601("2015-01-23")
{:ok, ~D[2015-01-23]}

iex> Date.from_iso8601("2015:01:23")
{:error, :invalid_format}

iex> Date.from_iso8601("2015-01-32")
{:error, :invalid_date}

from_iso8601!(string, calendar \ Calendar.ISO)

解析ISO 8601：2004所描述的扩展“日期”格式。

如果格式无效，则引发。

实例

iex> Date.from_iso8601!("2015-01-23")
~D[2015-01-23]
iex> Date.from_iso8601!("2015:01:23")
** (ArgumentError) cannot parse "2015:01:23" as date, reason: :invalid_format

leap_year?(date)

leap_year?(Calendar.date) :: boolean

如果给定的年份date是闰年，则返回true 。

实例

iex> Date.leap_year?(~D[2000-01-01])
true
iex> Date.leap_year?(~D[2001-01-01])
false
iex> Date.leap_year?(~D[2004-01-01])
true
iex> Date.leap_year?(~D[1900-01-01])
false
iex> Date.leap_year?(~N[2004-01-01 01:23:45])
true

new(year, month, day, calendar \ Calendar.ISO)

生成新的ISO日期。

期望所有值都是整数。返回{:ok, date}每个条目是否适合其适当的范围，{:error, reason}否则返回。

实例

iex> Date.new(2000, 1, 1)
{:ok, ~D[2000-01-01]}
iex> Date.new(2000, 13, 1)
{:error, :invalid_date}
iex> Date.new(2000, 2, 29)
{:ok, ~D[2000-02-29]}

iex> Date.new(2000, 2, 30)
{:error, :invalid_date}
iex> Date.new(2001, 2, 29)
{:error, :invalid_date}

range(first, last)

range(Calendar.date, Calendar.date) :: Date.Range.t

返回日期范围。

日期范围表示离散的日期数，其中第一个和最后一个值是具有匹配日历的日期。

日期的范围可以是增加（first <= last）或减少（first > last）。他们也总是包容性的。

iex> Date.range(~D[1999-01-01], ~D[2000-01-01])
#DateRange<~D[1999-01-01], ~D[2000-01-01]>

iex> Date.range(~N[2000-01-01 09:00:00], ~D[1999-01-01])
#DateRange<~N[2000-01-01 09:00:00], ~D[1999-01-01]>

日期的范围实现了Enumerable协议，这意味着Enum模块可用于处理范围：

iex> range = Date.range(~D[2001-01-01], ~D[2002-01-01])
iex> Enum.count(range)
366
iex> Enum.member?(range, ~D[2001-02-01])
true
iex> Enum.reduce(range, 0, fn _date, acc -> acc - 1 end)
-366

to_erl(date)

to_erl(Calendar.date) :: :calendar.date

转换给定的date二郎枣元组。

仅支持转换ISO日历中的日期，或其他日历中的日期，其中的日期也从午夜开始。尝试从其他日历转换日期将引发。

实例

iex> Date.to_erl(~D[2000-01-01])
{2000, 1, 1}

iex> Date.to_erl(~N[2000-01-01 00:00:00])
{2000, 1, 1}

to_iso8601(date, format \ :extended)

to_iso8601(Calendar.date, :extended | :basic) :: String.t

将给定值转换date为ISO 8601：2004。

默认情况下，Date.to_iso8601/2返回格式为“扩展”格式的日期，以供人员阅读。它也通过传递:basic选项支持“基本”格式。

仅支持转换ISO日历中的日期，或支持日历也在午夜开始的其他日历。试图从其他日历转换日期将引发ArgumentError。

实例

iex> Date.to_iso8601(~D[2000-02-28])
"2000-02-28"

iex> Date.to_iso8601(~D[2000-02-28], :basic)
"20000228"

iex> Date.to_iso8601(~N[2000-02-28 00:00:00])
"2000-02-28"

to_string(date)

to_string(Calendar.date) :: String.t

根据日期日历将给定日期转换为字符串。

实例

iex> Date.to_string(~D[2000-02-28])
"2000-02-28"
iex> Date.to_string(~N[2000-02-28 01:23:45])
"2000-02-28"

utc_today(calendar \ Calendar.ISO)

utc_today(Calendar.calendar) :: t

返回UTC中的当前日期。

实例

iex> date = Date.utc_today()
iex> date.year >= 2016
true

	日期 | Date
	日期 | Date	详细
	日期范围 | Date.Range	详细