NAME
Time::LST - Convert datetime representations to local sidereal time via Astro-Time
VERSION
This is documentation for Version 0.01 of Time::LST (2006.11.22).
SYNOPSIS
use Time::LST qw(filestat_2_lst time_2_lst ymdhms_2_lst);
$path = 'valid_path_to_a_file';
$long = -3.21145; # London, in degrees
$lst = filestat_2_lst('mod', $path, $long); # or filestat_2_lst('create', $path, $long)
$lst = time_2_lst(time(), $long);
$lst = ymdhms_2_lst([2006, 11, 21, 12, 15, 0], $long);
print $lst;DESCRIPTION
A wrapper to a number of Astro::Time methods that simplifies conversion of a datetime array (such as returned by Date::Calc), or time in seconds since the epoch (as returned by time, or stat fields), into local sidereal time (in hours, minutes and seconds). Give a filepath to get the LST of its last modified time, or see what the LST is now. Essentially, you need to know the longitude (in degrees) of the space relevant to your time.
METHODS
Methods need to be explicitly imported in the use statement. None are exported by default.
All methods expect a longitude in degrees, e.g. -3.21145 (London), 147.333 (Hobart, Tasmania).
LST is always returned in the format H:M:S, hours ranging from 0 (12 AM) to 23 (11 PM).
filestat_2_lst
$lst = filestat_2_lst('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.
time_2_lst
$lst = time_2_lst('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.
ymdhms_2_lst
$lst = ymdhms_2_lst([2006, 8, 21, 12, 3, 0], $long)Returns LST corresponding to a datetime given as an array reference of the following elements:
[year (2 or 4-digit), month-of-year (i.e., nth month, not element number returned by localtime()), day-of-month, hour (0 - 23), minutes, seconds]
Range-checking of these values is performed by Astro::Time itself.
EXAMPLE
Here and Now
Use Date::Calc and HeavensAbove to get the present LST.
use Time::LST qw(ymdhms_2_lst);
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 all went well, and the first city returned is "here".
print 'The LST here and now is ' . ymdhms_2_lst([Today_and_Now()], $cities->[0]->{'longitude'});SEE ALSO
Astro::Time : the present module uses the hms2time, str2turn, turn2str and cal2lst methods to eventually get the LST for a given time.
WWW::Gazetteer::HeavensAbove : see this module for determining longitudes of a certain city, or visit http://www.heavens-above.com/countries.asp.
AUTHOR
Roderick Garton, <rgarton@utas_DOT_edu_DOT_au>
COPYRIGHT/LICENSE/DISCLAIMER
Copyright (C) 2006 Roderick Garton
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.
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.