NAME

Time::D - Differentiate between two times

VERSION

version 0.020

SYNOPSIS

use Time::D;
use Time::C;
use feature 'say';

# "1 hour ago"
say Time::D->new(time, time - 3600)->to_string();

# "now"
say Time::D->new(time)->to_string();

my $d = Time::D->new(time);
$d->comp(Time::C->from_string("2000-01-01T00:00:00Z")->epoch);

# "16 years, 8 months, 4 weeks, 20 hours, 6 minutes, and 3 seconds ago" (at the time of writing)
say $d->to_string();

# "8 months, and 4 weeks ago"
$d->years = 0;

# "7 months, and 4 weeks ago"
$d->months--;

# "2016-02-01T00:00:00Z"
say Time::C->gmtime($d->comp)->string;

DESCRIPTION

Allows you to differentiate between two times, manipulate the difference in various ways, and check what the computed comparison time is.

CONSTRUCTORS

new

my $d = Time::D->new($base);
my $d = Time::D->new($base, $comp);

Creates a Time::D object comparing the $base epoch to the $comp epoch.

$base

This is the epoch for the base of the comparison.

$comp

This is the epoch for the time you want to compare to the base. If omitted, this defaults to the same as $base.

ACCESSORS

These accessors will work as LVALUEs, meaning you can assign to them to change the compared times.

base

my $epoch = $d->base;
$d->base = $epoch;
$d->base += 3600;
$d->base++;
$d->base--;

$d = $d->base($new_base);

Returns or sets the base epoch. This is the base time that $d->comp gets compared against, and is the number of seconds since the system epoch, usually 1970-01-01T00:00:00Z.

If the form $d->base($new_base) is used, it likewise changes the base epoch but returns the entire object.

comp

my $epoch = $d->comp;
$d->comp = $epoch;
$d->comp -= 3600;
$d->comp++;
$d->comp--;

$d = $d->comp($new_comp);

Returns or sets the comp epoch. This is the time that gets compared to the $d->base, and is the number of seconds since the system epoch, usually 1970-01-01T00:00:00Z.

If the form $d->comp($new_comp) is used, it likewise changes the comp epoch but returns the entire object.

sign

my $sign = $d->sign;
$d->sign = $sign;

$d = $d->sign($new_sign);

Returns or sets the sign part of the difference - whether the difference between $d->base and $d->comp is positive or negative. Changing it changes $d->comp to either be before the $d->base or after it. The sign can be either + or -.

If the form $d->sign($new_sign) is used, it likewise changes the sign but returns the entire object.

years

my $y = $d->years;
$d->years = $y;
$d->years += 10;
$d->years++;
$d->years--;

$d = $d->years($new_years);

Returns or sets the year part of the difference between the $d->base and the $d->comp. If changed, it changes $d->comp.

If the form $d->years($new_years) is used, it likewise changes the year part of the difference but returns the entire object.

months

my $m = $d->months;
$d->months = $m;
$d->months += 12;
$d->months++;
$d->months--;

$d = $d->months($new_months);

Returns or sets the month part of the difference between the $d->base and the $d->comp. If changed, it changes $d->comp.

If the form $d->months($new_months) is used, it likewise changes the month part of the difference but returns the entire object.

weeks

my $w = $d->weeks;
$d->weeks = $w;
$d->weeks += 4;
$d->weeks++;
$d->weeks--;

$d = $d->weeks($new_weeks);

Returns or sets the week part of the difference between the $d->base and the $d->comp. If changed, it changes $d->comp.

If the form $d->weeks($new_weeks) is used, it likewise changes the week part of the difference but returns the entire object.

days

my $days = $d->days;
$d->days = $days;
$d->days += 7;
$d->days++;
$d->days--;

$d = $d->days($new_days);

Returns or sets the day part of the difference between the $d->base and the $d->comp. If changed, it changes $d->comp.

If the form $d->days($new_days) is used, it likewise changes the day part of the difference but returns the entire object.

hours

my $h = $d->hours;
$d->hours = $h;
$d->hours += 24;
$d->hours++;
$d->hours--;

$d = $d->hours($new_hours);

Returns or sets the hour part of the difference between the $d->base and the $d->comp. If changed, it changes $d->comp.

If the form $d->hours($new_hours) is used, it likewise changes the hour part of the difference but returns the entire object.

minutes

my $m = $d->minutes;
$d->minutes = $m;
$d->minutes += 60;
$d->minutes++;
$d->minutes--;

$d = $d->minutes($new_minutes);

Returns or sets the minute part of the difference between the $d->base and the $d->comp. If changed, it changes $d->comp.

If the form $d->minutes($new_minutes) is used, it likewise changes the minute part of the difference but returns the entire object.

seconds

my $s = $d->seconds;
$d->seconds = $s;
$d->seconds += 60;
$d->seconds++;
$d->seconds--;

$d = $d->seconds($new_seconds);

Returns or sets the second part of the difference between the $d->base and the $d->comp. If changed, it changes $d->comp.

If the form $d->seconds($new_seconds) is used, it likewise changes the second part of the difference but returns the entire object.

METHODS

to_array

my ($sign, $years, $months, $weeks, $days, $hours, $minutes, $seconds) = $d->to_array();

Returns the difference between $d->base and $d->comp in the different units. This is like accessing them via the accessors, except you get everything in one single call. This method is what's used internally by the accessors to get their values.

$sign

This will be either + or -, depending on if $d->comp is ahead of or behind $d->base.

$years

This will be the difference in years.

$months

This will be the difference in months after the years have been accounted for.

$weeks

This will be the difference in weeks after the years and months have been accounted for.

$days

This will be the difference in days after the weeks etc. have been accounted for.

$hours

This will be the difference in hours after the days etc. have been accounted for.

$minutes

This will be the difference in minutes after the hours etc. have been accounted for.

$seconds

This will be the difference in seconds after the minutes etc. have been accounted for.

to_string

$d->to_string();
$d->to_string($precision);
"$d";

Returns the difference as a human readable string. The $precision determines how precise the output will be, and it can range from 0 to 7 (though 0 is pretty useless).

$precision

Determines how precise the output should be. The default is 7, which is the maximum precision and will tell you all the differences to the second. For precisions less than the maximum, the results are truncated. No rounding is done.

If you set it to 0, there actually won't be enough precision to see a difference at all, so you will get the string now returned.

If you stringified the object, like "$d"; for example, the precision will be 2, and only the 2 most significant units of difference will be returned.

This is treated as a maximum, meaning that if the actual difference in the data is less than the given precision, it won't pad with arbitrary 0 units.

The return value will be a string in one of the following forms:

• now

• in %s, [%s, ...], and %s

• in %s

• %s, [%s, ...], and %s ago

• %s ago

Where the %s will be strings such as:

• 1 year

• %d years

• 1 month

• %d months

... and so on.

SEE ALSO

Time::C

The companion to this module, which handles individual times.

Time::Seconds

Which doesn't base itself on a specific epoch, so it's ostensibly simpler, but also less able to correctly get differences in months and days.

Time::Moment

This is what this module uses internally to calculate the different units.

Number::Denominal

Breaks up numbers into arbitrary denominations; deals excellently with durations as well, though it works in the same way as Time::Seconds.

Time::Ago

Like Time::Seconds and Number::Denominal it doesn't care about real dates when determining a timespan, and it specifically states that it is only an approximation.

AUTHOR

Andreas Guldstrand <andreas.guldstrand@gmail.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by Andreas Guldstrand.

This is free software, licensed under:

The MIT (X11) License

cpanm Time::C

perl -MCPAN -e shell
install Time::C