NAME
Unit::Duration - Work-time unit duration conversion and canonicalization
VERSION
version 1.02
SYNOPSIS
use Unit::Duration;
my $ud = Unit::Duration->new;
my $x = $ud->canonicalize('4d 6h 4d 3h');
# $x eq '8 days, 9 hrs'
my $y = $ud->canonicalize( '4d 6h 4d 3h', { compress => 1 } );
# $y eq '1 wk, 4 days, 1 hr'
my $z = $ud->canonicalize(
'4d 6h 4d 3h',
{
intra_space => '',
extra_space => ' ',
pluralize => 0,
unit_type => 'letter',
compress => 1,
},
);
# $z eq '1w 4d 1h'
my $hours = $ud->sum_as( hours => '2 days -6h' );
# $hours == 10
my $ud_fully_described_with_defaults = Unit::Duration->new(
name => 'default',
table => q{
y | yr | year = 4 qtrs
q | qtr | quarter = 3 mons
o | mon | month = 4 wks
w | wk | week = 5 days
d | day = 8 hrs
h | hr | hour = 60 mins
m | min | minute = 60 secs
s | sec | second
},
intra_space => ' ',
extra_space => ', ',
pluralize => 1,
unit_type => 'short',
compress => 0,
);
my $canonical_table_string = $ud->get_table_string('default');
my $canonical_table_structure = $ud->get_table_structure('default');
$ud->set_table( default => $canonical_table_string );
$ud->set_table(
partial_default => [
{
letter => 'd',
short => 'day',
long => 'day',
duration => '8 hrs',
},
{
letter => 'h',
short => 'hr',
long => 'hour',
},
],
);
my $duration_string = $ud->canonicalize(
'3d 6h 1d 2h',
{
intra_space => ' ',
extra_space => ', ',
pluralize => 1,
unit_type => 'short',
compress => 0,
},
'default', # table name or table string or table structure
);
my $hours_by_table = $ud->sum_as( hours => '2 days -6h', 'default' );DESCRIPTION
This class provides the ability to "canonicalize" time durations based on custom time units and their relationships to each other.
As an illustrative example, let's say you're a project manager dealing with work-time duration estimates for a set of tasks. These might be weeks, days, hours, or some combination of these units and/or other units. In the context of work-time duration, 1 day does not equal 24 hours. The standard convention is 1 day equals 8 hours and 1 week equals 5 days. However, this is not universal. In France, for example, the work week is typically 35 hours, not 40.
Assuming the default/typical case, though, let's say you have a task that's estimated to take 12 hours. You can represent that duration as "12 hours" or "12 hrs" or "1 day, 4 hours" or "1.5 days" or "1d 4h" or any number of other ways.
TABLES
Exactly how many hours constitute a day and that "hrs" is the canonical shortened form of "hours" is all setup with a duration table. A duration table consists of rows of units and columns of data types. The following is the default table (in string form):
y | yr | year = 4 qtrs
q | qtr | quarter = 3 mons
o | mon | month = 4 wks
w | wk | week = 5 days
d | day = 8 hrs
h | hr | hour = 60 mins
m | min | minute = 60 secs
s | sec | secondEach unit must have a "letter" and "short" form and may have an optional "long" form. Any unit without a "long" form will use its "short" form as such. (See "day" for an example.) Each unit must conclude with a duration, which should define the unit's duration relative to some lower unit. Ultimately, there needs to be 1 and only 1 unit that is the "base" unit. In the default table, this is "second".
For tables in string form, the separation of columns can be done using any non-digit, non-letter character other than commas and semicolons. All spacing is ignored. Tables in data form are an arrayref of hashrefs where each hashref contains letter, short, optionally a long, and a duration.
{
letter => 'd',
short => 'day',
long => 'day',
duration => '8 hrs',
}Tables are parsed and stored by name. The default table is stored as "default".
METHODS
new
This method instantiates a Unit::Duration object. It requires no inputs, but it can be supplied with a table (using the name and table keys) and any number of settings. See "SETTINGS" below.
my $ud = Unit::Duration->new;
my $ud_fully_described_with_defaults = Unit::Duration->new(
name => 'default',
table => q{
y | yr | year = 4 qtrs
q | qtr | quarter = 3 mons
o | mon | month = 4 wks
w | wk | week = 5 days
d | day = 8 hrs
h | hr | hour = 60 mins
m | min | minute = 60 secs
s | sec | second
},
intra_space => ' ',
extra_space => ', ',
pluralize => 1,
unit_type => 'short',
compress => 0,
);canonicalize
This method requires a duration string to parse. It will return a canonicalized string based on the settings and table used.
my $x = $ud->canonicalize('4d 6h 4d 3h');
# $x eq '8 days, 9 hrs'It can optionally can accept settings overrides in a hashref. See "SETTINGS" below.
my $y = $ud->canonicalize( '4d 6h 4d 3h', { compress => 1 } );
# $y eq '1 wk, 4 days, 1 hr'
my $z = $ud->canonicalize(
'4d 6h 4d 3h',
{
compress => 1,
unit_type => 'letter',
intra_space => '',
extra_space => ' ',
},
);
# $z eq '1w 4d 1h'It can also optionally be provided a table by name or as a string or data structure.
my $duration_string = $ud->canonicalize(
'3d 6h 1d 2h',
{
intra_space => ' ',
extra_space => ', ',
pluralize => 1,
unit_type => 'short',
compress => 0,
},
'default', # table name or table string or table structure
);sum_as
Thie method accepts a unit label and a duration string. It will return a number representing the value of the duration as the unit.
my $hours = $ud->sum_as( hours => '2 days -6h' );
# $hours == 10It can also optionally be provided a table by name or as a string or data structure.
my $hours = $ud->sum_as( hours => '2 days -6h', 'default' );set_table
This method sets a table for later use. It requires a name string, which will be used to label the table, and the table data as either a string or a data structure.
$ud->set_table( default => $canonical_table_string );
$ud->set_table(
partial_default => [
{
letter => 'd',
short => 'day',
long => 'day',
duration => [ 8, 'hrs' ],
},
{
letter => 'h',
short => 'hr',
long => 'hour',
},
],
);get_table_string
This method returns a "canonical" table string for a given table label.
my $canonical_table_string = $ud->get_table_string('default');The "canonical" table string is not necessarily exactly the same as the input string used to create the table. It's a uniform string, but it can be fed back into set_table and other methods if desired.
get_table_structure
This method returns a table as a data structure: an arrayref of hashrefs.
my $canonical_table_structure = $ud->get_table_structure('default');SETTINGS
Settings affect the way canonicalize formats its output.
intra_space
This is a string and represents the space between a unit's numeric value and its text label.
extra_space
This is a string and represents the space between different units.
pluralize
This is a boolean that sets whether units should be "pluralized" when they don't have the value of 1. For example, if you input "2h", that will become "2 hrs" if pluralize is true or "2 hr" if pluralize is false.
unit_type
This is the unit type to use for the unit label. This will be either "letter", "short", or "long".
compress
By default, if you provide canonicalize a string with repeated same units, it will merge these values, but it will not shift values between units. For example:
my $x = $ud->canonicalize('4d 6h 4d 3h');
# $x eq '8 days, 9 hrs'By setting compress to a true value, canonicalize will shift values between units. For example:
my $y = $ud->canonicalize( '4d 6h 4d 3h', { compress => 1 } );
# $y eq '1 week, 2 days, 1 hrs'SEE ALSO
You can look for additional information at:
AUTHOR
Gryphon Shafer <gryphon@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2021 by Gryphon Shafer.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)