TWiki/TimeSpecifications.mdwn

   1 ## <a name="Time Specifications"></a> Time Specifications
   2
   3 TWiki recognises the following formats for date/time strings. For all strings the time is optional.
   4
   5 - 31 Dec 2001 - 23:59
   6 - 2001/12/31 23:59:59
   7 - 2001.12.31.23.59.59
   8 - 2001/12/31 23:59
   9 - 2001.12.31.23.59
  10 - `2001-12-31T23:59:59` - ISO 8601 format
  11
  12 ISO dates may have a timezone specifier, either Z or a signed difference in hh:mm format. For example:
  13
  14 - 2001-12-31T23:59:59+01:00
  15 - 2001-12-31T23:59Z
  16
  17 ## <a name="Time Intervals"></a> Time Intervals
  18
  19 Some features of TWiki, such as searches, permit the specification of _time intervals_. A time interval is a period of time, such as "1337 to 1451" (the Hundred Years War) or "9th February 2005 to 26th March 2005" (the Christian season of Lent).
  20
  21 The recognised format is a [[restricted|Main/WebHome#RestrictedInterpretation]] interpretation of the [ISO standard 8601](http://www.iso.ch/iso/en/prods-services/popstds/datesandtime.html).
  22
  23 A string is accepted as a valid time interval string if it conforms to the following grammar:
  24
  25     interval ::= date
  26                | date '/' date
  27                | 'P' duration '/' date
  28                | date '/' 'P' duration
  29                ;
  30
  31     date ::= year ('-' month ('-' day ('T' hour (':' minute (':' second)))))
  32            | '$today'
  33            | '$now'
  34            ;
  35
  36     duration ::= NUM unit
  37                | duration NUM unit
  38                ;
  39
  40     unit ::= 'y' | 'm' | 'w' | 'd' | 'h' | 'M' | 'S'
  41
  42     year, month, day, hour, minute, second ::= NUM
  43
  44 An incompletely specified date will be completed by including as much time as possible.
  45
  46 For example, if the start of a date range is specified by just a year, e.g. `1999/2006`, it will be interpreted as starting at January 1st 1999, at zero hours zero minutes zero seconds. Similarly for the end of the range; `2006` will be interpreted as the last second of 2006.
  47
  48 If only one date is specified (e.g. the interval string is `1999`) it will be treated as if the same date were the start and the end i.e. `1999-1999`. Thus `1999` is interpreted as the whole of the year 1999.
  49
  50 <table border="1" cellpadding="0" cellspacing="0">
  51   <tr>
  52     <th bgcolor="#99CCCC"><strong> You write </strong></th>
  53     <th bgcolor="#99CCCC"><strong> You mean </strong></th>
  54   </tr>
  55   <tr>
  56     <td><code>2003</code></td>
  57     <td> the whole year 2003 </td>
  58   </tr>
  59   <tr>
  60     <td><code>2003-03-28T/2003-05-15</code></td>
  61     <td> from March 28th to May 15th of the year 2003 </td>
  62   </tr>
  63   <tr>
  64     <td><code>P3w/$today</code></td>
  65     <td> three weeks until today </td>
  66   </tr>
  67   <tr>
  68     <td> 2003-12-12 </td>
  69     <td> 12th Dec 2003, from 0:00 to 23:59:59 </td>
  70   </tr>
  71   <tr>
  72     <td> 2003 </td>
  73     <td> any time in the year 2003 </td>
  74   </tr>
  75   <tr>
  76     <td> 2003/P20w </td>
  77     <td> the first 20 weeks of the year 2003 </td>
  78   </tr>
  79   <tr>
  80     <td> P20w/2003 </td>
  81     <td> the last 20 weeks of the year 2003 </td>
  82   </tr>
  83   <tr>
  84     <td> $today </td>
  85     <td> any second during the present day </td>
  86   </tr>
  87   <tr>
  88     <td> P2d/$today </td>
  89     <td> today and yesterday </td>
  90   </tr>
  91   <tr>
  92     <td> P1d/$now </td>
  93     <td> the last 24 hours </td>
  94   </tr>
  95   <tr>
  96     <td> $now/P50y </td>
  97     <td> the next 50 years </td>
  98   </tr>
  99 </table>
 100
 101 Further examples can be seen [here](http://www.iso.ch/iso/en/prods-services/popstds/datesandtime.html#three).
 102
 103 <a name="RestrictedInterpretation"></a>
 104
 105 ### <a name="Limitations"></a> Limitations
 106
 107 If you are entering a date at both ends of the time interval string, the end date must include all leading fields, even if these are the same as in the start date. This limitation forms a proper restriction to the ISO8601 standard. i.e. ISO8601 specifies that `2003-12-12/14` means 12th Dec 2003 00:00 to 14th Dec 2003 23:59:59. However this shorthand is not supported by TWiki and must be written as `2003-12-12/2003-12-14`