TWiki/TWikiTimeDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Time="></a> Package =TWiki::Time
   2
   3 Time handling functions.
   4
   5 <div>
   6   <ul>
   7     <li><a href="#Package =TWiki::Time="> Package TWiki::Time</a><ul>
   8         <li><a href="#StaticMethod <strong>parseTime</strong> ($szDat"> StaticMethod parseTime <tt>($szDate,$defaultLocal) -&gt; $iSecs</tt></a></li>
   9         <li><a href="#StaticMethod <strong>formatTime</strong> ($epoc"> StaticMethod formatTime <tt>($epochSeconds,$formatString,$outputTimeZone) -&gt; $value</tt></a></li>
  10         <li><a href="#StaticMethod <strong>formatDelta</strong> ($s)"> StaticMethod formatDelta <tt>($s) -&gt; $string</tt></a></li>
  11         <li><a href="#StaticMethod <strong>parseInterval</strong> ($s"> StaticMethod parseInterval <tt>($szInterval) -&gt; [$iSecs,$iSecs]</tt></a></li>
  12       </ul>
  13     </li>
  14   </ul>
  15 </div>
  16
  17 ## <a name="StaticMethod &lt;strong&gt;parseTime&lt;/strong&gt; ($szDat"></a> [[StaticMethod]] **parseTime** `($szDate,$defaultLocal) -> $iSecs`
  18
  19 Convert string date/time string to seconds since epoch (1970-01-01T00:00:00Z).
  20
  21 - `$sDate` - date/time string
  22
  23 Handles the following formats:
  24
  25 Default TWiki format
  26
  27 - 31 Dec 2001 - 23:59
  28
  29 TWiki format without time (defaults to 00:00)
  30
  31 - 31 Dec 2001
  32
  33 Date seperated by '/', '.' or '-', time with '.' or ':' Date and time separated by ' ', '.' and/or '-'
  34
  35 - 2001/12/31 23:59:59
  36 - 2001.12.31.23.59.59
  37 - 2001/12/31 23:59
  38 - 2001.12.31.23.59
  39 - 2001-12-31 23:59
  40 - 2001-12-31 - 23:59
  41
  42 ISO format
  43
  44 - 2001-12-31T23:59:59
  45
  46 ISO dates may have a timezone specifier, either Z or a signed difference in hh:mm format. For example:
  47
  48 - 2001-12-31T23:59:59+01:00
  49 - 2001-12-31T23:59Z
  50
  51 The default timezone is Z, unless $defaultLocal is true in which case the local timezone will be assumed.
  52
  53 If the date format was not recognised, will return 0.
  54
  55 ## <a name="StaticMethod &lt;strong&gt;formatTime&lt;/strong&gt; ($epoc"></a> [[StaticMethod]] **formatTime** `($epochSeconds,$formatString,$outputTimeZone) -> $value`
  56
  57 - `$epochSeconds` epochSecs GMT
  58 - `$formatString` twiki time date format, default `$day $month $year - $hour:$min`
  59 - `$outputTimeZone` timezone to display, `gmtime` or `servertime`, default is whatever is set in $TWiki::cfg\{DisplayTimeValues\}
  60
  61 `$formatString` supports:
  62
  63 <table border="1" cellpadding="0" cellspacing="0">
  64   <tr>
  65     <td> $seconds </td>
  66     <td> secs </td>
  67   </tr>
  68   <tr>
  69     <td> $minutes </td>
  70     <td> mins </td>
  71   </tr>
  72   <tr>
  73     <td> $hours </td>
  74     <td> hours </td>
  75   </tr>
  76   <tr>
  77     <td> $day </td>
  78     <td> date </td>
  79   </tr>
  80   <tr>
  81     <td> $wday </td>
  82     <td> weekday name </td>
  83   </tr>
  84   <tr>
  85     <td> $dow </td>
  86     <td> day number (0 = Sunday) </td>
  87   </tr>
  88   <tr>
  89     <td> $week </td>
  90     <td> week number </td>
  91   </tr>
  92   <tr>
  93     <td> $month </td>
  94     <td> month name </td>
  95   </tr>
  96   <tr>
  97     <td> $mo </td>
  98     <td> month number </td>
  99   </tr>
 100   <tr>
 101     <td> $year </td>
 102     <td> 4-digit year </td>
 103   </tr>
 104   <tr>
 105     <td> $ye </td>
 106     <td> 2-digit year </td>
 107   </tr>
 108   <tr>
 109     <td> $http </td>
 110     <td> ful HTTP header format date/time </td>
 111   </tr>
 112   <tr>
 113     <td> $email </td>
 114     <td> full email format date/time </td>
 115   </tr>
 116   <tr>
 117     <td> $rcs </td>
 118     <td> full RCS format date/time </td>
 119   </tr>
 120   <tr>
 121     <td> $epoch </td>
 122     <td> seconds since 1st January 1970 </td>
 123   </tr>
 124 </table>
 125
 126 ## <a name="StaticMethod &lt;strong&gt;formatDelta&lt;/strong&gt; ($s)"></a><a name="StaticMethod &lt;strong&gt;formatDelta&lt;/strong&gt; ($s) "></a> [[StaticMethod]] **formatDelta** `($s) -> $string`
 127
 128 Format a time in seconds as a string. For example, "1 day, 3 hours, 2 minutes, 6 seconds"
 129
 130 ## <a name="StaticMethod &lt;strong&gt;parseInterval&lt;/strong&gt; ($s"></a> [[StaticMethod]] **parseInterval** `($szInterval) -> [$iSecs,$iSecs]`
 131
 132 Convert string representing a time interval to a pair of integers representing the amount of seconds since epoch for the start and end extremes of the time interval.
 133
 134 - `$szInterval` - time interval string
 135
 136 in yacc syntax, grammar and actions:
 137
 138     interval ::= date                 { $$.start = fillStart($1); $$.end = fillEnd($1); }
 139              | date '/' date          { $$.start = fillStart($1); $$.end = fillEnd($3); }
 140              | 'P' duration '/' date  { $$.start = fillEnd($4)-$2; $$.end = fillEnd($4); }
 141              | date '/' 'P' duration  { $$.start = fillStart($1); $$.end = fillStart($1)+$4; }
 142              ;
 143
 144 an `interval` may be followed by a timezone specification string (this is not supported yet).
 145
 146 `duration` has the form (regular expression):
 147
 148        P(<number><nameOfDuration>)+
 149
 150 nameOfDuration may be one of:
 151
 152 - y(year), m(month), w(week), d(day), h(hour), M(minute), S(second)
 153
 154 `date` follows ISO8601 and must include hypens. (any amount of trailing elements may be omitted and will be filled in differently on the differents ends of the interval as to include the longest possible interval):
 155
 156 - 2001-01-01T00:00:00
 157 - 2001-12-31T23:59:59
 158
 159 timezone is optional. Default is local time.
 160
 161 If the format is not recognised, will return empty interval [0,0].
 162
 163 TODO: timezone testing, especially on non valid strings