跳转到内容

模组:Date/doc

维基百科,自由的百科全书

这是Module:Date的文档页面

本模块为其他模块提供日期相关的函数。目前支持公历儒略历的日期,有效范围从公元前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&nbsp;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&nbsp;BC
text = date:text('%Y-%m-%d %{era}', 'era=B.C.E.')      -- 4713-10-09&nbsp;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