模块:Date/doc
这是Module:Date的文档页面
此模块文档被引用于约126,000个页面。 为了避免造成大规模的影响,所有对此模块文档的编辑应先于沙盒或测试样例上测试。 测试后无误的版本可以一次性地加入此模块文档中,但是修改前请务必于讨论页发起讨论。 模板引用数量会自动更新。 |
本模块为其他模块提供日期相关的函数。目前支持公历和儒略历的日期,有效范围从公元前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 |