Difference between revisions of "Template:Extract/doc"

From blackwiki
Jump to navigation Jump to search
imported>Johnuniq
(correction for dayofyear)
imported>Johnuniq
(bunch more)
Line 1: Line 1:
'''This template is under development, see [[Template talk:Time interval|talk]].'''
+
{{Lua|Module:Age|Module:Date}}
 
+
'''This template can extract information from a date, or can format a date. Time units can be added to a date.'''
This template can extract information from a date, or can format a date. Time units can be added to a date.
 
  
 
== Syntax ==
 
== Syntax ==
Line 10: Line 9:
 
*<code>fix=on</code> • Adjust invalid 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>partial=on</code> • Accept a year only, or a year and month only.
*<code>show=''code for 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>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>).
  
The date can be entered as the first parameter, or year/month/day components of the date can be entered in separate parameters.
+
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.
 
A valid date must be specified. Dates are [[Coordinated Universal Time|UTC]]—local times and time zones are not supported.
  
By default, the date is displayed in dmy format, for example, "12 November 2015".
+
Dates from 9999&nbsp;BCE to 9999&nbsp;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.
 
A date can include an era or a time, and a variety of formats are accepted.
Line 40: Line 43:
 
| <code>&#123;&#123;extract&#124;BC 1 Feb 120&#125;&#125;</code>              || <code>&#123;&#123;extract&#124;-119&#124;2&#124;1&#125;&#125;</code>
 
| <code>&#123;&#123;extract&#124;BC 1 Feb 120&#125;&#125;</code>              || <code>&#123;&#123;extract&#124;-119&#124;2&#124;1&#125;&#125;</code>
 
|}
 
|}
 +
 +
The last example above uses the rule:
 +
:'''''n''''' BC is year '''1 − ''n'''''
 +
Year 0 refers to 1&nbsp;BC, and year −1 is 2&nbsp;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 ==
 
== Add ==
Line 57: Line 77:
 
*<code><nowiki>{{extract|2004-04-03|add=28d}}</nowiki></code> → {{extract|2004-04-03|add=28d}}
 
*<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=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=-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=-912345d}}</nowiki></code> → {{extract|2004-04-03|add=-912345d}}
Line 63: Line 84:
 
*<code><nowiki>{{extract|2004-04-30|add=-2m}}</nowiki></code> → {{extract|2004-04-30|add=-2m}}
 
*<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=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}}
+
*<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 ==
 
== Fix ==

Revision as of 11:33, 22 June 2016

This template can extract information from a date, or can format a date. Time units can be added to a date.

Syntax

  • {{extract|date|options}}

The following options are available:

  • add=periods to add • Add/subtract time units.
  • fix=on • Adjust invalid time units.
  • partial=on • Accept a year only, or a year and month only.
  • show=what to display • Specifies what should be extracted (such as dayname), or how to format the date (such as mdy).

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:

  • {{extract|2015-11-12}} → 12 November 2015

Date

A valid date must be specified. Dates are 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 julian 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.

A date as a single parameter Components of a date in separate parameters
{{extract|1900-02-01}} {{extract|1900|02|01}}
{{extract|1900-2-1 14:45}} {{extract|1900|2|1|14|45}}
{{extract|1 FEB 1900}} {{extract|1900|FEB|1}}
{{extract|February 1, 1900}} {{extract|1900|February|1}}
{{extract|Feb 1 1900 14:45}} {{extract|1900|Feb|1|14|45}}
{{extract|2:45 pm February 1 1900}} {{extract|1900|February|1|14|45}}
{{extract|1 February 1900 2:45 p.m.}} {{extract|1900|February|1|14|45}}
{{extract|BC 1 Feb 120}} {{extract|-119|2|1}}

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.

  • {{extract|juliandate|2451545}} → 1 January 2000 (Julian day 2451545 is noon 1 January 2000 UTC in the Gregorian calendar)
  • {{extract|juliandate|julian|2451545}} → 19 December 1999 (which is 19 December 1999 in the Julian calendar)
  • {{extract|currentdate}} → 29 December 2025 (the date shown is when this documentation page was last purged)
  • {{extract|currentdatetime}} → 14:30 29 December 2025

The following confirms that 16 February 2000 in the Julian calendar was 29 February 2000 in the Gregorian calendar.

  • {{extract|julian|Feb 16, 2000|show=juliandate}} → 2451604 (Julian calendar was specified)
  • {{extract|juliandate|2451604}} → 29 February 2000 (Gregorian calendar by default)

16 February 2000 in the Julian calendar can be converted to the Gregorian calendar in one line:

  • {{extract|juliandate|{{extract|julian|16 Feb 2000|show=juliandate}}}} → 29 February 2000

Add

These time units can be added to a date:

  • y years
  • m months
  • d days
  • h hours
  • min minutes
  • s 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:

  • {{extract|2004-04-03|add=28d}} → 1 May 2004
  • {{extract|2004-04-03|add=3m 28d}} → 31 July 2004
  • {{extract|2004-04-03|add=28d 3m}} → 1 August 2004 (the order in which units are added changes the result)
  • {{extract|2004-04-03|add=-3d}} → 31 March 2004
  • {{extract|2004-04-03|add=-912345d}} → 5 May 495 BC
  • {{extract|2004-04-03|add=250h}} → 10:00 13 April 2004
  • {{extract|2004-04-03|add=-2.5h}} → 21:30 2 April 2004
  • {{extract|2004-04-30|add=-2m}} → 29 February 2004
  • {{extract|2004-04-03|add=2y 3m 4d}} → 7 July 2006
  • {{extract|2004-04-03|add=5.75d}} → 18:00 8 April 2004 (years and months are integer only)

Fix

By default, the date entered must be valid. If fix=on 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 -1.

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

Examples:

  • {{extract|2001|5|31|fix=on}} → 31 May 2001 (no fix is required)
  • {{extract|2001|5|0|fix=on}} → 30 April 2001
  • {{extract|2001|5|-1|fix=on}} → 29 April 2001
  • {{extract|2001|125|-1000|fix=on}} → 3 August 2008
  • {{extract|2001|0|12|fix=on}} → 12 December 2000
  • {{extract|2016|3|0|fix=on}} → 29 February 2016

Partial

If partial=on is used, the date may consist of a year only, or a year and month only. Addition is not supported for a partial date.

  • {{extract|2001|5|partial=on}} → May 2001
  • {{extract|2016|partial=on|show=isleapyear}} → 1

Show

These are most of the show parameters that can be used:

Parameter Description
show=year year
show=month month (1 to 12)
show=day day of month (1 to 31)
show=hour hour (0 to 23)
show=minute minute (0 to 59)
show=second second (0 to 59)
show=dayabbr abbreviated name of day of week
show=dayname full name of day of week
show=dayofweek day-of-week (0=Sunday to 6=Saturday)
show=dayofweekiso day-of-week (1=Monday to 7=Sunday)
show=dayofyear day-of-year (1 to 366)
show=era an era code such as BC or BCE
show=format code for the detected format of the input date (dmy, mdy, ymd)
show=gsd Gregorian serial date
show=juliandate Julian day
show=isleapyear 1 if the date is in a leap year; 0 otherwise
show=monthabbr abbreviated name of month
show=monthdays number of days in the month of the date
show=monthname full name of month
show=dmy show date as "day month year" (default)
show=mdy show date as "month day, year"
show=ymd show date as "year-month-day"

Examples:

  • {{extract|1 Feb 2001}} → 1 February 2001
  • {{extract|FEB 1 2001}} → 1 February 2001
  • {{extract|2001-2-1}} → 1 February 2001
  • {{extract|1 Feb 2001|show=format}} → dmy
  • {{extract|FEB 1 2001|show=format}} → mdy
  • {{extract|2001-2-1|show=format}} → ymd
  • {{extract|1 Feb 2001|show=mdy}} → February 1, 2001
  • {{extract|1 Feb 2001|show=ymd}} → 2001-02-01
  • {{extract|June 30, 2001|show=dayname}} → Saturday
  • {{extract|June 30, 2001|show=dayofyear}} → 181
  • {{extract|2001-2-1|show=monthname}} → February
  • {{extract|2001-2-1|show=a %{dayname} in %{monthname} }} → a Thursday in February