模组:Date/doc

本模块为其他模块提供日期相关的函数。目前支持公历和儒略历的日期，有效范围从公元前999年至公元9999年。使用的日期都应当是公历前推的，也就是说所有的时间都是唯一且确定的。

日期，包含可选的时间，可以用多种格式指定，并且可以通过多种格式进行显示转换，例如：1 April 2016 或 April 1, 2016。一个日期的属性包括它的儒略日期和公历序列日期，以及星期几和一年中的第几天。

日期是可比的（例如，date1 <= date2），并且可以相加或相减（例如，date + '3 months'）。两个日期之间的差异可以通过 date1 - date2 来确定。这些操作适用于公历和儒略历日期，但如果两个日期混用不同的历法，date1 - date2 将为空。

该模块提供以下内容：

模块导出	描述
_current	包含当前年月日时分秒的表（table）
_Date	返回包含指定日期的表（table）的函数
_days_in_month	返回某个月的天数的函数

格式化输出

日期可以以文字形式输出：

local Date = require('Module:Date')._Date
local text = Date(2016, 7, 1):text()          -- 输出 '1 July 2016'
local text = Date(2016, 7, 1):text('%-d %B')  -- 输出 '1 July'
local text = Date('1 July 2016'):text('mdy')  -- 输出 'July 1, 2016'

模块提供了下列格式代码简写：

代码	结果
hm	hour:minute, 包含"am"或"pm" or variant, if specified (14:30 or 2:30 pm or variant)
hms	hour:minute:second (14:30:45)
ymd	year-month-day (2016-07-01)
mdy	month day, year (July 1, 2016)
dmy	day month year (1 July 2016)

以下格式化代码（类似于C语言的 strftime）可用于格式化输出日期：

代码	结果
%a	Day abbreviation: Mon, Tue, ...
%A	Day name: Monday, Tuesday, ...
%u	Day of week: 1 to 7 (Monday to Sunday)
%w	Day of week: 0 to 6 (Sunday to Saturday)
%d	Day of month zero-padded: 01 to 31
%b	Month abbreviation: Jan to Dec
%B	Month name: January to December
%m	Month zero-padded: 01 to 12
%Y	Year zero-padded: 0012, 0120, 1200
%H	Hour 24-hour clock zero-padded: 00 to 23
%I	Hour 12-hour clock zero-padded: 01 to 12
%p	AM or PM or as in options
%M	Minute zero-padded: 00 to 59
%S	Second zero-padded: 00 to 59
%j	Day of year zero-padded: 001 to 366
%-d	Day of month: 1 to 31
%-m	Month: 1 to 12
%-Y	Year: 12, 120, 1200
%-H	Hour: 0 to 23
%-M	Minute: 0 to 59
%-S	Second: 0 to 59
%-j	Day of year: 1 to 366
%-I	Hour: 1 to 12
%%	%

此外，可以使用%{property}（其中 property 是日期的任何属性）来进行格式化。

例如，Date('1 Feb 2015 14:30:45 A.D.') 具有以下属性：

代码	结果
%{calendar}	Gregorian
%{year}	2015
%{month}	2
%{day}	1
%{hour}	14
%{minute}	30
%{second}	45
%{dayabbr}	Sun
%{dayname}	Sunday
%{dayofweek}	0
%{dow}	0 (same as dayofweek)
%{dayofweekiso}	7
%{dowiso}	7 (same as dayofweekiso)
%{dayofyear}	32
%{era}	A.D.
%{gsd}	735630 (numbers of days from 1 January 1 CE; the first is day 1)
%{juliandate}	2457055.1046875 (Julian day)
%{jd}	2457055.1046875 (same as juliandate)
%{isleapyear}	false
%{monthdays}	28
%{monthabbr}	Feb
%{monthname}	February

一些快捷方式也是可用的。给定 date = Date('1 Feb 2015 14:30')，将产生以下结果：

代码	描述	结果	等同于
date:text('%c')	date and time	2:30 pm 1 February 2015	%-I:%M %p %-d %B %-Y %{era}
date:text('%x')	date	1 February 2015	%-d %B %-Y %{era}
date:text('%X')	time	2:30 pm	%-I:%M %p

儒略日期

下面是一个将儒略日期转换为日期，并获取日期信息的示例：

-- 代码                                                -- 结果
Date = require('Module:Date')._Date
date = Date('juliandate', 320)
number = date.gsd                                      -- -1721105
number = date.jd                                       -- 320
text = date.dayname                                    -- Saturday
text = date:text()                                     -- 9 October 4713 BC
text = date:text('%Y-%m-%d')                           -- 4713-10-09
text = date:text('%{era} %Y-%m-%d')                    -- BC 4713-10-09
text = date:text('%Y-%m-%d %{era}')                    -- 4713-10-09 BC
text = date:text('%Y-%m-%d %{era}', 'era=B.C.E.')      -- 4713-10-09 B.C.E.
text = date:text('%Y-%m-%d', 'era=BCNEGATIVE')         -- -4712-10-09
text = date:text('%Y-%m-%d', 'era=BCMINUS')            -- −4712-10-09 (uses Unicode MINUS SIGN U+2212)
text = Date('juliandate',320):text('%{gsd} %{jd}')     -- -1721105 320
text = Date('Oct 9, 4713 B.C.E.'):text('%{gsd} %{jd}') -- -1721105 320
text = Date(-4712,10,9):text('%{gsd} %{jd}')           -- -1721105 320

日期差

两个日期之间的差值可以通过 date1 - date2 来确定。如果两个日期都使用公历或儒略历，那么计算的结果是有效的；如果两个日期使用不同的历法，那么计算的结果将为空值。日期差异可以被用于计算年龄和时间间隔。

例子：

-- 代码                                      -- 结果
Date = require('Module:Date')._Date
date1 = Date('21 Mar 2015')
date2 = Date('4 Dec 1999')
diff = date1 - date2
d = diff.age_days                            -- 5586
y, m, d = diff.years, diff.months, diff.days -- 15, 3, 17 (15 years + 3 months + 17 days)
y, m, d = diff:age('ymd')                    -- 15, 3, 17
y, m, w, d = diff:age('ymwd')                -- 15, 3, 2, 3 (15 years + 3 months + 2 weeks + 3 days)
y, m, w, d = diff:duration('ymwd')           -- 15, 3, 2, 4
d = diff:duration('d')                       -- 5587 (duration 包含最后一天)

日期差包含原始的日期，只是它们可能被交换以满足 diff.date1 >= diff.date2 的条件（其中 diff.date1 是较靠后的日期）。以下是示例说明：

date1 = Date('21 Mar 2015')
date2 = Date('4 Dec 1999')
diff = date1 - date2
neg = diff.isnegative                        -- false
text = diff.date1:text()                     -- 21 March 2015
text = diff.date2:text()                     -- 4 December 1999
diff = date2 - date1
neg = diff.isnegative                        -- true (日期被交换了)
text = diff.date1:text()                     -- 21 March 2015
text = diff.date2:text()                     -- 4 December 1999

除了包含日期之间的差，还包含时间之间的差：

date1 = Date('8 Mar 2016 0:30:45')
date2 = Date('19 Jan 2014 22:55')
diff = date1 - date2
y, m, d = diff.years, diff.months, diff.days      -- 2, 1, 17
H, M, S = diff.hours, diff.minutes, diff.seconds  -- 1, 35, 45

日期差值可以被加到一个日期上，也可以从一个日期上减去：

date1 = Date('8 Mar 2016 0:30:45')
date2 = Date('19 Jan 2014 22:55')
diff = date1 - date2
date3 = date2 + diff
date4 = date1 - diff
text = date3:text('ymd hms')        -- 2016-03-08 00:30:45
text = date4:text('ymd hms')        -- 2014-01-19 22:55:00
equal = (date1 == date3)            -- true
equal = (date2 == date4)            -- true

年龄和时间间隔的日期差可以接受一个代码，用于指定需要返回的日期间隔组成部分。对于时间间隔，会额外包含一天，因为它包含了最后一天：

代码	返回值
'ymwd'	years, months, weeks, days
'ymd'	years, months, days
'ym'	years, months
'y'	years
'm'	months
'wd'	weeks, days
'w'	weeks
'd'	days