Caleb Cooper: Created page with "{{documentation subpage}} {{Lua|Module:Age|Module:Date}} {{Commons Import}} '''This template can extract information from a date, or can format a date. Time units can be added..."

2020-10-25T18:08:54Z

Created page with "{{documentation subpage}} {{Lua|Module:Age|Module:Date}} {{Commons Import}} '''This template can extract information from a date, or can format a date. Time units can be added..."

New page

{{documentation subpage}}
{{Lua|Module:Age|Module:Date}}
{{Commons Import}}
'''This template can extract information from a date, or can format a date. Time units can be added to a date.'''

== Syntax ==
*<code>{{extract|''date''|''options''}}</code>

The following options are available:
*<code>add=''periods to add''</code> • Add/subtract time units.
*<code>fix=on</code> • Adjust invalid time units.
*<code>partial=on</code> • Accept a year only, or a year and month only.
*<code>show=''what to display''</code> • Specifies what should be extracted (such as <code>dayname</code>), or how to format the date (such as <code>mdy</code>).
*<code>sortable=on</code> • A hidden sort key is inserted before the date (for use in [[WP:SORT|sortable tables]]).

The date can be entered as the first parameter, or separate parameters can be used for the year/month/day/hour/minute/second components of a date.

By default, the date is displayed in dmy format, for example:
*<code><nowiki>{{extract|2015-11-12}}</nowiki></code> → {{extract|2015-11-12}}

== Date ==
A valid date must be specified. Dates are [[Coordinated Universal Time|UTC]]—local times and time zones are not supported.

Dates from 9999 BCE to 9999 CE are accepted. The [[proleptic Gregorian calendar]] is used by default. Entering the parameter <code>julian</code> with a date uses the [[proleptic Julian calendar]].

A date can include an era or a time, and a variety of formats are accepted.

Examples of valid dates follow. Each row shows two equivalent methods of entering a date.
{| class="wikitable"
! A date as a single parameter !! Components of a date in separate parameters
|-
| <code>{{extract|1900-02-01}}</code> || <code>{{extract|1900|02|01}}</code>
|-
| <code>{{extract|1900-2-1 14:45}}</code> || <code>{{extract|1900|2|1|14|45}}</code>
|-
| <code>{{extract|1 FEB 1900}}</code> || <code>{{extract|1900|FEB|1}}</code>
|-
| <code>{{extract|February 1, 1900}}</code> || <code>{{extract|1900|February|1}}</code>
|-
| <code>{{extract|Feb 1 1900 14:45}}</code> || <code>{{extract|1900|Feb|1|14|45}}</code>
|-
| <code>{{extract|2:45 pm February 1 1900}}</code> || <code>{{extract|1900|February|1|14|45}}</code>
|-
| <code>{{extract|1 February 1900 2:45 p.m.}}</code> || <code>{{extract|1900|February|1|14|45}}</code>
|-
| <code>{{extract|BC 1 Feb 120}}</code> || <code>{{extract|-119|2|1}}</code>
|}

The last example above uses the rule:
:'''''n''''' BC is year '''1 − ''n'''''
Year 0 refers to 1 BC, and year −1 is 2 BC, etc.

Dates can also be entered with the following special names which are not case sensitive.
*<code><nowiki>{{extract|juliandate|2451545}}</nowiki></code> → {{extract|juliandate|2451545}} {{green|1=([[Julian day]] 2451545 is noon 1 January 2000 UTC in the Gregorian calendar)}}
*<code><nowiki>{{extract|juliandate|julian|2451545}}</nowiki></code> → {{extract|juliandate|julian|2451545}} {{green|1=(which is 19 December 1999 in the Julian calendar)}}
*<code><nowiki>{{extract|currentdate}}</nowiki></code> → {{extract|currentdate}} {{green|1=(the date shown is when this documentation page was last [[WP:Purge|purged]])}}
*<code><nowiki>{{extract|currentdatetime}}</nowiki></code> → {{extract|currentdatetime}}

The following confirms that 16 February 2000 in the [[Julian calendar]] was 29 February 2000 in the [[Gregorian calendar]].
*<code><nowiki>{{extract|julian|Feb 16, 2000|show=juliandate}}</nowiki></code> → {{extract|julian|Feb 16, 2000|show=juliandate}} {{green|1=(Julian calendar was specified)}}
*<code><nowiki>{{extract|juliandate|2451604}}</nowiki></code> → {{extract|juliandate|2451604}} {{green|1=(Gregorian calendar by default)}}

16 February 2000 in the Julian calendar can be converted to the Gregorian calendar in one line:
*<code><nowiki>{{extract|juliandate|{{extract|julian|16 Feb 2000|show=juliandate}}}}</nowiki></code> → {{extract|juliandate|{{extract|julian|16 Feb 2000|show=juliandate}}}}

== Add ==
These time units can be added to a date:
*<code>y</code> years
*<code>m</code> months
*<code>d</code> days
*<code>h</code> hours
*<code>min</code> minutes
*<code>s</code> seconds

Multiple periods can be given, separated by spaces. There must be no space between a value and the code for the time unit.

A hyphen can be used for a negative value. Periods are added in the order given.

Examples:
*<code><nowiki>{{extract|2004-04-03|add=28d}}</nowiki></code> → {{extract|2004-04-03|add=28d}}
*<code><nowiki>{{extract|2004-04-03|add=3m 28d}}</nowiki></code> → {{extract|2004-04-03|add=3m 28d}}
*<code><nowiki>{{extract|2004-04-03|add=28d 3m}}</nowiki></code> → {{extract|2004-04-03|add=28d 3m}} {{green|1=(the order in which units are added changes the result)}}
*<code><nowiki>{{extract|2004-04-03|add=-3d}}</nowiki></code> → {{extract|2004-04-03|add=-3d}}
*<code><nowiki>{{extract|2004-04-03|add=-912345d}}</nowiki></code> → {{extract|2004-04-03|add=-912345d}}
*<code><nowiki>{{extract|2004-04-03|add=250h}}</nowiki></code> → {{extract|2004-04-03|add=250h}}
*<code><nowiki>{{extract|2004-04-03|add=-2.5h}}</nowiki></code> → {{extract|2004-04-03|add=-2.5h}}
*<code><nowiki>{{extract|2004-04-30|add=-2m}}</nowiki></code> → {{extract|2004-04-30|add=-2m}}
*<code><nowiki>{{extract|2004-04-03|add=2y 3m 4d}}</nowiki></code> → {{extract|2004-04-03|add=2y 3m 4d}}
*<code><nowiki>{{extract|2004-04-03|add=5.75d}}</nowiki></code> → {{extract|2004-04-03|add=5.75d}} {{green|1=(years and months are integer only)}}

== Fix ==
By default, the date entered must be valid. If <code>fix=on</code> is used, units which are too large are "fixed". For example, 26 hours would be regarded as 1 day and 2 hours.

Entering a day as zero is regarded as the previous day (the last day of the previous month). The day before the previous day would be indicated with <code>-1</code>.

Similarly, entering a month as zero goes back one month, and entering <code>-1</code> goes back two months.

Examples:
*<code><nowiki>{{extract|2001|5|31|fix=on}}</nowiki></code> → {{extract|2001|5|31|fix=on}} {{green|1=(no fix is required)}}
*<code><nowiki>{{extract|2001|5|0|fix=on}}</nowiki></code> → {{extract|2001|5|0|fix=on}}
*<code><nowiki>{{extract|2001|5|-1|fix=on}}</nowiki></code> → {{extract|2001|5|-1|fix=on}}
*<code><nowiki>{{extract|2001|125|-1000|fix=on}}</nowiki></code> → {{extract|2001|125|-1000|fix=on}}
*<code><nowiki>{{extract|2001|0|12|fix=on}}</nowiki></code> → {{extract|2001|0|12|fix=on}}
*<code><nowiki>{{extract|2016|3|0|fix=on}}</nowiki></code> → {{extract|2016|3|0|fix=on}}

The following shows how to get the date for a given year and day-of-year. For example, June 30, 2001 is day 181 in the year 2001, as can be seen by adding 181 days to the date just before January 1, 2001.
*<code><nowiki>{{extract|June 30, 2001|show=dayofyear}}</nowiki></code> → {{extract|June 30, 2001|show=dayofyear}} {{green|1=(date to day-of-year)}}
*<code><nowiki>{{extract|2001|1|0|fix=on|add=181d|show=mdy}}</nowiki></code> → {{extract|2001|1|0|fix=on|add=181d|show=mdy}} {{green|1=(day-of-year to date)}}

== Partial ==
If <code>partial=on</code> is used, the date may consist of a year only, or a year and month only. Addition is not supported for a partial date.
*<code><nowiki>{{extract|2001|5|partial=on}}</nowiki></code> → {{extract|2001|5|partial=on}}
*<code><nowiki>{{extract|2016|partial=on|show=isleapyear}}</nowiki></code> → {{extract|2016|partial=on|show=isleapyear}}

== Show ==
The following table lists most of the show parameters that can be used. Some of these work properly only with a full date.
{| class="wikitable"
! Parameter !! Description
|-
| <code>show=hide</code> || display nothing; may be useful with <code>sortable=on</code>
|-
| <code>show=year</code> || year
|-
| <code>show=month</code> || month (1 to 12)
|-
| <code>show=day</code> || day of month (1 to 31)
|-
| <code>show=hour</code> || hour (0 to 23)
|-
| <code>show=minute</code> || minute (0 to 59)
|-
| <code>show=second</code> || second (0 to 59)
|-
| <code>show=dayabbr</code> || abbreviated name of day of week
|-
| <code>show=dayname</code> || full name of day of week
|-
| <code>show=dayofweek</code> || day-of-week (0=Sunday to 6=Saturday)
|-
| <code>show=dayofweekiso</code> || day-of-week (1=Monday to 7=Sunday)
|-
| <code>show=dayofyear</code> || day-of-year (1 to 366)
|-
| <code>show=era</code> || an era code such as BC or BCE
|-
| <code>show=format</code> || code for the detected format of the input date (dmy, mdy, ymd, or error)
|-
| <code>show=gsd</code> || Gregorian serial date
|-
| <code>show=juliandate</code> || Julian day
|-
| <code>show=isleapyear</code> || 1 if the date is in a leap year; 0 otherwise
|-
| <code>show=monthabbr</code> || abbreviated name of month
|-
| <code>show=monthdays</code> || number of days in the month of the date
|-
| <code>show=monthname</code> || full name of month
|-
| <code>show=dmy</code> || show date as "day month year" (default)
|-
| <code>show=mdy</code> || show date as "month day, year"
|-
| <code>show=ymd</code> || show date as "year-month-day"
|}

Examples:
*<code><nowiki>{{extract|1 Feb 2001}}</nowiki></code> → {{extract|1 Feb 2001}}
*<code><nowiki>{{extract|FEB 1 2001}}</nowiki></code> → {{extract|FEB 1 2001}}
*<code><nowiki>{{extract|2001-2-1}}</nowiki></code> → {{extract|2001-2-1}}
*<code><nowiki>{{extract|1 Feb 2001|show=format}}</nowiki></code> → {{extract|1 Feb 2001|show=format}}
*<code><nowiki>{{extract|FEB 1 2001|show=format}}</nowiki></code> → {{extract|FEB 1 2001|show=format}}
*<code><nowiki>{{extract|2001-2-1|show=format}}</nowiki></code> → {{extract|2001-2-1|show=format}}
*<code><nowiki>{{extract|2001-2-29|show=format}}</nowiki></code> → {{extract|2001-2-29|show=format}}
*<code><nowiki>{{extract|1 Feb 2001|show=mdy}}</nowiki></code> → {{extract|1 Feb 2001|show=mdy}}
*<code><nowiki>{{extract|1 Feb 2001|show=ymd}}</nowiki></code> → {{extract|1 Feb 2001|show=ymd}}
*<code><nowiki>{{extract|June 30, 2001|show=dayname}}</nowiki></code> → {{extract|June 30, 2001|show=dayname}}
*<code><nowiki>{{extract|June 30, 2001|show=dayofyear}}</nowiki></code> → {{extract|June 30, 2001|show=dayofyear}}
*<code><nowiki>{{extract|2001-2-1|show=monthname}}</nowiki></code> → {{extract|2001-2-1|show=monthname}}
*<code><nowiki>{{extract|2001-2-1|show=a %{dayname} in %{monthname} }}</nowiki></code> → {{extract|2001-2-1|show=a %{dayname} in %{monthname} }}

Some <code>show</code> options will not produce a useful result with a partial date, for example:
*<code><nowiki>{{extract|2001|partial=on|show=juliandate}}</nowiki></code> → {{extract|2001|partial=on|show=juliandate}}
*<code><nowiki>{{extract|2001|partial=on|show=monthname}}</nowiki></code> → {{extract|2001|partial=on|show=monthname}}

== Sortable ==
The sort options are:
{| class="wikitable"
! Parameter !! Description
|-
| <code>prefix=''text''</code>|| Insert the given ''text'' before the result but after any sort key.
|-
| <code>sortable=off</code> || No sort key (default).
|-
| <code>sortable=on</code> || Output a hidden sort key for use in [[WP:SORT|sortable tables]].
|-
| <code>sortable=table</code> || Insert a sort key using table syntax <code>data-sort-value="''value''"|</code>.
|-
| <code>sortable=debug</code> || Same as <code>sortable=on</code> but the sort key is displayed for testing.
|}

The sort key is calculated from the <code>juliandate</code> value. For a partial date such as May 2016, the first day in the range is used (1 May 2016).

If wanted, <code>show=hide</code> can be used so the date is not displayed.

The <code>prefix</code> parameter allows the insertion of text that will not interfere with sorting. For example, <code><nowiki>{{extract|500 BC|prefix=c.|partial=on|sortable=on}}</nowiki></code> outputs a hidden sort key followed by "c. 500 BC".

Examples:
*<code><nowiki>{{extract|1 Jan 2001|sortable=on}}</nowiki></code> → {{extract|1 Jan 2001|sortable=on}}
*<code><nowiki>{{extract|1 Jan 2001|sortable=on|show=hide}}</nowiki></code> → {{extract|1 Jan 2001|sortable=on|show=hide}}
*<code><nowiki>{{extract|2300 BCE|partial=on|sortable=debug}}</nowiki></code> → {{extract|2300 BCE|partial=on|sortable=debug}}
*<code><nowiki>{{extract|1 Jan 2001|sortable=debug}}</nowiki></code> → {{extract|1 Jan 2001|sortable=debug}}
*<code><nowiki>{{extract|1 Jan 2001|sortable=debug|show=hide}}</nowiki></code> → {{extract|1 Jan 2001|sortable=debug|show=hide}}
*<code><nowiki>{{extract|00:12 1 Jan 2001|sortable=debug|show=hide}}</nowiki></code> → {{extract|00:12 1 Jan 2001|sortable=debug|show=hide}}

Template:Extract/doc - Revision history

Caleb Cooper: Created page with "{{documentation subpage}} {{Lua|Module:Age|Module:Date}} {{Commons Import}} '''This template can extract information from a date, or can format a date. Time units can be added..."