模組:Date/doc
此頁面為 Module:Date 的說明文件
![]() | 此模組文件被引用於約125,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 |