Redigerer Modul:Date/dok

This module provides date functions for use by other modules. Dates in the [[Gregorian calendar]] and the [[Julian calendar]] are supported, from 9999 BCE to 9999 CE. The calendars are proleptic—they are assumed to apply at all times with no irregularities.

A date, with an optional time, can be specified in a variety of formats, and can be converted for display using a variety of formats, for example, 1 April 2016 or April 1, 2016. The properties of a date include its [[Julian day|Julian date]] and its Gregorian serial date, as well as the day-of-week and day-of-year.

Dates can be compared (for example, <code>date1 <= date2</code>), and can be used with add or subtract (for example, <code>date + '3 months'</code>). The difference between two dates can be determined with <code>date1 - date2</code>. These operations work with both Gregorian and Julian calendar dates, but <code>date1 - date2</code> is nil if the two dates use different calendars.

The module provides the following items.

{| class="wikitable"
! Export !! Description
|-
| <code>_current</code>       || Table with the current year, month, day, hour, minute, second.
|-
| <code>_Date</code>          || Function that returns a table for a specified date.
|-
| <code>_days_in_month</code> || Function that returns the number of days in a month.
|}

The following has examples of using the module:
*[[Module:Date/example]] • Demonstration showing how Module:Date may be used.
*[[Module talk:Date/example]] • Output from the demonstration.

== Formatted output ==

A date can be formatted as text.
<syntaxhighlight lang="lua">
local Date = require('Module:Date')._Date
local text = Date(2016, 7, 1):text()          -- result is '1 July 2016'
local text = Date(2016, 7, 1):text('%-d %B')  -- result is '1 July'
local text = Date('1 July 2016'):text('mdy')  -- result is 'July 1, 2016'
</syntaxhighlight>

The following simplified formatting codes are available.
{| class="wikitable"
! Code !! Result
|-
| hm  || hour:minute, with "am" or "pm" or variant, if specified (14:30 or 2:30&nbsp;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)
|}

The following formatting codes (similar to [[strftime]]) are available.
{| class="wikitable"
! Code !! Result
|-
| %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
|-
| %%  || %
|}

In addition, <code>%{''property''}</code> (where <code>''property''</code> is any property of a date) can be used.

For example, <code>Date('1 Feb 2015 14:30:45 A.D.')</code> has the following properties.

{| class="wikitable"
! Code !! Result
|-
| %{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
|}

Some shortcuts are available. Given <code>date = Date('1 Feb 2015 14:30')</code>, the following results would occur.
{| class="wikitable"
! Code            !! Description   !! Example result               !! Equivalent format
|-
| date:text('%c') || date and time || 2:30&nbsp;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&nbsp;pm                 || %-I:%M %p
|}

== Julian date ==

The following has an example of converting a [[Julian day|Julian date]] to a date, then obtaining information about the date.
<syntaxhighlight lang="lua">
-- Code                                                -- Result
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
</syntaxhighlight>

== Date differences ==

The difference between two dates can be determined with <code>date1 - date2</code>. The result is valid if both dates use the Gregorian calendar or if both dates use the Julian calendar, otherwise the result is nil. An age and duration can be calculated from a date difference.

For example:
<syntaxhighlight lang="lua">
-- Code                                      -- Result
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 (a duration includes the final day)
</syntaxhighlight>

A date difference holds the original dates except they are swapped so <code>diff.date1 >= diff.date2</code> (<code>diff.date1</code> is the more recent date). This is shown in the following.
<syntaxhighlight lang="lua">
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 (dates have been swapped)
text = diff.date1:text()                     -- 21 March 2015
text = diff.date2:text()                     -- 4 December 1999
</syntaxhighlight>

A date difference also holds a time difference:
<syntaxhighlight lang="lua">
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
</syntaxhighlight>

A date difference can be added to a date, or subtracted from a date.
<syntaxhighlight lang="lua">
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
</syntaxhighlight>

The age and duration methods of a date difference accept a code that identifies the components that should be returned. An extra day is included for the duration method because it includes the final day.
{| class="wikitable"
! Code !! Returned values
|-
| <code>'ymwd'</code> || years, months, weeks, days
|-
| <code>'ymd'</code>  || years, months, days
|-
| <code>'ym'</code>   || years, months
|-
| <code>'y'</code>    || years
|-
| <code>'m'</code>    || months
|-
| <code>'wd'</code>   || weeks, days
|-
| <code>'w'</code>    || weeks
|-
| <code>'d'</code>    || days
|}