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) -&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) -> $iSecs`
  18
  19 Convert string date/time to seconds since epoch.
  20
  21 - `$sDate` - date/time string
  22
  23 Handles the following formats:
  24
  25 - 31 Dec 2001 - 23:59
  26 - 2001/12/31 23:59:59
  27 - 2001.12.31.23.59.59
  28 - 2001/12/31 23:59
  29 - 2001.12.31.23.59
  30 - 2001-12-31T23:59:59Z
  31 - 2001-12-31T23:59:59+01:00
  32 - 2001-12-31T23:59Z
  33 - 2001-12-31T23:59+01:00
  34
  35 If the date format was not recognised, will return 0.
  36
  37 ## <a name="StaticMethod &lt;strong&gt;formatTime&lt;/strong&gt; ($epoc"></a> [[StaticMethod]] **formatTime** `($epochSeconds,$formatString,$outputTimeZone) -> $value`
  38
  39 - `$epochSeconds` epochSecs GMT
  40 - `$formatString` twiki time date format, default `$day $month $year - $hour:$min`
  41 - `$outputTimeZone` timezone to display, `gmtime` or `servertime`, default is whatever is set in $TWiki::cfg\{DisplayTimeValues\}
  42
  43 `$formatString` supports:
  44
  45 <table border="1" cellpadding="0" cellspacing="0">
  46   <tr>
  47     <td> $seconds </td>
  48     <td> secs </td>
  49   </tr>
  50   <tr>
  51     <td> $minutes </td>
  52     <td> mins </td>
  53   </tr>
  54   <tr>
  55     <td> $hours </td>
  56     <td> hours </td>
  57   </tr>
  58   <tr>
  59     <td> $day </td>
  60     <td> date </td>
  61   </tr>
  62   <tr>
  63     <td> $wday </td>
  64     <td> weekday name </td>
  65   </tr>
  66   <tr>
  67     <td> $dow </td>
  68     <td> day number (0 = Sunday) </td>
  69   </tr>
  70   <tr>
  71     <td> $week </td>
  72     <td> week number </td>
  73   </tr>
  74   <tr>
  75     <td> $month </td>
  76     <td> month name </td>
  77   </tr>
  78   <tr>
  79     <td> $mo </td>
  80     <td> month number </td>
  81   </tr>
  82   <tr>
  83     <td> $year </td>
  84     <td> 4-digit year </td>
  85   </tr>
  86   <tr>
  87     <td> $ye </td>
  88     <td> 2-digit year </td>
  89   </tr>
  90   <tr>
  91     <td> $http </td>
  92     <td> ful HTTP header format date/time </td>
  93   </tr>
  94   <tr>
  95     <td> $email </td>
  96     <td> full email format date/time </td>
  97   </tr>
  98   <tr>
  99     <td> $rcs </td>
 100     <td> full RCS format date/time </td>
 101   </tr>
 102   <tr>
 103     <td> $epoch </td>
 104     <td> seconds since 1st January 1970 </td>
 105   </tr>
 106 </table>
 107
 108 ## <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`
 109
 110 Format a time in seconds as a string. For example, "1 day, 3 hours, 2 minutes, 6 seconds"
 111
 112 ## <a name="StaticMethod &lt;strong&gt;parseInterval&lt;/strong&gt; ($s"></a> [[StaticMethod]] **parseInterval** `($szInterval) -> [$iSecs,$iSecs]`
 113
 114 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.
 115
 116 - `$szInterval` - time interval string
 117
 118 in yacc syntax, grammar and actions:
 119
 120     interval ::= date                 { $$.start = fillStart($1); $$.end = fillEnd($1); }
 121              | date '/' date          { $$.start = fillStart($1); $$.end = fillEnd($3); }
 122              | 'P' duration '/' date  { $$.start = fillEnd($4)-$2; $$.end = fillEnd($4); }
 123              | date '/' 'P' duration  { $$.start = fillStart($1); $$.end = fillStart($1)+$4; }
 124              ;
 125
 126 an `interval` may be followed by a timezone specification string (this is not supported yet).
 127
 128 `duration` has the form (regular expression):
 129
 130        P(<number><nameOfDuration>)+
 131
 132 nameOfDuration may be one of:
 133
 134 - y(year), m(month), w(week), d(day), h(hour), M(minute), S(second)
 135
 136 `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):
 137
 138 - 2001-01-01T00:00:00
 139 - 2001-12-31T23:59:59
 140
 141 timezone is optional and not supported yet.
 142
 143 If the format is not recognised, will return empty interval [0,0].
 144
 145 TODO: timezone testing, especially on non valid strings