跳至內容

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