/ 
Time-LST-0.037
River stage zero No dependents
/ Time::LST

NAME

Time::LST - Convert date/time representations to local sidereal time via Astro-Time and other Date/Time modules

VERSION

This is documentation for Version 0.037 of Time::LST (2009.09.25).

SYNOPSIS

use Time::LST qw(datetime2lst filestat2lst now2lst time2lst ymdhms2lst);

$long = -3.21145; # London, in degrees

$lst_from_string = datetime2lst('1942:8:7T17:00:00', -3.21145, 'BST'); # note approx only for pre-1970
$data_mod_lst    = filestat2lst('mod', 'valid_path_to_a_file', $long); # or filestat2lst('create', $path, $long)
$now_as_lst      = time2lst(time(), $long);
$lst_from_aref   = ymdhms2lst([2006, 11, 21, 12, 15, 0], $long, 'EADT'); # optional timezone

DESCRIPTION

This is essentially no more than a wrapper to a number of Astro::Time methods that simplifies conversion into local sidereal time of a datetime representation, such as returned by Date::Calc), or seconds since the epoch, such as returned by time, or stat fields).

Manditorily, you need to know the longitude (in degrees) of the space relevant to your time.

Give a filepath to get the LST of its last modified time, or readily see what the LST is now.

Get an accurate representation of the relevant datetime ("now," a given time, or a file's creation or modified time) in so many "seconds since the epoch", taking TimeZone into account.

Optionally, a timezone string in some methods can be helpful for accurately parsing (solar) clock-and-calendar times.

METHODS

Methods need to be explicitly imported in the use statement. None are exported by default.

All methods expect a longitude, either in degrees.decimal or degrees:minutes:seconds - e.g. -3.21145 (London), 147.333 (Hobart, Tasmania) - or degrees+minutes - e.g., 147:19:58.8 (Hobart). See the str2turn method in the Astro::Time module for valid representations of longitude. Note, however, the degrees, not hours, are here supported.

LST is always returned in the format H:M:S, hours ranging from 0 (12 AM) to 23 (11 PM).

datetime2lst

$lst = datetime2lst('1942:12:27:16:04:07', -3.21145, 'BST')

Returns LST on the basis of parsing a datetime string into "seconds since the epoch".

The first two values to the function are manditory.

Firstly, there should be passed a string in any form parseable by Date::Parse, e.g., "1995:01:24T09:08:17.1823213"; "21 dec 17:05"; "16 Nov 94 22:28:20 PST". There are system limitations in handling years outside of a certain range. Years less than 1000 will not parse. Years between 1000 and 1969, inclusive, will be rendered as 1970, and those greater than 2037 will be rendered as 2037. (LST deviates by only about 3 minutes from 1970 to 2037).

A second mandatory value to the function is the longitude in degrees.

Then follow non-mandatory values.

A timezone string can be specified as an optional third value for accurate parsing of the datetime string into "seconds since the epoch"; the local timezone is used if this is not specified. Valid representations of Timezone include the likes of "AEDT" and "EST" (parsed by Date::Parse; i.e., a capital-letter string of 3-5 letters in length), or "Australia/Hobart" (parsed by DateTime).

filestat2lst

$lst = filestat2lst('create|mod', $path, $long)

Returns LST corresponding to the creation or modification time of a given path.

First argument equals either 'c' or 'm' (only the first letter is looked-up, case-insensitively). This, respectively, determines access to ctime (element 10) and mtime (element 9) returned by Perl's internal stat function. Note that only modification-time is truly portable across systems; see Files and Filesystems in perlport (paras 6 and 7).

The path must be to a "real" file, not a link to a file.

now2lst #--------------------------------

$lst = now2lst($long)

Returns local now (as returned by perl's time()) as LST, given longitude in degrees.

Same as going: time2lst(time(), $long).

ymdhms2lst #--------------------------------

$lst = ymdhms2lst([2006, 8, 21, 12, 3, 0], $long, $timezone)

Returns LST corresponding to a datetime array reference of the following elements:

  [
   year (4-digit only),
   month-of-year (i.e., nth month (ranging 1-12, or 01-12), not month index as returned by localtime()),
   day-of-month (1-31 (or 01-31)),
   hour (0 - 23),
   minutes,
   seconds
  ]

Range-checking of these values is performed by Astro::Time itself; digital representations such as "08" or "00" are stripped of leading zeroes for parseability to another module (so there's no need to add them as fillers). Ensure that the year is 4-digit representation.

A value for longitude is required secondary to this datetime array.

A final timezone string - e.g., 'EST', 'AEDT' - is optional. Sending nothing, or an erroneous timezone string, assumes present local timezone. The format is as used by Date::Parse or DateTime; UTC+n format does not parse.

time2lst #--------------------------------

$lst = time2lst('1164074032', $long)

Returns LST given seconds since the epoch. If you have a time in localtime format, see Time::localtime to convert it into the format that can be used with this function.

EXAMPLE

Here and Now

Use HeavensAbove and Date::Calc to blindly get the present LST.

use Time::LST qw(ymdhms2lst);
use Date::Calc qw(Today_and_Now);
use WWW::Gazetteer::HeavensAbove;

my $atlas = WWW::Gazetteer::HeavensAbove->new;
my $cities = $atlas->find('Hobart', 'AU'); # cityname, ISO country code
# Assume call went well, and the first city returned is "here".

print 'The LST here and now is ' . ymdhms2lst([Today_and_Now()], $cities->[0]->{'longitude'});

SEE ALSO

Astro::Time : the present module uses the turn2str, hms2time, str2turn, cal2mjd, and mjd2lst methods to eventually get the LST for a given time.

Date::Parse : the present module uses the str2time method to parse datetime strings to a format that can be readily converted to LST via ymdhms_2_time(). See this module for parsing other datetime representations into a "time" format that can be sent to time2lst().

WWW::Gazetteer::HeavensAbove : see this module for determining longitudes of a certain city, or visit http://www.heavens-above.com/countries.asp.

http://home.tiscali.nl/~t876506/TZworld.html for valid timezone strings.

TO DO/ISSUES

Timezone handling might need higher sensitivity.

Epoch-external periods merit a better solution than reduction to the minimum/maximum.

ACKNOWLEDGEMENT

The author of Astro::Time kindly looked over the basic conversion wrap-up. Any errors are fully those of the present author.

AUTHOR/LICENSE

rgarton AT cpan DOT org

This program is free software. It may be used, redistributed and/or modified under the same terms as Perl-5.6.1 (or later) (see http://www.perl.com/perl/misc/Artistic.html).

Disclaimer

To the maximum extent permitted by applicable law, the author of this module disclaims all warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with regard to the software and the accompanying documentation.