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 quantity.

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

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][view] => US fluid ounces, [to][view] => Imperial pints)

HOOK_UNITSAPI_LOAD_ALTER() and HOOK_UNITSAPI_RESULT_ALTER()

/**
 * Implementation of hook_unitsapi_load_alter().
 */
function mymodule_unitsapi_load_alter(&$units) {
  /* Modify the meter name */
  $units['meter']['singular'] = 'metre';

  /* Add a kilopascal unit to the pressure category */
  $units['kilopascal'] = Array('singular' => 'kilopascal', 'plural' => 'kilopascals', 'symbol' => 'kPa', 'factor'  => array('default' => '1000'), 'kind' => 'pressure', 'source' => 'http://physics.nist.gov/Pubs/SP811/contents.html');
}

/**
 * Implementation of hook_unitsapi_result_alter().
 */
function mymodule_unitsapi_result_alter(&$result) {
  if ($result['from']['key'] == 'meter') {
    $result['result'] = mymodule_any_function($result['value']);
  }  
}

HOW TO ADD NEW UNITS

• Option #1: Implement hook_unitsapi_load_alter() from your own module to add units.
• Option #2: Implement hook_unitsapi_result_alter() from your own module to add units or run your own conversion function.
• Option #3: Create an issue with your requested units. The issue requires at least the unit name, plural name, symbol, conversion factor, and an URL to a credible source to verify the conversion factor. For the conversion factor, check the units.xml file for the common factor. For example, all Area conversions use square meters as their conversion factor.

INTEGRATED MODULES

1. Unit Conversion Formatters
2. Units of Measurement
3. Measured Value Field

SUPPORTED UNITS

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.

Length:

millimeter (mm)
centimeter (cm)
decimeter (dm)
meter (m)
kilometer (km)
foot (ft)
inch (in)
mile (mi)
yard (yd)

Volume:

cubic foot (ft3)
cubic inch (in3)
cubic mile (mi3)
cubic yard (yd3)
cup (cup)
Imperial gallon (gal)
US gallon (gal)
milliliter (mL)
liter (L)
Imperial fluid ounce (fl oz)
US fluid ounce (fl oz)
Imperial pint (pt)
US pint (liquid) (pt)
US pint (dry) (pt)
Imperial quart (qt)
US quart (liquid) (qt)
US quart (dry) (qt)
tablespoon (tbsp)
teaspoon (tspn)

Weight:

milligram (mg)
gram (g)
kilogram (kg)
carat (CD)
grain (gr)
ounce (oz)
pennyweight (dwt)
pound (lb)
stone (st)
slug (slug)
metric ton (t)
long ton (t)
short ton (t)

Area:

acre (acre)
are (a)
hectare (ha)
square foot (ft2)
square meter (m2)
square kilometer (km2)
square inch (in2)
square yard (yd2)
square mile (mi2)
aankadam (aankadam)
perch (perch)
cent (cent)
chatak (chatak)
kottah (B) (kottah (B))
guntha (guntha)
ground (ground)
marla (marla)
rood (rood)
bigha I (bigha I)
bigha II (bigha II)
kanal (kanal)
biswa I (biswa I)
biswa II (biswa II)

Pressure:

pascal (Pa)
torr (Torr)
bar (bar)
millibar (mb)
psi (lbf/in2)

Time:

day (d)
hour (h)
minute (min)
year (yr)

Temperature:

celsius (°C)
fahrenheit (°F)
kelvin (K)