Provided by: libbadger-perl_0.16-2_all
NAME
Badger::Duration - simple class for representing durations
SYNOPSIS
use Badger::Duration 'Duration'; my $d = Duration('7 days 4 hours 20 minutes'); print "$d is ", $d->seconds, " seconds\n";
DESCRIPTION
This is a simple module for parsing durations. It is ideally suited for things like the calculation of expiry times (e.g. for cookies, items in a cache, etc) allowing them to be specified in human-friendly format, e.g. "4 minutes 20 seconds" (or various alternatives).
EXPORTABLE SUBROUTINES
DURATION This is a shortcut alias to "Badger::Duration". use Badger::Duration 'DURATION'; my $duration = DURATION->new( hours => 4, minutes => 20, ); # same as Badger::Duration->new(...); Duration() This subroutine returns the name of the "Badger::Duration" class when called without arguments. Thus it can be used as an alias for "Badger::Duration" as per DURATION. use Badger::Duration 'Duration'; my $duration = Duration->new(...); # same as Badger::Duration->new(...); When called with arguments, it creates a new "Badger::Duration" object. my $duration = Duration(...); # same as Badger::Duration->new(...);
METHODS
The following methods are defined in addition to those inherited from the Badger::Comparable and Badger::Base base classes. new() Constructor method to create a new "Badger::Duration" object. The duration can be specified as a single "duration" parameter. my $d = Badger::Duration->new( duration => '4 minutes 20 seconds' ); The duration string can contain any number of "<number> <duration>" sequences separate by whitespace, commas or the word "and". The following are all valid: 4 minutes 20 seconds 4 minutes,20 seconds 4 minutes, 20 seconds 4 minutes and 20 seconds The canonical names for durations are: "year", "month", "day", "hour", "minute" and "second". The following aliases may be used: second s sec secs seconds minute m min mins minutes hour h hr hrs hours day d days week w wk weeks month M mon mons months year y yr yrs years A duration can also be specified using named parameters: my $d = Badger::Duration->new( minutes => 4, seconds => 20, ); Or by reference to a hash array: my $d = Badger::Duration->new({ minutes => 4, seconds => 20, }); This can also be specified as an explicit "duration" option if you prefer: my $d = Badger::Duration->new( duration => { minutes => 4, seconds => 20, } ); In all cases, any of the valid aliases for durations may be used, e.g. my $d = Badger::Duration->new( h => 1, m => 4, s => 20, ); duration() Returns a reference to a hash array containing the canonical values of the duration. my $d = Badger::Duration->new( duration => '4 hours 20 minutes' ); my $h = $d->duration; print $h->{ hour }; # 4 print $h->{ minute }; # 20 seconds() Returns the total number of seconds for the duration. my $d = Badger::Duration->new( duration => '4 hours 20 minutes' ); print $d->seconds; # 15600 compare($that) This method is defined to enable the functionality provided by the Badger::Comparable base class. use Badger::Duration 'Duration'; my $d1 = Duration('4 hours 20 minutes'); my $d2 = Duration('270 minutes'); if ($d1 < $d2) { # ...do something... } text() Returns a canonical text representation of the duration. use Badger::Duration 'Duration'; my $d1 = Duration('4 hrs 20 mins'); print $d1->text; # 4 hours 20 minutes Note that the units will be pluralised appropriately. e.g. 1 hour 1 minute 1 second 2 hours 2 minutes 2 seconds This method is bound to the auto-stringification operation which is a fancy way of saying it gets called automatically when you simply print a "Badger::Duration" object. print $d1; # 4 hours 20 minutes
INTERNAL METHODS
init($config) Object initialisation method called automatically by the new() constructor method inherited from the Badger::Base base class. parse_text($text) Internal method to parse a text string and return a hash reference of canonical values. parse_hash($hash) Internal method to parse a hash reference and return another hash reference of canonical values (e.g. after mapping aliases to canonical names). count_seconds($hash) Counts the total number of seconds in a duration passed by reference to a hash array.
AUTHOR
Andy Wardley <http://wardley.org>
COPYRIGHT
Copyright (C) 2013 Andy Wardley. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.