Units API

Units API converts between various weights and measurements. The conversion uses the International System of Units (SI) conversion factors. Where possible, these conversion factors are those provided by the U.S. National Institute of Standards and Technology (NIST) Special Publication 811, 2008 Edition. If the NIST does not provide the conversion factor, other sources may be used as long as the work is GPL compatible.

The central API call, unitsapi_convert($value, $from, $to, $details = FALSE), returns the result of the conversion. By setting $default = TRUE, the result is an array that contains the converted value, plus the full name of the units involved in the conversion (singular or plural, depending on the result).

This module is only an API and does not have an user interface.

SUPPORTED UNITS

There are hundreds of measurement units found throughout the world, and this module does not intend to support them all. To determine which units should be supported, the module developers use their own best guess as to which units are most popular. If you would like a specific measurement unit supported, please submit a feature request with Units API.

A list of supported units, and the keys you need to pass to the unitsapi_convert() function, are available on the module's help page.

EXAMPLES

// Convert kilometer to feet
$result = unitsapi_convert(1.5, 'kilometer', 'foot');
// $result == 4921.259843

// Convert Fahrenheit to Kelvin
$result = unitsapi_convert(55, 'fahrenheit', 'kelvin');
// $result == 285.927778 

// Convert US liquid ounces to Imperial pints with a detailed array of the conversion
$result = unitsapi_convert(50, 'us fluid ounce', 'imperial pint', TRUE);
// $result == Array ([result] => 2.602107, [from] => US fluid ounces, [to] => Imperial pints)

HOOK_UNITSAPI($data)

Use hook_unitsapi($data) to make changes to the units array. For example:

/**
 * Implementation of hook_unitsapi().
 */
function mymodule_unitsapi() {
  $data['meter']['singular'] = 'metre';
  return $data;
}

TESTING

Every measurement unit should have its own unit test using the assertion: $this->assertUnitConversion($value, $from, $to, $expected, $group). If you submit a new kind of unit, please also submit an example conversion for this test.