Alex White (wu)

NAME

Wubot::TimeLength - utilities for dealing with time durations

VERSION

version 0.2.004

SYNOPSIS

    use Wubot::TimeLength;

    my $timelength = Wubot::TimeLength->new();

    # returns '1h1m'
    $timelength->get_human_readable( 3601 );

    # returns 1.5
    $timelength->get_hours( 60*60*1.5 );

    # returns 3601
    $timelength->get_seconds( '1h1s' );

    # rounds 1.5 days, 1 minute, and 10 seconds to nearest hour: 1d12h
    $timelength->get_human_readable( 60*60*24*1.5+70 )

    # use a space delimiter
    my $timelength = Wubot::TimeLength->new( space => 1 ),

    # returns '1h 1s' with space delimiter
    $timelength->get_human_readable( 3601 );

DESCRIPTION

This class provides some utilities for dealing with time durations. It supports the 'compact' form used by Convert::Age, but with a few variations.

For the sake of simplicity, one month is always treated as 30 days, and one year is always represented as 365 days.

SUBROUTINES/METHODS

$obj->get_seconds( $time );

When given a date in the 'compact' form (e.g. '1h1m' or '1h 1m'), returns the number of seconds.

$obj->get_human_readable( $seconds );

Given a number of seconds, return the time in 'compact' form. For example, '3601' seconds returns '1h1s'.

Time lengths are rounded to the most significant two fields. For example, 1 day, 1 hour, 1 minute, and 1 second would be rounded to 1d1h. Obviously this method is not intended for precise time calculations, but rather for human-friendly ones. Please don't try to convert a number of seconds to the human-readable format, and then convert that back to a number of seconds, as it will most likely be different due to rounding!!! If you need a more precise calculation, use Convert::Age.

If the 'space' option was set at construction time, then a space delimiter will be used in the resulting string, e.g. '1h 1m'.

$obj->get_hours( $seconds )

Given a number of seconds, return the number of hours rounded to a single digit.

$obj->get_age_color( $seconds )

Given a number of seconds, return a color representing the age. This helps to very quickly assess the age of an item by looking at the color. A steady stream of items with evenly spaced ages will create a smooth gradient of color. Different colors are used to represent the age in minutes, hours, days, or months.

If the age is younger than 1 hour, the color will be somewhere in the spectrum from light pink (brand new) to dark purple (1 hour old).

If the age is between 1 hour and 1 day old, the color will vary from light blue to dark blue.

If the age is between 1 day and 1 month, the color will vary from a rather light gray to black.

If the age is greater than 1 month year, the color will be an increasingly dark yellow color.

This should be configurable in the future.

SEE ALSO

Convert::Age