This page is read by a script (makeunits). The script extracts information from the wikitext, and outputs the Lua source that defines the table of units; that source can be manually copied into Module:Convert/data.
Conversion factors and physical constants
The values for most of the conversion factors used by Template:Convert come from international and national standards documents:
The NIST document gives conversion factors correct to 7 places. Factors in bold are exact. If exact factors have more than 7 places, they are rounded and no longer exact. This convert module replaces these rounded figures with the exact figures. For example, the NIST document has 1 square mile = 2.589 988 E+06 square meters. The convert template has 1 square mile = 2,589,988.110336 square meters.
Values for the fundamental physical constants come from the NIST Reference on Constants, Units, and Uncertainty, either the 2010 or the 2014 version. The 2018 version is in preparation. While the articles on the units should be updated as the new versions come out every four years, the few more significant figures provided are probably not necessary for the way this template is used.
"CODATA 2010 Table at NIST"(PDF). From Mohr, Peter J.; Taylor, Barry N.; Newell, David B. (2012). "CODATA recommended values of the fundamental physical constants: 2010". Reviews of Modern Physics. 84 (4): 1527–1605. doi:10.1103/RevModPhys.84.1527.
"CODATA 2014 Table at NIST". From Mohr, Peter J.; Newell, David B.; Taylor, Barry N. (2016). "CODATA recommended values of the fundamental physical constants: 2014". Reviews of Modern Physics. 88 (3). doi:10.1103/RevModPhys.88.035009.
Definitions for additional historical measures are found in sources such as
Fenna, Donald (2002). A Dictionary of Weights, Measures, and Units. Oxford University Press. ISBN978-0-19-107898-9.
Table format
Format
The script that reads this page ignores everything except for the wikitext in the following sections:
In those sections, a level-3 heading (like === Length ===) starts a table that defines units of a certain type. In the subsection, lines that start with | are processed (all other lines, and lines that start with |- or |}, are ignored). A processed line is split into fields (delimited with ||), and leading/trailing whitespace is removed from each field. Empty fields in the Conversions section are given a default value (for example, the plural of yard is formed by adding s, and the US names are also yard and yards).
The second field in each row of the Conversions section normally specifies a unit's symbol, but it can be used for other purposes described in the following. In some cases the text in the second field can be long, and it is convenient to insert colspan="11" | before the text to avoid it wrapping in a narrow column. Any such colspan at the start of the second field is ignored.
Alias
Some unit codes are an alias for another spelling of the unit code. For example, the code ft2 is an alias for sqft, and that is indicated by entering =sqft in the Symbol column for the ft2 entry. An alias can only be entered after the primary unit has been defined (the sqft entry must precede the ft2 entry).
Normally there are no other entries on an alias line, however, the following may be used:
default = unit code to specify that the alias has a default output that is different from the primary unit
link = link text to specify that the alias has a link that is different from the primary unit
multiplier = number used as "multiplier = 100" with unit code 100km to define a unit that is 100 times the size of a kilometre
sp=us (or sp = us) to specify that using the alias forces US spelling for that unit
symbol = symbol text to specify that the alias has a symbol that is different from the primary unit
symlink = link text to specify that the alias has a different link when abbreviated ("symbol link")
Per units
A unit can be defined as a ratio of two other units. For example, L/km can be defined as "liters per kilometer" by entering ==L/km as the symbol for the unit. A single "=" is used with an alias to specify that a unit code is an alternative name for another unit. By contrast, if "==" is used, the unit code is defined as the first unit "per" the second.
As well as a ratio of two units, a per unit can be of the form "currency per unit". The module recognizes "$" and "£" as currency symbols and shows them appropriately. For example, the input |120|$/acre would be displayed as "$120 per acre", or "$120/acre" if abbreviated.
The definition for a per unit can be followed by the same modifiers available for an alias.
Should be
Some unit codes should not be used—if such a code is used, the template displays an error message telling the editor what unit code should be entered. For example, the code feet should not be used, and that is indicated by entering !Message in the Symbol column for the feet entry. There should be no other entries on an error line. The Message text is displayed as an error if feet is used in a conversion. The text should use the special format codes %{ and %} on each side of a unit code. The format codes are replaced with wikitext defined in Module:Convert, and which applies a consistent style to each displayed unit code.
Use name
Some units generally use their name, rather than a symbol. That is indicated by inserting ~ before the symbol. For example, the code acre has symbol ~acre which means results will use the singular name "acre", or the plural name "acres", depending on the value.
Use unit code for default
Some units have a symbol prefixed with *, for example, the symbol given for pitch is *µm. Normally, when units are looked up in the Defaults or Links exception tables, the symbol of the unit is used. However, pitch has a symbol that conflicts with micrometre. The * prefix means that the unit code for pitch is used to look up exceptions, not the symbol.
SI prefixes
The prefix column should be empty if SI prefixes are not used, SI for a unit that accepts SI prefixes, SI2 for a unit code that indicates a base unit squared, and SI3 for cubed. For example when defining unit code m2 put SI2 here, and for m3 say SI3. This will scale, for example, km2 to 1000 × 1000 of the base unit, m, or scale mm3 to 0.001 × 0.001 × 0.001 of the base unit m.
Name
The name of the unit is required. The plural name is optional. If no plural name is given, it is created by appending "s" to the singular name. For example, the ft unit has name "foot" and plural name "feet"—the plural name is necessary to avoid the plural of "foot" being "foots".
The US name is optional. If no US name is given, it is the same as the normal name. The US plural name is optional—if it is missing it is created by appending "s" to the US name. When using {{convert}}, the option |sp=us causes the US name to be displayed if a name is required for the convert.
Any %s in the name columns is replaced with the appropriate SI prefix, or is removed if SI prefixes are not appropriate (not suitable for the unit, or not used in the conversion). It is only necessary to use %s if the unit accepts prefixes, and if the prefix is not at the start of the unit's name, for example with m2 and m3.
Exceptions
Spelling exceptions can be handled by entering a row with the exception. For example, see ha which sets the unit name to "hectare"; without that row, the a row would cause ha to have the name "hectoare". There must be an override to document that an exception is intended.
Scale
The scale is a value or expression that is used as a factor to convert a value to its corresponding base unit. Commas may be used as a thousand separator (e.g. 1,000,000) or e notation may be used (e.g. 1e6). Fractions should be used when required for exactness (e.g. 1/12).
Extra
The Extra column is usually empty, but can contain a value or code when more than a simple Scale is required for a conversion. There are two codes used with fuel efficiency units: volume/length and length/volume. In addition, certain codes are required to indicate that the conversion procedure for the unit is built-in to the module. Any other text is used as an offset in the conversion calculation that occurs with temperature units.
Built-in units
The conversion procedure for some units (for example, the Mach unit of speed) are built into Module:Convert as they are too complex to be specified in a table. That is indicated by entering a code (which must be the same as used in the module) in the Extra column.
The script that reads this page contains a small amount of built-in data that does not conveniently fit into the tables below (see set_builtins in makeunits).
Default
A default is a code for a unit or combination that identifies the output unit or units that will be used if none is specified in the convert template. The Defaults section defines exceptions for unit codes with an SI prefix, where the default output is different from that of the base unit. Also, units using engineering notation may appear in the defaults section to define a default output for the unit.
A default may specify a unit code or an expression that tests the input value, and which produces one of two different outputs depending on that value. In the expression, v represents the input value specified in the convert template, and exclamation marks (!) are used to separate the expression into either three or four fields. For example, the following expression might be used as the default for unit in (inch):
v < 36 ! mm ! cm
The first field is a condition which evaluates to true or false. In this example, if the input value is less than 36, the default output unit is mm; otherwise, it is cm.
If present, the fourth field is appended to the result. For example, the following expression might be used for unit Ml (megalitre):
v < 28.316846592 ! e3 ! e6 ! cuft
If the condition is true, the result is e3cuft; otherwise, it is e6cuft.
Composite
A composite input unit consists of two standard units, where the second is a subdivision of the first. For example, |2|ft|6|in may be used to specify 2 feet 6 inches as the input unit in a conversion. See the Input multiples section.
Composites are defined in pairs, but any number of pairs can be used to specify an input. For example, given that ch is defined as a subdivision of mi, and that ft is a subdivision of ch, an input length could be specified as 1|mi|2|ch|3|ft. Also, with suitable pairs defined, an input length could be specified as 4|mi|3|yd|2|ft|1|in. There is no limit to the number of permitted subunits.
Multiple
A multiple is a unit code that can be used as an output. For example, ftin is a multiple that results in a length being expressed in feet and inches. A multiple may have any number of components defined in the Output multiples section, where each component is a subdivision of the preceding unit.
Link
The link column is the title of the article related to that unit. If the link is preceded with + or *, extra text will be inserted before the link, and the text shown by the link will be adjusted to omit a prefix of "US" or "U.S.", if present. For example, if a unit has the symbol "US gal" (or "U.S. gal"), and if the link is +[[Gallon]], then if the symbol is linked, it would appear as "USgal" ("US" and "gal" link to two different articles). If the link is *[[Gallon]], it would appear as "U.S.gal".
Similarly, if the link is preceded with @, extra text will be inserted before the link, and the text shown by the link will be adjusted to omit a prefix of "imp" or "imperial", if present. For example, if a unit has the symbol "imp gal", and if the link is @[[Gallon]], then if the symbol is linked, it would appear as "impgal" ("imp" and "gal" link two different articles).
The Links section defines exceptions for unit codes with an SI prefix, where the linked article is different from that of the base unit.
Pipe characters (|) in a table need to be encoded. For example, "[[Gallon|gal]]" should be entered as "[[Gallon|gal]]". The script that reads this page replaces each | with |.
Override
Some unit codes match a unit with an SI prefix, and duplicate unit codes are not permitted. For example, Pa can be interpreted as "peta-are" which would prevent the pascal unit of pressure being defined after the are unit of area. However, listing Pa in the Overrides section means that the pascal unit can be defined, in which case peta-are will not be available.
Conventions
Some unit codes are not intended to be used in a template, but are needed to define exceptions. For example, the code ft has link Foot (unit), but unit psi/ft needs ft to be linked to Fracture gradient. To handle such cases, a unit code starting with "-" is used (-ft-frac for feet with a link to fracture gradient).
If needed, more dashes can be used to define additional exceptions (for example, see -Scwt and --Scwt, which are similar to Scwt but have different names).
Engineering notation
In addition to the units defined in the data below, large scale units such as e6km (million kilometres) may be used. The following prefixes may be used, and the linked names are shown if |lk=on:
Any standard unit (not a combination, multiple, or built-in) may be used after an engineering notation prefix, including "temperature change" units, but not "temperature" units.
However, some topics use traditional units that conflict with the above convention. To handle these, Module:Convert/makeunits includes a specials table that adds an "alttype" (alternate type) field to certain whitelisted units. The alttype field allows conversion between units of different type, provided each unit is whitelisted to allow the conversion.
As at December 2013, the following energy units have alttype = "torque" (the first line consists of different units, while the second line consists of aliases for units in the first line):
The following tables define composite input units consisting of multiple unit codes. A composite must consist of two unit codes where the second is a subdivision of the first. In addition, a default output must be specified. Optionally, an alternate unit code or name can be specified. An alternate unit must have the same scale as that of the subdivision, but may have a different name or symbol.
If both an alternate unit and name are provided, the unit will be used when the input consists of only two components, and the alternate name will be used with three or more (generally, the alternate name would be shorter than the unit's standard name or symbol, and that may be desirable when three or more units make up an input composite).
If an alternate name is used, it replaces the unit's symbol and name and plural name. In other words, the same alternate name applies regardless of whether the unit is abbreviated, and regardless of the number of units.
If the unit yd allows ft as a subdivision, and ft allows in, then the input to a conversion can use all three units (for example, {{convert|1|yd|2|ft|3|in}} which specifies the input as 1 yard, 2 feet, 3 inches). There is no limit to the number of units that can be used in an input multiple.
To simplify processing by the script which extracts data from this wikitext, a unit code is required in the first column; that unit code is not used. This section is read after all units and combinations are defined, so the unit codes may refer to items defined anywhere on this page.
Area
Composite code
Unit code
Unit code
Default
Alternate
Name
_acre_rood
acre
rood
ha
_acre_sqperch
acre
sqperch
ha
_rood_sqperch
rood
sqperch
m2
Length
Composite code
Unit code
Unit code
Default
Alternate
Name
_ch_ft
ch
ft
m
_ch_yd
ch
yd
m
_chain_ft
chain
ft
m
_chain_yd
chain
yd
m
_foot_in
foot
in
m
_ft_in
ft
in
m
_mi_ch
mi
ch
km
_mi_chlk
mi
chlk
km
_mi_chain
mi
chain
km
_mi_chainlk
mi
chainlk
km
_mi_ft
mi
ft
km
_mi_furlong
mi
furlong
km
_mi_yd
mi
yd
km
_smi_chain
smi
chain
km
_yd_ft
yd
ft
m
Mass
Composite code
Unit code
Unit code
Default
Alternate
Name
_lb_oz
lb
oz
kg
_Lcwt_qtr
Lcwt
qtr
kg
_Lcwt_st
Lcwt
st
kg
_long_cwt_qtr
long cwt
qtr
kg
_LT_Lcwt
LT
Lcwt
t
-Lcwt
_lt_Lcwt
lt
Lcwt
t
-Lcwt
_qtr_lb
qtr
lb
kg
_st_lb
st
lb
kg lb
_ST_Scwt
ST
Scwt
t
-Scwt
Output multiples
The following tables define the "multiple" unit codes that can be used for an output unit. Using a multiple code for the output means that the conversion result contains multiple components (for example, a length expressed in yards, feet, inches).
Length
Multiple code
Unit code
Unit code
Unit code
Unit code
mich
mi
ch
michlk
mi
chlk
michainlk
mi
chainlk
miyd
mi
yd
miydftin
mi
yd
ft
in
mift
mi
ft
ydftin
yd
ft
in
ydft
yd
ft
ftin
ft
in
footin
foot
in
handin
hand
in
Mass
Multiple code
Unit code
Unit code
Unit code
Unit code
lboz
lb
oz
stlb
st
lb
stlboz
st
lb
oz
st and lb
st
lb
Combinations
The following tables list predefined "combination" unit codes that can be used for an output unit. Using a combination code for the output means that the input value is converted to more than one unit. In addition to the combinations listed here, units may be combined by separating unit codes with a space or plus character.
Force
Combination code
Unit code
Unit code
Unit code
Unit code
GN LTf
GN
-LTf
GN LTf STf
GN
-LTf
-STf
GN STf
GN
-STf
GN STf LTf
GN
-STf
-LTf
kN LTf
kN
-LTf
kN LTf STf
kN
-LTf
-STf
kN STf
kN
-STf
kN STf LTf
kN
-STf
-LTf
LTf STf
-LTf
-STf
MN LTf
MN
-LTf
MN LTf STf
MN
-LTf
-STf
MN STf
MN
-STf
MN STf LTf
MN
-STf
-LTf
STf LTf
-STf
-LTf
Fuel efficiency
Combination code
Unit code
Unit code
Unit code
Unit code
L/100 km mpgimp
L/100 km
mpgimp
l/100 km mpgimp
l/100 km
mpgimp
L/100 km mpgUS
L/100 km
mpgus
L/100 km mpgus
L/100 km
mpgus
l/100 km mpgus
l/100 km
mpgus
mpgimp L/100 km
mpgimp
L/100 km
Mass
Combination code
Unit code
Unit code
Unit code
Unit code
LT ST t
lt
-ST
t
LT t ST
lt
t
-ST
ST LT t
-ST
lt
t
ST t LT
-ST
t
lt
t LT ST
t
lt
-ST
ton
LT
ST
Pressure
Combination code
Unit code
Unit code
Unit code
Unit code
kPa kg/cm2
kPa
kgf/cm2
kPa lb/in2
kPa
-lb/in2
Volume
Combination code
Unit code
Unit code
Unit code
Unit code
floz
impoz
USoz
Defaults
The following tables define default outputs for unit codes that use an SI prefix or an engineering notation prefix, where the default output is different from that of the base unit.
Area
Unit code
Default output
cm2
sqin
dm2
sqin
e3acre
km2
e3m2
e6sqft
e6acre
km2
e6ha
e6acre
e6km2
e6sqmi
e6m2
e6sqft
e6sqft
v * 9.290304 < 100 ! e3 ! e6 ! m2
e6sqmi
e6km2
hm2
acre
km2
sqmi
mm2
sqin
Energy
Unit code
Default output
aJ
eV
e3BTU
MJ
e6BTU
GJ
EJ
kWh
fJ
keV
GJ
kWh
MJ
kWh
PJ
kWh
pJ
MeV
TJ
kWh
YJ
kWh
yJ
μeV
ZJ
kWh
zJ
meV
Flow
Unit code
Default output
e12cuft/a
v * 2.8316846592 < 100 ! e9 ! e12 ! m3/a
e12cuft/d
v * 2.8316846592 < 100 ! e9 ! e12 ! m3/d
e12m3/a
Tcuft/a
e12m3/d
Tcuft/d
e3cuft/a
v * 2.8316846592 < 100 ! ! e3 ! m3/a
e3cuft/d
v * 2.8316846592 < 100 ! ! e3 ! m3/d
e3cuft/s
v * 2.8316846592 < 100 ! ! e3 ! m3/s
e3m3/a
v < 28.316846592 ! k ! M ! cuft/a
e3m3/d
v < 28.316846592 ! k ! M ! cuft/d
e3m3/s
v < 28.316846592 ! k ! M ! cuft/s
e3USgal/a
v * 3.785411784 < 1000 ! ! e3 ! m3/a
e6cuft/a
v * 2.8316846592 < 100 ! e3 ! e6 ! m3/a
e6cuft/d
v * 2.8316846592 < 100 ! e3 ! e6 ! m3/d
e6cuft/s
v * 2.8316846592 < 100 ! e3 ! e6 ! m3/s
e6m3/a
v < 28.316846592 ! M ! G ! cuft/a
e6m3/d
v < 28.316846592 ! M ! G ! cuft/d
e6m3/s
v < 28.316846592 ! e6 ! e9 ! cuft/s
e6USgal/a
v * 3.785411784 < 1000 ! e3 ! e6 ! m3/a
e9cuft/a
m3/a
e9cuft/d
v * 2.8316846592 < 100 ! e6 ! e9 ! m3/d
e9m3/a
v < 28.316846592 ! G ! T ! cuft/a
e9m3/d
v < 28.316846592 ! G ! T ! cuft/d
e9m3/s
v < 28.316846592 ! e9 ! e12 ! cuft/s
e9USgal/a
v * 3.785411784 < 1000 ! e6 ! e9 ! m3/a
e9USgal/s
v * 3.785411784 < 1000 ! e6 ! e9 ! m3/s
Force
Unit code
Default output
nN
gr-f
μN
gr-f
mN
oz-f
Length
Unit code
Default output
am
in
cm
in
dam
ft
dm
in
e12km
e12mi
e12mi
e12km
e3AU
ly
e3km
e3mi
e3mi
e3km
e6km
e6mi
e6mi
e6km
e9km
AU
e9mi
e9km
Em
mi
fm
in
Gm
mi
hm
ft
km
mi
mm
in
Mm
mi
nm
in
Pm
mi
pm
in
Tm
mi
Ym
mi
ym
in
Zm
mi
zm
in
μm
in
Mass
Unit code
Default output
e12lb
v * 4.5359237 < 10 ! Mt ! Gt
e3lb
v * 4.5359237 < 10 ! kg ! t
e3ozt
v * 0.311034768 < 10 ! kg ! t
e3t
LT ST
e6carat
t
e6lb
v * 4.5359237 < 10 ! t ! kilotonne
e6ozt
lb kg
e6ST
Mt
e6t
LT ST
e9lb
v * 4.5359237 < 10 ! kilotonne ! Mt
e9t
LT ST
Gg
lb
kg
lb
mg
gr
Mg
LT ST
ng
gr
μg
gr
Radioactivity
Unit code
Default output
mBq
fCi
kBq
nCi
MBq
μCi
GBq
mCi
TBq
Ci
PBq
kCi
EBq
kCi
fCi
mBq
pCi
Bq
nCi
Bq
μCi
kBq
mCi
MBq
kCi
TBq
MCi
PBq
Time
Unit code
Default output
ns
μs
μs
ms
ms
s
ks
h
Ms
week
Gs
decade
Ts
millennium
Ps
million year
Es
thousand million year
Temperature
Unit code
Default output
MK
keVT
Volume
Unit code
Default output
cL
impoz usoz
cl
impoz usoz
cm3
cuin
dL
impoz usoz
dl
impoz usoz
mm3
cuin
dm3
cuin
e12cuft
v * 2.8316846592 < 100 ! e9 ! e12 ! m3
e12impgal
v * 4.54609 < 1000 ! T ! P ! l
e12m3
v < 28.316846592 ! T ! P ! cuft
e12U.S.gal
v * 3.785411784 < 1000 ! T ! P ! l
e12USgal
v * 3.785411784 < 1000 ! T ! P ! l
e15cuft
v * 2.8316846592 < 100 ! e12 ! e15 ! m3
e15m3
Pcuft
e3bdft
v * 0.23597372167 < 100 ! e3 ! e6 ! m3
e3cuft
v * 2.8316846592 < 100 ! ! e3 ! m3
e3impgal
v * 4.54609 < 1000 ! k ! M ! l
e3m3
v < 28.316846592 ! k ! M ! cuft
e3U.S.gal
v * 3.785411784 < 1000 ! k ! M ! l
e3USgal
v * 3.785411784 < 1000 ! k ! M ! l
e6bdft
v * 0.23597372167 < 100 ! e3 ! e6 ! m3
e6cuft
v * 2.8316846592 < 100 ! e3 ! e6 ! m3
e6cuyd
v * 7.64554857984 < 10 ! e3 ! e6 ! m3
e6impgal
v * 4.54609 < 1000 ! M ! G ! l
e6L
USgal
e6m3
v < 28.316846592 ! M ! G ! cuft
e6U.S.gal
v * 3.785411784 < 1000 ! M ! G ! l
e6USgal
v * 3.785411784 < 1000 ! M ! G ! l
e9bdft
v * 0.23597372167 < 100 ! e6 ! e9 ! m3
e9cuft
v * 2.8316846592 < 100 ! e6 ! e9 ! m3
e9impgal
v * 4.54609 < 1000 ! G ! T ! l
e9m3
v < 28.316846592 ! G ! T ! cuft
e9U.S.gal
v * 3.785411784 < 1000 ! G ! T ! l
e9USgal
v * 3.785411784 < 1000 ! G ! T ! l
GL
cuft
Gl
cuft
kL
cuft
kl
cuft
km3
cumi
mL
impoz usoz
ml
impoz usoz
Ml
v < 28.316846592 ! e3 ! e6 ! cuft
ML
v < 28.316846592 ! e3 ! e6 ! cuft
TL
cumi
Tl
cumi
μL
cuin
μl
cuin
Links
The following tables define links for unit codes that use an SI prefix, where the linked article is different from that of the base unit.
The following table defines equivalent unit types for some of the types that can be generated automatically for unit codes of the form x/y (x per y). For example, the unit code kg/hl is not defined, so if it were used, it would be regarded as kilograms per hectolitre with unit type mass/volume; the following table would translate that to density so the unit could be converted with other density units. If "Density" is specified in the Link column, the unit name or symbol would be linked to Density if |lk=on is used.
In addition, a scale multiplier can be specified; that allows mass/area units to be converted to pressure units on the assumption that the mass refers to the force due to the "weight" of an object.
Type/type
Equivalent unit type
Link
Multiplier
/area
per unit area
/volume
per unit volume
area/area
area per unit area
energy/length
energy per unit length
energy/mass
energy per unit mass
energy/time
power
Power (physics)
energy/volume
energy per unit volume
force/area
pressure
Pressure
length/length
gradient
Grade (slope)
length/time
speed
Speed
length/time/time
acceleration
Acceleration
mass/area
pressure
9.80665
mass/length
linear density
mass/mass
concentration
mass/power
mass per unit power
mass/time
mass per unit time
mass/volume
density
Density
power/mass
power per unit mass
power/volume
Power density
pressure/length
fracture gradient
speed/time
acceleration
Acceleration
volume/area
volume per unit area
volume/length
volume per unit length
volume/time
flow
Overrides
The following tables define "override" unit codes which conflict with another unit when it is combined with one of the SI prefixes. The script which processes this page rejects unit codes that duplicate a known entry, however, that checking is not performed for the unit codes listed here. The Comment field documents the conflict, but is otherwise ignored.
Area
Override code
Comment
daa
Override default prefix which would give name "decaare".
ha
Override default prefix which would give name "hectoare".