NAME

Class::Measure - Create, compare, and convert units of measurement.

SYNOPSIS

See Class::Measure::Length for some examples.

DESCRIPTION

This is a base class that is inherited by the Class::Measure classes. This distribution comes with the class Class::Measure::Length.

The classes Class::Measure::Area, Class::Measure::Mass, Class::Measure::Space, Class::Measure::Temperature, and Class::Measure::Volume are planned and will be added soon.

The methods described here are available in all Class::Measure classes.

METHODS

new

my $m = new Class::Measure::Length( 1, 'inch' );

Creates a new measurement object. You must pass an initial measurement and default unit.

In most cases the measurement class that you are useing will export a method to create new measurements. For example Class::Measure::Length exports the length() method.

unit

my $unit = $m->unit;

Returns the object's default unit.

set_unit

$m->set_unit( 'feet' );

Sets the default unit of the measurement.

value

my $yards = $m->value('yards');
my $val = $m->value;
print "$m is the same as $val when in a string\n";

Retrieves the value of the measurement in the default unit. You may specify a unit in which case the value is converted to the unit and returned.

This method is also used to handle overloading of stringifying the object.

set_value

my $m = length( 0, 'inches' );
$m->set_value( 12 ); # 12 inches.
$m->set_value( 1, 'foot' ); # 1 foot.

Sets the measurement in the default unit. You may specify a new default unit as well.

reg_units

Class::Measure::Length->reg_units(
  'inch', 'foot', 'yard'
);

Registers one or more units for use in the specified class. Units should be in the singular, most common, form.

units

my @units = Class::Measure::Length->units();

Returns a list of all registered units.

reg_aliases

Class::Measure::Length->reg_aliases(
  ['feet','ft'] => 'foot',
  ['in','inches'] => 'inch',
  'yards' => 'yard'
);

Register alternate names for units. Expects two arguments per unit to alias. The first argument being the alias (scalar) or aliases (array ref), and the second argument being the unit to alias them to.

reg_convs

Class::Measure::Length->reg_convs(
  12, 'inches' => 'foot',
  'yard' => '3', 'feet'
);

Registers a unit conversion. There are three distinct ways to specify a new conversion. Each requires three arguments.

$count1, $unit1 => $unit2
$unit1 => $count2, $unit2

These first two syntaxes create automatic reverse conversions as well. So, saying there are 12 inches in a foot implies that there are 1/12 feet in an inch.

$unit1 => $unit2, $sub

The third syntax accepts a subroutine as the last argument the subroutine will be called with the value of $unit1 and it's return value will be assigned to $unit2. This third syntax does not create a reverse conversion automatically.

PRIVATE METHODS

These methods are used internally and should only be useful to authors of Class::Measure classes.

_unalias

Accepts a single name either returns the name if it is the name of a unit, returns the name of the unit that it aliases to, or throws an error if neither a matching alias or matching unit was found.

_conv

Returns the current value as converted to the specified unit. Any values that are converted are cached so that proceeding calls that might require the value in the same unit. If the value is ever changed then the value cache is cleared.

_path

my $path = $m->_path(
  'inch',
  'yard'
);
# $path = ['inch','foot','yard']

Figures out the best conversion path for converting from the first unit to the second. Any paths that are created are cached for proceding calls that might need to get the same path.

_find_path

Used by _path for recursively finding the best path for a conversion.

_ol_add

$m = length(2,'inches') + length(1,'foot'); # 14 inches
$m++; # 15 inches
$m += length(3,'inches'); # 18 inches

This method handles the overloading of addition logic, such as +, +=, and ++.

_ol_sub

This method is the same as _ol_add, but works on subtraction.

_ol_mult

Multiplication overloader.

_ol_div

Division overloader.

_ol_str

Overloads the stringification of this object by calling and returning the response of value().

AUTOLOAD

# Same as get_value('feet').
my $feet = $m->feet;

# Same as set_value(2,'feet').
$m->feet(2);

Retrieve and set the leangth of measurement.

SUBCLASSING

Its straight-forward, see Class::Measure::Length for a simple and complete example.

TODO/BUGS/SUPPORT

See http://www.arandeltac.com/ClassMeasureModule.

AUTHOR

Copyright (c) 2005 Aran Clary Deltac

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Class::Measure

perl -MCPAN -e shell
install Class::Measure