模組: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