Documentation/Calc Functions/CONVERT

From The Document Foundation Wiki
Jump to navigation Jump to search

Function name:

CONVERT

Category:

Add-in

Summary:

Converts a value expressed in one unit of measure to the corresponding value in another, compatible measurement system.

CONVERT is a wide-ranging function capable of converting values in many different types of measurement systems, covering:

  • Area
  • Energy
  • Flux density
  • Force
  • Information
  • Length and distance
  • Mass and weight
  • Power
  • Pressure
  • Speed
  • Temperature
  • Time
  • Volume

Syntax:

CONVERT(Number; FromUnit; ToUnit)

Returns:

Returns a real number which is the converted value expressed in the specified unit of measure.

Arguments:

Number is a real number, or a reference to a cell containing that number, that is the value to be converted from one unit to another.

FromUnit is a string, or a reference to a cell containing that string, that is an abbreviation signifying the unit from which conversion is taking place.

ToUnit is a string, or a reference to a cell containing that string, that is an abbreviation signifying the unit to which conversion is taking place. Both FromUnit and ToUnit must be of the same unit type.

  • If Number is non-numeric, then CONVERT reports a #VALUE! error.
  • If FromUnit and ToUnit are not valid units of the same type, then CONVERT reports an invalid argument error (Err:502).

The measurement units recognized by CONVERT fall into 13 groups, which are listed in the #Summary: section above. CONVERT will perform conversions between any two units within one group but reject any request to convert between units in different groups.

Within each group, a set of base unit symbols is defined (for example, the Temperature group includes symbols for Celsius, Fahrenheit, kelvin, and other units). However, many (but not all) of these base unit symbols can be further refined by the addition of a decimal prefix (for example, the decimal prefix of “k” might be added to the Mass and weight base unit of “g” if values in kilograms are to be used in the conversion).

Further flexibility is available for units in the Information group which can be given a binary prefix (for example, the binary prefix of “Mi” might be added to “byte” if values in mebibytes are to be used in the conversion).

All base unit symbols, decimal prefixes, and binary prefixes are case-sensitive.

The following tables list:

  1. The base unit symbols that are available within each of the unit groups (#Area, #Energy, #Flux density, #Force, #Information, #Length and distance, #Mass and weight, #Power, #Pressure, #Speed, #Temperature, #Time, and #Volume). Within each of these 13 tables, the Prefix column indicates with an asterisk any base units that accept optional decimal prefixes.
  2. The list of available #decimal prefixes.
  3. The list of available #binary prefixes.


Base units for Area group
Prefix Unit symbol Description
* "ang2" or "ang^2" square angstrom
* "ar" are
"ft2" or "ft^2" square foot
"ha" hectare
"in2" or "in^2" square inch
"ly2" or "ly^2" square light-year
* "m2" or "m^2" square meter
"mi2" or "mi^2" square international mile
"Morgen" morgen
"Nmi2" or "Nmi^2" square nautical mile
"Pica2" or "Pica^2" or "picapt2" or "picapt^2" square pica point
"pica2" or "pica^2" square pica
"uk_acre" or "acre" international acre
"us_acre" US survey acre
"yd2" or "yd^2" square yard


Base units for Energy group
Prefix Unit symbol Description
"BTU" or "btu" British thermal unit
* "c" thermochemical calorie
* "cal" International Steam Table calorie
* "e" erg
* "eV" or "ev" electron volt
"flb" foot-pound
"HPh" or "hh" horsepower-hour
* "J" joule
* "Wh" or "wh" watt-hour


Base units for Flux density group
Prefix Unit symbol Description
* "ga" gauss
* "T" tesla


Base units for Force group
Prefix Unit symbol Description
* "dyn" or "dy" dyne
* "N" newton
"lbf" pound-force
* "pond" pond


Base units for Information group
Prefix Unit symbol Description
* "bit" bit
* "byte" byte


Base units for Length and distance group
Prefix Unit symbol Description
* "ang" angstrom
"ell" ell
"ft" foot
"in" inch
* "ly" or "lightyear" light-year
* "m" meter
"mi" international mile
"Nmi" nautical mile
* "parsec" or "pc" parsec
"Pica" or "picapt" pica point
"pica" pica
"survey_mi" US survey mile
"yd" yard


Base units for Mass and weight group
Prefix Unit symbol Description
"cwt" or "shweight" short hundredweight
* "g" gram
"grain" grain
"lbm" pound
"ozm" ounce
"pweight" pennyweight
"sg" slug
"stone" stone
"ton" short ton
* "u" unified atomic mass unit
"uk_cwt" or "lcwt" or "hweight" long hundredweight
"uk_ton" or "LTON" or "brton" long ton


Base units for Power group
Prefix Unit symbol Description
"HP" or "h" mechanical horsepower
"PS" Pferdestärke or metric horsepower
* "W" or "w" watt


Base units for Pressure group
Prefix Unit symbol Description
* "atm" or "at" standard atmosphere
* "mmHg" millimeter of mercury
* "Pa" pascal
"psi" pound per square inch
"Torr" torr


Base units for Speed group
Prefix Unit symbol Description
"admkn" Admiralty knot
"kn" international knot
* "m/h" or "m/hr" meters per hour
* "m/s" or "m/sec" meters per second
"mph" miles per hour


Base units for Temperature group
Prefix Unit symbol Description
"C" or "cel" degree Celsius
"F" or "fah" degree Fahrenheit
* "K" or "kel" kelvin
"Rank" degree Rankine
"Reau" degree Réaumur


Base units for Time group
Prefix Unit symbol Description
"day" or "d" day
"hr" hour
"mn" or "min" minute
* "sec" or "s" second
"yr" year


Base units for Volume group
Prefix Unit symbol Description
* "ang3" or "ang^3" cubic angstrom
"barrel" oil barrel
"bushel" US bushel
"cup" US cup
"ft3" or "ft^3" cubic foot
"gal" US gallon
"Glass" Australian glass (200 milliliters)
"GRT" or "regton" gross register tonnage
"Humpen" Humpen (500 milliliters)
"in3" or "in^3" cubic inch
* "l" or "L" or "lt" liter
"ly3" or "ly^3" cubic light-year
* "m3" or "m^3" cubic meter
"mi3" or "mi^3" cubic international mile
"Middy" Australian middy (285 milliliters)
"MTON" measurement ton
"Nmi3" or "Nmi^3" cubic nautical mile
"oz" US fluid ounce
"Pica3" or "Pica^3" or "picapt3" or "picapt^3" cubic pica point
"pica3" or "pica^3" cubic pica
"pt" or "us_pt" US pint
"qt" US quart
"Schooner" Australian schooner (425 milliliters)
"Sixpack" six pack (2 liters)
"tbs" US tablespoon
"tsp" US teaspoon
"tspm" metric teaspoon
"uk_gal" imperial gallon
"uk_pt" imperial pint
"uk_qt" imperial quart
"yd3" or "yd^3" cubic yard


Available decimal prefixes
Prefix Multiplier
Y (yotta) 1024
Z (zetta) 1021
E (exa) 1018
P (peta) 1015
T (tera) 1012
G (giga) 109
M (mega) 106
k (kilo) 103
h (hecto) 102
e (deca) 101
d (deci) 10-1
c (centi) 10-2
m (milli) 10-3
u (micro) 10-6
n (nano) 10-9
p (pico) 10-12
f (femto) 10-15
a (atto) 10-18
z (zepto) 10-21
y (yocto) 10-24


Available binary prefixes
Prefix Multiplier
Yi (yobi) 280
Zi (zebi) 270
Ei (exbi) 260
Pi (pebi) 250
Ti (tebi) 240
Gi (gibi) 230
Mi (mebi) 220
ki (kibi) 210


Im-jabber.svg

International Standard Abbreviations
For historical reasons, many of the units recognised by the CONVERT function do not use international standard abbreviations.

Additional details:

See Wikipedia’s Unit prefix and Binary prefix pages for more background information about decimal and binary prefixes.

This function is not generally compatible with other spreadsheets.

Examples:

Formula Description Returns
=CONVERT(3.5; "mi"; "yd") Here the function converts 3.5 international miles to yards, returning the value 6160. Both units are in the Length and distance group. 6160
=CONVERT(E1; E2; E3) where cells E1, E2, and E3 contain the values 15.6 (number), day (text), and hr (text) respectively. Here the argument values are passed by cell reference and the function converts 15.6 days to hours, returning the value 374.4. Both units are in the Time group. 374.4
=CONVERT(-20; "grain"; "g") Here the function converts -20 grains to grams, returning the value -1.29598 (to five decimal places). Both units are in the Mass and weight group. The CONVERT function accepts negative values and in most such cases, where there is a simple multiplicative relationship bewteen units, will return a negative value. (This may not be the case when converting between units in the Temperature group - see next example) -1.29598
=CONVERT(-10; "C"; "F") Here the function converts -10 degrees Celsius to degrees Fahrenheit, returning the value 14. There is not a simple multiplicative relationship bewteen temperature units, as different reference points are used. Hence, as in this case, an input negative number may be converted to a positive value. 14
=CONVERT(1; "dyn"; "e") Here the function returns an invalid argument error (Err:502) because the two units (dyne and erg) are in different groups (Force and Energy respectively). Err:502
=CONVERT(8; "barrel"; "kL") Here the function converts 8 oil barrels to kiloliters, returning the value 1.27190 (to five decimal places). Both units are in the Volume group. Note that kiloliters is specified by appending the decimal prefix "k" to the base unit of "L". 1.27190
=CONVERT(1; "kstone"; "lbm") Here the function returns an invalid argument error (Err:502) because decimal prefixes are not accepted with the stone unit. Err:502
=CONVERT(256; "Gibit"; "Mibyte") Here the function converts 256 gigibits to mebibytes, returning the value 32768. Both units (bit and byte) are in the Information group and support binary prefixes. 32768
=CONVERT(256; "Gbit"; "Mbyte") Here the function converts 256 gigabits to megabytes, returning the value 32000. Both units (bit and byte) are in the Information group and support decimal prefixes. 32000

Related LibreOffice functions:

None.

ODF standard:

Section 6.16.18, part 2

Equivalent Excel functions:

CONVERT