- NAME
- SYNOPSIS
- DESCRIPTION
- COPYRIGHT
- SEE ALSO

# NAME

ActiveState::Duration - Format and parse time duration values

# SYNOPSIS

     use ActiveState::Duration qw(ago_eng);
     print "It is now ", ago_eng(time), " since time begun.\n";

# DESCRIPTION

The `ActiveState::Duration` module provides functions to format and parse time duration values. Time is expressed as a number of weeks, days, hours, minutes and seconds.

$str = dur_format_XXX( $duration )
$str = dur_format_XXX( $duration, $precision )
$str = dur_format_XXX( $duration, $precision, $frac_part )

  The dur_format_XXX() functions take a time $duration value (in seconds) and format it as a readable string. This section describes the common arguments supported by most of dur_format_XXX() functions. The `XXX` in the function name selects which format it returns and is described below.

  The $precision argument specify how close the string much match the duration value. The default is 0.05 which means that up to 5% off is acceptable. Pass 0 as the $precision to request an exact result.

  The $frac_part specify at which time unit formatting will start using fractions to achieve the desired precision. It should be one of "week", "day", "hour", "minute", "second" or "first". The default is "second".

  A $frac_part value of "first" is special and needs some more explanation. The time units will be considered in order from "week" to "second", and the first one longer than the $duration is used.

$str = dur_format_sm( @ARGS )

  Use the Sendmail format which looks like "1h30m". If the $duration value is negative it is formatted like "-1h30m".

$str = dur_format_iso( @ARGS )

  Use the ISO 8601 format which looks like "PT1H30M". If the $duration value is negative it is formatter with a leading "-", even though that is not standards conforming.

$str = dur_format_eng( @ARGS )

  Use plain English; "1 hour and 30 minutes". If the $duration value is negative then the word "negative" is prepended to the string.

$str = ago_eng( @ARGS )

  Same as dur_format_eng() but adds the word "ago" as long as $duration is positive and the words "from now" if $duration is negative. A $duration of 0 is special cased as "just now".

$str = dur_format_clock( $duration )

  Use stopwatch format; "1:30:00", i.e. "hhh:mm:ss". This function does not take the $precision or $frac_part arguments yet and the $duration is truncated to whole seconds. A negative $duration value will be formated with a leading "-". A value of `0` is formatted as "0:00:00".

$duration = dur_parse( $str )

  This function takes a string representing a duration value and return it as number of seconds. All strings produced by any of the dur_format_XXX() or the ago_eng() functions can be parsed back to an $duration value by dur_parse(). It returns `undef` if it cannot parse the $str for some reason.

# COPYRIGHT

Copyright (C) 2003 ActiveState Corp. All rights reserved.

# SEE ALSO

Time::Duration, ActiveState::StopWatch, ActiveState::Bytes