home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / Time.pm < prev    next >
Text File  |  1999-04-17  |  6KB  |  187 lines
  1. NAME
  2.     RISCOS::Time -- perl interface to RISC OS time SWIs
  3.  
  4. SYNOPSIS
  5.         use RISCOS::Time qw (time2utc time2local);
  6.         print 'symtable updated ', scalar time2local $time;
  7.         print 'script started ' . time2utc (0);    # Auto converts from "age"
  8.  
  9.  
  10. DESCRIPTION
  11.     This module provides perl interface to the SWIs
  12.     `OS_ConvertStandardDateAndTime',
  13.     `Territory_ConvertTimeToUTCOrdinals' and
  14.     `Territory_ConvertTimeToOrdinals' and functions to convert
  15.     between different formats for storing time information.
  16.  
  17.     Time formats currently understood are
  18.  
  19.     * numeric ages as returned by perl's `-A', `-C' and `-M' functions
  20.  
  21.     4 byte scalars - Unix times, seconds starting from 1st January 1970
  22.  
  23.     5 byte scalars - RISC OS times, centiseconds starting from 1st January 1900
  24.  
  25.     6 byte scalars - RISC OS times, as stored in `ALF' files.
  26.  
  27.  
  28.     Clearly it is not possible to automatically distinguish between
  29.     all these formats so where guessing is necessary the following
  30.     heuristics are used:
  31.  
  32.     *   If *time* is composed soley of numeric characters (0-9, "-" and
  33.         ".") then it is assumed to be an age in days since the time
  34.         the script started running (see the "$^T" entry in the
  35.         perlvar manpage). Clearly there is possible ambiguity with
  36.         RISC OS 5 byte ages that happen to be eqactly 5 characters
  37.         and composed of legal numeric characters. However the most
  38.         recent 5 byte time which could be confused is `"99999"',
  39.         23:17:53.85 on Friday 18th November 1977, which is likely to
  40.         predate most stamped files by about a decade.
  41.  
  42.     *   Otherwise `if (length $time == 5)' then `$time' is assumed to be
  43.         a 5 byte RISC OS time, encoded as centiseconds since
  44.         1900/1/1.
  45.  
  46.     *   `if (length $time == 4)' then `$time' is taken to be a 4 byte
  47.         Unix time, seconds since 1970/1/1 `pack'ed as `'I''.
  48.  
  49.     *   `if (length $time == 6)' then `$time' is expected to be a 6 byte
  50.         time as stored in `ALF' files, also centiseconds since
  51.         1900/1/1. If the MSB is not 0 the time is rejected,
  52.         otherwise it is treated as the equivalent 5 byte RISC OS
  53.         time.
  54.  
  55.  
  56.   SWI interface
  57.  
  58.     As the SWI interface functions are expect to be used with native
  59.     times if `length $time == 5' then it is taken as a RISC OS time,
  60.     taking priority over the guessing heuristic.
  61.  
  62.     standard_date_and_time <time>
  63.         calls `OS_ConvertStandardDateAndTime' for *time*, returning
  64.         the string representation of that time for the local
  65.         timezone (the format being set by `<Sys$DateFormat>').
  66.  
  67.     time2utc <time>
  68.         calls `Territory_ConvertTimeToUTCOrdinals' for *time*,
  69.         returning an array of integers, adjusted to be consistent
  70.         with the return array from `gmtime'.
  71.  
  72.             #  0    1    2     3     4    5     6     7
  73.             ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday) = time2utc($time);
  74.  
  75.  
  76.         In particular this means that `$mon' has the range 0..11 and
  77.         `$wday' has the range 0..6 with Sunday as day 0. Note
  78.         `$year' is the number of years since 1900, not simply the
  79.         last two digits of the year. If `length $time == 4' calls
  80.         `gmtime' directly, but drops the 9th element ("is daylight
  81.         saving time").
  82.  
  83.     time2local <time> [, <territory>]
  84.         calls `Territory_ConvertTimeToOrdinals' for *time* to
  85.         convert to local times. In scalar context behaves as a call
  86.         to `standard_date_and_time', in array context returns an
  87.         array as described in `time2utc'. If `length $time == 4'
  88.         calls `localtime' directly. *territory* defaults to `-1' -
  89.         the current territory.
  90.  
  91.         Support for territories other than `-1' (the current
  92.         territory) is rather limited - currently territories may
  93.         only be used in array context and must be specified by
  94.         number only, rather than name. Calls in scalar context may
  95.         only use the current territory. (Otherwise the script `die's
  96.         with an error).
  97.  
  98.     time2_raw <swi_number>, <time> [, <territory>]
  99.         calls the supplied SWI (which is expected to be
  100.         `Territory_ConvertTimeToUTCOrdinals' or
  101.         `Territory_ConvertTimeToOrdinals') and returns an array of
  102.         integers
  103.  
  104.             #  0     1    2     3     4    5    6     7    8
  105.             ($csec,$sec,$min,$hour,$mday,$mon,$year,$wday,$yday)
  106.  
  107.  
  108.         where the ranges for `$mon', `$wday' and `$yday' run from 1
  109.         upwards (*c.f.* 0 upwards for the other subroutines and the
  110.         perl builtins) and `$year' is the full Gregorian year
  111.         (rather then the number of years since 1900).
  112.  
  113.  
  114.     Values are returned consistent with ANSI C and perl's idea of
  115.     the base values for days of the week, days of the year *etc.*
  116.     from `time2utc' and `time2local' - the native RISC OS values are
  117.     available from `time2_raw'.
  118.  
  119.   Conversion functions
  120.  
  121.     13 functions are provided to convert between different time
  122.     formats. In scalar context all convert only the first argument,
  123.     in list context a list of conversions corresponding to the
  124.     argument list.
  125.  
  126.     time_guess2riscos
  127.         Each argument is processed according to the guessing
  128.         heuristics to determine which conversion to use.
  129.  
  130.     time_age2cs
  131.  
  132.     time_age2riscos
  133.  
  134.     time_age2unix
  135.  
  136.     time_cs2age
  137.  
  138.     time_cs2riscos
  139.  
  140.     time_cs2unix
  141.  
  142.     time_riscos2age
  143.  
  144.     time_riscos2cs
  145.  
  146.     time_riscos2unix
  147.  
  148.     time_unix2age
  149.  
  150.     time_unix2cs
  151.  
  152.     time_unix2riscos
  153.         Arguments are converted from the first named format to the
  154.         second, where formats are
  155.  
  156.     age     numeric ages as returned by perl's `-A', `-C' and `-M'
  157.             functions (see the "-X" entry in the perlfunc manpage)in
  158.             days since the script start time (`$^T').
  159.  
  160.     cs      centiseconds since 1900/1/1 expressed as a number.
  161.  
  162.     riscos  centiseconds since 1900/1/1 packed as 5 bytes.
  163.  
  164.     unix    seconds since 1970/1/1 packed as 4 bytes.
  165.  
  166.  
  167.   Constants
  168.  
  169.     `RISCOS::Time' is able to export these "useful" constants:
  170.  
  171.     $s_1900to1970
  172.         `2208988800', the number of seconds between Janaury 1st 1900
  173.         and 1970.
  174.  
  175.     $seconds_per_day
  176.         `86400', the number of seconds in a day.
  177.  
  178.  
  179. BUGS
  180.     Support for territories other than the current territory is very
  181.     limited. It might help if Acorn supplied more than one territory
  182.     on the standard UK machine.
  183.  
  184. AUTHOR
  185.     Nicholas Clark <nick@unfortu.net>
  186.  
  187.