Editing Module:Date/doc (section)

== 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
|}
<noinclude>
[[Category:Module documentation pages]]
</noinclude>