The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Data-Vitals-1.06
River stage zero No dependents
++
/ Data::Vitals::Circumference

NAME

Data::Vitals::Circumference - A measurement of the circumference around part of the human body.

DESCRIPTION

A significant number of measurements in the Data::Vitals package relate to measurements of the circumference of part of the human body.

Some examples include the Chest, Waist and Hips measurements.

These measurements are generally recorded in the same format, either as a number of inches or as a number of centimetres.

The Data::Vitals::Circumference package provides a base class for the family of circumference measurements, and can also be used directly to take an arbitrary circumference measurement not defined in the main DatA::Vitals package.

The "Circumference String"

Because this is such a general package, great effort has been taken to avoid assumptions that might lead to incorrect measurements. Measurements in both inches and cms are very widespread, and in order to support them both we do not accept raw numbers as input to the contructors.

Any "Circumference String" must provide an indication of the unit. We try to find this a flexibly as possible.

The following shows samples for the formats accepted.

  Metric measurements
  30cm        Default form
  86.5cm      Halves (and only halves) are also allowed
  85c         Shorthand form (or you accidentally missed the m)
  85cms       Plural form
  85CM        Case insensitive
  85 cm       Whitespace is ignored
  
  Imperial Measurements
  30"         Default form
  30.5"       Halves (and only halves) are also allowed
  30i         Various fragments of "inches"
  30in        Various fragments of "inches"
  30inc       Various fragments of "inches"
  30inch      Various fragments of "inches"
  30inche     Various fragments of "inches"
  30inches    Various fragments of "inches"
  30inchs     Bad spelling
  30INCHES    Case insensitive
  30 inches   Case insensitive
  30 "        Whitespace is ignored

Storage and Conversion

Regardless of the method that the value is entered, all values are stored internally in centimetres. The default string form of all measurements is also given in centimetres.

This is a specific design decision, as there is a long term world trend towards increased metrification. Many countries such as Germany use metric values even for the "common" understanding of things and would be hard-pressed to tell you their height in feet and inches.

However, to support those still dealing in inches we ensure that any value initially entered in inches (including optional halves), stored as cms, and returned to inches for presentation will ALWAYS return the original number of inches, including halves.

The conversion functions in Data::Vitals::Util are heavily tested for every possible value in the range to ensure that this is the case.

METHODS

new $circumference

The new constructor takes a circumference string and returns a new object representing the measurement, or undef if there is a problem with the value provided.

Currently, there is no explanation of the reason why a value is rejected. Any used may need to just be presented with an "Invalid Value" message.

In future, a mechanism to access error messages following an error will be added.

as_string

The as_string method returns the generic string form of the measurement.

This is also the method called during overloaded stringification. By default, this returns the metric form, which is in centimetres.

as_metric

The as_metric method returns the metric form of the measurement, which for circumference measurements is always in centimetres.

as_imperial

The as_imperial method returns the imperial form of the measurement, which for circumference measurements is in raw inches (with no conversion to feet and inches)

as_cms

The as_cms method explicitly returns the measurement in centimetres.

The format of the string returned is similar to 38cm.

as_inches

The as_inches method explicitly returns the measurement in inches.

Unlike Height, it is not converted to feet, and is shown just as raw inches.

The format of the string returned is similar to 38"

SUPPORT

Bugs should always be reported via the CPAN bug tracker

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Data-Vitals

For other issues, contact the maintainer.

AUTHORS

Adam Kennedy <adamk@cpan.org>

ACKNOWLEGEMENTS

Thank you to Phase N (http://phase-n.com/) for permitting the open sourcing and release of this distribution.

COPYRIGHT

Copyright 2004 - 2008 Adam Kennedy.

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

The full text of the license can be found in the LICENSE file included with this module.