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

NAME

Time::LST - Convert datetime representations to local sidereal time via Astro-Time

VERSION

This is documentation for Version 0.02 of Time::LST (2006.12.08).

SYNOPSIS

use Time::LST qw(filestat_2_lst now_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); # "now" in LST
$lst = ymdhms_2_lst([2006, 11, 21, 12, 15, 0], $long, 'eadt'); # optional timezone

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 readily see what the LST is now.

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

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

My original intention was to be able to get LST for clock-times occurring in the UK during World War 2, when double daylight saving time (+2 hours from GMT) was occasionally in force. This was outside of normal timezone-conversion solutions. This is now simply possible via the ymdhms_2_lst() method.

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).

datetime_2_lst

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

Returns LST on the basis of parsing a datetime string into "seconds since the epoch". This string can be in any form parseable by Date::Parse. Note that 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 annually deviates by only about 3 minutes from 1970 to 2037).

Longitude in degrees is mandatory.

A timezone string can be specified as an optional third argument for accurate parsing of the datetime string into "seconds since the epoch"; the local timezone is used if this is not specified. Valid representations 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).

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.

now_2_lst

$lst = now_2_lst($long)

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

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

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, $timezone)

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

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

Range-checking of these values is performed by Astro::Time itself. Ensure that the year is 4-digit representation, and do not send the likes of "08" for 8.

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.

EXAMPLE

Here and Now

Use HeavensAbove and Date::Calc to blindly 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 call 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 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 time_2_lst().

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.

AUTHOR

Roderick Garton, <rgarton@utas_DOT_edu_DOT_au>

ACKNOWLEDGEMENT

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

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.