NAME

Data::Tools::Time provides set of basic functions for time processing.

SYNOPSIS

use Data::Tools::Time qw( :all );  # import all functions
use Data::Tools::Time;             # the same as :all :) 
use Data::Tools::Time qw( :none ); # do not import anything

# --------------------------------------------------------------------------

my $time_diff_str     = unix_time_diff_in_words( $time1 - $time2 );
my $time_diff_str_rel = unix_time_diff_in_words_relative( $time1 - $time2 );

# --------------------------------------------------------------------------
  
my $date_diff_str     = julian_date_diff_in_words( $date1 - $date2 );
my $date_diff_str_rel = julian_date_diff_in_words_relative( $date1 - $date2 );

# --------------------------------------------------------------------------

# return seconds after last midnight, i.e. current day time
my $seconds_in_the_current_day = get_local_time_only()

# returns current julian day
my $jd = get_local_julian_day()

# returns current year
my $year = get_local_year()

# gets current julian date, needs Time::JulianDay
my $jd = local_julian_day( time() );
# or
my $jd = get_local_julian_day();

# move current julian date to year ago, one month ahead and 2 days ahead
$jd = julian_date_add_ymd( $jd, -1, 1, 2 );

# get year, month and day from julian date
my ( $y, $m, $d ) = julian_date_to_ymd( $jd );

# get julian date from year, month and day
$jd = julian_date_from_ymd( $y, $m, $d );

# move julian date ($jd) to the first day of its current month
$jd = julian_date_goto_first_dom( $jd );

# move julian date ($jd) to the last day of its current month
$jd = julian_date_goto_last_dom( $jd );

# get day of week for given julian date ( 0 => Mon .. 6 => Sun )
my $dow = julian_date_get_dow( $jd );
print( ( qw( Mon Tue Wed Thu Fri Sat Sun ) )[ $dow ] . "\n" );

# get month days count for the given julian date's month
my $mdays = julian_date_month_days( $jd );

# get month days count for the given year and month
my $mdays = julian_date_month_days_ym( $y, $m );

FUNCTIONS

unix_time_diff_in_words( $unix_time_diff )

Returns human-friendly text for the given time difference (in seconds). This function returns absolute difference text, for relative (before/after/ago/in) see unix_time_diff_in_words_relative().

unix_time_diff_in_words_relative( $unix_time_diff )

Same as unix_time_diff_in_words() but returns relative text (i.e. with before/after/ago/in)

julian_date_diff_in_words( $julian_date_diff );

Returns human-friendly text for the given date difference (in days). This function returns absolute difference text, for relative (before/after/ago/in) see julian_day_diff_in_words_relative().

julian_date_diff_in_words_relative( $julian_date_diff );

Same as julian_date_diff_in_words() but returns relative text (i.e. with before/after/ago/in)

TODO

* support for language-dependent wording (before/ago)
* support for user-defined thresholds (48 hours, 2 months, etc.)

REQUIRED MODULES

Data::Tools::Time uses:

* Data::Tools (from the same package)
* Date::Calc
* Time::JulianDay

TEXT TRANSLATION NOTES

time/date difference wording functions does not have translation functions and return only english text. This is intentional since the goal is to keep the translation mess away but still allow simple (yet bit strange) way to translate the result strings with regexp and language hash:

my $time_diff_str_rel = unix_time_diff_in_words_relative( $time1 - $time2 );

my %TRANS = (
            'now'       => 'sega',
            'today'     => 'dnes',
            'tomorrow'  => 'utre',
            'yesterday' => 'vchera',
            'in'        => 'sled',
            'before'    => 'predi',
            'year'      => 'godina',
            'years'     => 'godini',
            'month'     => 'mesec',
            'months'    => 'meseca',
            'day'       => 'den',
            'days'      => 'dni',
            'hour'      => 'chas',
            'hours'     => 'chasa',
            'minute'    => 'minuta',
            'minutes'   => 'minuti',
            'second'    => 'sekunda',
            'seconds'   => 'sekundi',
            );
            
$time_diff_str_rel =~ s/([a-z]+)/$TRANS{ lc $1 } || $1/ge;

I know this is no good for longer sentences but works fine in this case.

GITHUB REPOSITORY

git@github.com:cade-vs/perl-data-tools.git

git clone git://github.com/cade-vs/perl-data-tools.git

AUTHOR

Vladi Belperchinov-Shabanski "Cade"
      <cade@noxrun.com> <cade@bis.bg> <cade@cpan.org>
http://cade.noxrun.com/