data/TWiki/TWikiTimeDotPm.txt
changeset 0 414e01d06fd5
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     1 ---+ Package =TWiki::Time=
       
     2 
       
     3 Time handling functions.
       
     4 
       
     5 
       
     6 %TOC%
       
     7 
       
     8 ---++ StaticMethod *parseTime* <tt>($szDate,$defaultLocal) -> $iSecs</tt>
       
     9 
       
    10 Convert string date/time string to seconds since epoch (1970-01-01T00:00:00Z).
       
    11    * =$sDate= - date/time string
       
    12 
       
    13 Handles the following formats:
       
    14 
       
    15 Default TWiki format
       
    16    * 31 Dec 2001 - 23:59
       
    17 
       
    18 TWiki format without time (defaults to 00:00)
       
    19    * 31 Dec 2001
       
    20 
       
    21 Date seperated by '/', '.' or '-', time with '.' or ':'
       
    22 Date and time separated by ' ', '.' and/or '-'
       
    23    * 2001/12/31 23:59:59
       
    24    * 2001.12.31.23.59.59
       
    25    * 2001/12/31 23:59
       
    26    * 2001.12.31.23.59
       
    27    * 2001-12-31 23:59
       
    28    * 2001-12-31 - 23:59
       
    29 
       
    30 ISO format
       
    31    * 2001-12-31T23:59:59
       
    32 ISO dates may have a timezone specifier, either Z or a signed difference
       
    33 in hh:mm format. For example:
       
    34    * 2001-12-31T23:59:59+01:00
       
    35    * 2001-12-31T23:59Z
       
    36 The default timezone is Z, unless $defaultLocal is true in which case
       
    37 the local timezone will be assumed.
       
    38 
       
    39 If the date format was not recognised, will return 0.
       
    40 
       
    41 
       
    42 
       
    43 ---++ StaticMethod *formatTime* <tt>($epochSeconds,$formatString,$outputTimeZone) -> $value</tt>
       
    44 
       
    45    * =$epochSeconds= epochSecs GMT
       
    46    * =$formatString= twiki time date format, default =$day $month $year - $hour:$min=
       
    47    * =$outputTimeZone= timezone to display, =gmtime= or =servertime=, default is whatever is set in $TWiki::cfg{DisplayTimeValues}
       
    48 =$formatString= supports:
       
    49    | $seconds | secs |
       
    50    | $minutes | mins |
       
    51    | $hours | hours |
       
    52    | $day | date |
       
    53    | $wday | weekday name |
       
    54    | $dow | day number (0 = Sunday) |
       
    55    | $week | week number |
       
    56    | $month | month name |
       
    57    | $mo | month number |
       
    58    | $year | 4-digit year |
       
    59    | $ye | 2-digit year |
       
    60    | $http | ful HTTP header format date/time |
       
    61    | $email | full email format date/time |
       
    62    | $rcs | full RCS format date/time |
       
    63    | $epoch | seconds since 1st January 1970 |
       
    64 
       
    65 
       
    66 
       
    67 ---++ StaticMethod *formatDelta* <tt>($s) -> $string</tt>
       
    68 
       
    69 Format a time in seconds as a string. For example,
       
    70 "1 day, 3 hours, 2 minutes, 6 seconds"
       
    71 
       
    72 
       
    73 
       
    74 ---++ StaticMethod *parseInterval* <tt>($szInterval) -> [$iSecs,$iSecs]</tt>
       
    75 
       
    76 Convert string representing a time interval to a pair of integers
       
    77 representing the amount of seconds since epoch for the start and end
       
    78 extremes of the time interval.
       
    79 
       
    80    * =$szInterval= - time interval string
       
    81 
       
    82 in yacc syntax, grammar and actions:
       
    83 <verbatim>
       
    84 interval ::= date                 { $$.start = fillStart($1); $$.end = fillEnd($1); }
       
    85          | date '/' date          { $$.start = fillStart($1); $$.end = fillEnd($3); }
       
    86          | 'P' duration '/' date  { $$.start = fillEnd($4)-$2; $$.end = fillEnd($4); }
       
    87          | date '/' 'P' duration  { $$.start = fillStart($1); $$.end = fillStart($1)+$4; }
       
    88          ;
       
    89 </verbatim>
       
    90 an =interval= may be followed by a timezone specification string (this is not supported yet).
       
    91 
       
    92 =duration= has the form (regular expression):
       
    93 <verbatim>
       
    94    P(<number><nameOfDuration>)+
       
    95 </verbatim>
       
    96 
       
    97 nameOfDuration may be one of:
       
    98    * y(year), m(month), w(week), d(day), h(hour), M(minute), S(second)
       
    99 
       
   100 =date= follows ISO8601 and must include hypens.  (any amount of trailing
       
   101        elements may be omitted and will be filled in differently on the
       
   102        differents ends of the interval as to include the longest possible
       
   103        interval):
       
   104 
       
   105    * 2001-01-01T00:00:00
       
   106    * 2001-12-31T23:59:59
       
   107 
       
   108 timezone is optional. Default is local time.
       
   109 
       
   110 If the format is not recognised, will return empty interval [0,0].
       
   111 
       
   112 TODO: timezone
       
   113       testing, especially on non valid strings
       
   114 
       
   115