/ 
Time-Travel-0.03
/ Time::Travel

NAME

Time::Travel - provide a tool to travel across the time for a given
distance.

SYNOPSIS

use Time::Travel;

# initialize

my $tstr = localtime;

my $time = new Time::Travel($tstr); # or

my @tlst = localtime;

my $time = new Time;:Travel(@tlst); # or

my $time = new Time::Travel(28,14,11,19,05,2003);

my $t1 = $time->land; # source

print $t1;

$time->travel(['6mo','5dy','4hr']); # travel

print $time->land();

DESCRIPTION

The Time::Travel module produces a slim, quick method to slide across the time scale over a given period (NOT a given date).

It is much simpler and shorter than the Date::Manip and Time::Piece. It creates an object which is in fact a reference to a six-member array. It is possible then to travel using this object and to land (print resulting time).

METHODS

The following methods are defined in the module:

new(@TIME | $TIME);

The constructor returns a newly created object which points at a six-member array. If the argument is a CTIME string as returned by localtime() in scalar context, it is parsed into such array using strptime() from Date::Parse. If the argument is a nine-member array as returned by localtime() in list context or any other larger than six-member list, first six members are taken. The month is considered to be in 0..11 range as it is for localtime() and the year is rebuilt into 4-digits number in case it is found to be less than 200. If the given array has less than six members then it is considered that higher precision units are omitted subsequently (i.e. if there are only 4 members they are treated as hour, day, month and year).

The created array is then validated using internal validate() function. If the validation fails, a warning is given and an undefined object is returned.

travel([Time Distance]);

This main method shifts the time stored in the object by the given margin which is passed as an array reference. The members of the margin array must be of Nxx format, where N is an integer number (might be negative) and xx is one of the following:

  • sc - seconds

  • mn - minutes

  • hr - hours

  • dy - days

  • mo - months

  • yr - years

This notation is used by GrADS (http://grads.iges.org/grads/head.html) and I find it the best and the easiest around. The items in the margin array might be in any order.

land();

After we traveled we want to land - this method constructs a CTIME compatible string and returns it, also adjusting the month that has been within the 0..1 range all the time. You can now print that string.

BUGS

I wanted this module to be small, robust and simple therefore it does not treat so many formats for input and output as other Time:: or Date:: modules do. But I am glad it is that way.

Years have a limitation set upwards to 100000 for sanity.

When reporting bugs/problems please include as much information as possible.

AUTHOR

Roman M. Parparov <romm@empire.tau.ac.il>. Special thanks to authors of the modules in SEE ALSO section.

SEE ALSO

Time::ParseDate, Date::Parse, Date::Manip, Time::DaysInMonth

COPYRIGHT

Copyright 2003 Roman M. Parparov <romm@empire.tau.ac.il>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.