View source for Template:Convert/doc

{{documentation subpage}}
{{hatnote|'''See [[Help:Convert]] for up-to-date and more complete information'''}}
{{Lua|Module:Convert|Module:Convert/data|Module:Convert/extra|Module:Convert/text}}
'''Template {{tl|convert}}''' ''calculates'' measurements from one unit (you entered) to another one, and then ''presents the results''. For example:
:<code><nowiki>{{convert|1|km|mi}}</nowiki></code> &rarr; {{convert|1|km|mi}}
:<code><nowiki>{{convert|7|mi|km}}</nowiki></code> &rarr; {{convert|7|mi|km}}<br>
That's all.
==Usage==
===Basic examples===
{| class="wikitable"
|'''Input'''||'''Displays as'''
|-
|<nowiki>{{convert|3.21|kg|lb}}</nowiki>||{{convert|3.21|kg|lb}}
|-
|<nowiki>{{convert|3.21|kg|lb|0}}</nowiki>||{{convert|3.21|kg|lb|0}}
|-
|<nowiki>{{convert|10|kg|lb|disp=or}}</nowiki>||{{convert|10|kg|lb|disp=or}}
|-
|<nowiki>{{convert|6|ft|5|in|m}}</nowiki>||{{convert|6|ft|5|in|m}}
<!--This is currently broken, see talk page
|-
|<nowiki>{{convert|2|m|ftin}}</nowiki>||{{convert|2|m|ftin}}
-->
|-
|<nowiki>{{convert|10|mi}}</nowiki>||{{convert|10|mi}}
|-
|<nowiki>{{convert|100|mpgus}}</nowiki>||{{convert|100|mpgus}}
|-
|<nowiki>{{convert|120|km/h}}</nowiki>||{{convert|120|km/h}}
|-
|<nowiki>{{convert|18|°C|°F}}</nowiki>||{{convert|18|°C|°F}}
|-
|<nowiki>{{convert|-15|C|F}}</nowiki>||{{convert|-15|C|F}}
|-
|<nowiki>{{convert|9|e6USgal|abbr=off}}</nowiki>||{{convert|9|e6USgal|abbr=off}}<br>The "e6" scales the input to millions; the "abbr=off" yields the "mega" in the output.<br>Scaling is only available for Single value conversions.  Not all units are supported.
|-
| <nowiki>{{convert|1250|sqft|m2|lk=in|sigfig=2}}</nowiki> ||{{convert|1250|sqft|m2|lk=in|sigfig=2}}<br/>Note 'lk=in' links only the input unit. This example is for illustration only, common units of measurement should not be linked. See: [[Wikipedia:Only make links that are relevant to the context|wp:overlink]].
|-
|<nowiki>{{convert|20.5|m3|cuyd|lk=out|abbr=on}}</nowiki>||{{convert|20.5|m3|cuyd|1|lk=out|abbr=on}}<br/>Note 'lk=out' links only the output unit, [[cu yd]].
|-
|<nowiki>{{convert|641|acre|ha sqmi|lk=on}}</nowiki>||{{convert|641|acre|ha sqmi|lk=on}}<br/>Note 'lk=on' links all units. Per guidelines, common units should not be linked. See: [[Wikipedia:Only make links that are relevant to the context|wp:overlink]].
|-
|<nowiki>{{convert|641|acre|ha sqmi|2|lk=on}}</nowiki>||{{convert|641|acre|ha sqmi|2|lk=on}}<br/> Although 640 acres equals 1 square mile; 641 acres rounded to two decimal places equals 1.00&nbsp;sq&nbsp;mi.
|}

==Options==
===Unit name or abbreviation (symbol): ''1 pound'' or ''1 lb''?===
{{para|abbr|on}} will produce the unit's ''symbol'':
:<code><nowiki>{{convert|1|lb|kg}}</nowiki></code> &rarr; {{convert|1|lb|kg}}
:<code><nowiki>{{convert|1|lb|kg|abbr=on}}</nowiki></code> &rarr; {{convert|1|lb|kg|abbr=on}}

===Adjective: ''a 10-mile distance''===
Use {{para|adj|on}} to produce the adjective form. The difference:
:<code><nowiki>{{convert|10|mi|km}} to go</nowiki></code> &rarr; {{convert|10|mi|km}} to go. -- Regular
:<code><nowiki>A {{convert|10|mi|km|adj=on}} distance</nowiki></code> &rarr; A {{convert|10|mi|km|adj=on}} distance. -- Adjective

===Rounding: ''123 ft'' is ''40&nbsp;m'' or ''37&nbsp;m'' or ''37.5&nbsp;m''?===
''Convert'' supports four types of rounding:
;Rounding to a given precision
:Specify the desired precision with the fourth unnamed parameter (or third unnamed parameter if the "convert to" parameter is omitted; or fifth unnamed parameter if a range is specified; or fourth unnamed parameter again if a range is specified and the "convert to" parameter is omitted; needs to be replaced with a "precision" named parameter).  The conversion is rounded off to the nearest power of {{frac|10}} this number.  For instance, if the result is 8621 and the round number is '-2', the result will be 8600.  If the result is '234.0283043' and the round number is '0', the result will be 234.

;Rounding to a given number of significant figures
:Specify the desired number of significant figures using <code><nowiki>|sigfig={some integer greater than zero}</nowiki></code> as noted above.

;Default rounding
:If neither the desired precision nor the desired number of significant figures is specified, the conversion will be rounded either to precision comparable to that of the input value (the number of digits after the decimal point—or the negative of the number of non-significant zeroes before the point—is increased by one if the conversion is a multiplication by a number between 0.02 and 0.2, remains the same if the factor is between 0.2 and 2, is decreased by 1 if it is between 2 and 20, and so on) or to two significant figures, whichever is more precise. An exception to this is temperature, wherein the conversion will be rounded either to precision comparable to that of the input value or to that which would give three significant figures when expressed in kelvins, whichever is more precise.

{| class="wikitable"
|-
! colspan="3" | Examples of default rounding
|-
|'''Input'''||'''Displays as'''||'''Note'''
|-
|<nowiki>{{convert|123|ft|m|-1}}</nowiki>||{{convert|123|ft|m|-1}}  ||
|-
|<nowiki>{{convert|123|ft|m|0}}</nowiki>||{{convert|123|ft|m|0}}  ||
|-
|<nowiki>{{convert|123|ft|m|1}}</nowiki>||{{convert|123|ft|m|1}}  ||
|-
|<nowiki>{{convert|550|ft|m|0}}</nowiki>||{{convert|550|ft|m|0}}  || Approximate value is 167.64 m
|-
|<nowiki>{{convert|550|ft|m}}</nowiki>||{{convert|550|ft|m}} || Rounds to 170, when approximate value is 167.64 m
|-
|<nowiki>{{convert|500|ft|m|0}}</nowiki>||{{convert|500|ft|m|0}}  ||  Approximate value is 152.4 m
|-
|<nowiki>{{convert|500|ft|m}}</nowiki>||{{convert|500|ft|m}}  ||   Rounds to 150, when approximate value is 152.4 m
|}<!--NOTE: rows require "nowiki", using &#123;{ disappears. -->

===Range of values: ''6 to 17 kg (13 to 37 lb)''===
Range indicators are entered as the second parameter (between the values). Range separators can be:<br>
:<code>to</code>, <code>-</code> <small>(ndash or hyphen)</small>, <code>or</code>, <code>and</code>, <code>to(-)</code>, <code>+/-</code>:
:<code><nowiki>{{convert|6|to|17|kg|lb|abbr=on}}</nowiki></code> &rarr; {{convert|6|to|17|kg|lb|abbr=on}}
:<code><nowiki>{{convert|-10|to|-20|C}}</nowiki></code> &rarr; {{convert|-10|to|-20|C}}
:<code><nowiki>{{convert|6|and|17|kg|lb}}</nowiki></code> &rarr; {{convert|6|and|17|kg|lb}}
:<code><nowiki>{{convert|6|to(-)|17|kg|lb}}</nowiki></code> &rarr; {{convert|6|to(-)|17|kg|lb}}
:<code><nowiki>{{convert|60|+/-|10|m|ft}}</nowiki></code> &rarr; {{convert|60|+/-|10|m|ft}}

===Multiple dimensions: ''6 by 12 feet (1.8 by 3.7 m)''===
:<code><nowiki>{{convert|6|by|12|ft|m}}</nowiki></code> &rarr; {{convert|6|by|12|ft|m}}
:<code><nowiki>{{convert|6|x|12|m|ft}}</nowiki></code> &rarr; {{convert|6|x|12|m|ft}}

===Brackets and separators: ''2.4 m, 7.9 ft''===
Brackets and separators are set by {{para|disp|}}:
:<code><nowiki>{{convert|2.4|m|ft}}</nowiki></code> &rarr; {{convert|2.4|m|ft}} -- ''default''
:<code><nowiki>{{convert|2.4|m|ft|disp=sqbr}}</nowiki></code> &rarr; {{convert|2.4|m|ft|disp=sqbr}}
:<code><nowiki>{{convert|2.4|m|ft|disp=comma}}</nowiki></code> &rarr; {{convert|2.4|m|ft|disp=comma}}
:<code><nowiki>{{convert|2.4|m|ft|disp=slash}}</nowiki></code> &rarr; {{convert|2.4|m|ft|disp=slash|abbr=on}}
:<code><nowiki>{{convert|2.4|m|ft|disp=br}}</nowiki></code> &rarr; {{convert|2.4|m|ft|disp=br}}

===Spelling of units: UK ''metre'' or US ''meter''?===
Default spelling of units is en-UK. To show en-US spelling, use {{para|sp|us}}:
:<code><nowiki>{{convert|1|m|ft}}</nowiki></code> &rarr; {{convert|1|m|ft}} -- ''default''
:<code><nowiki>{{convert|1|m|ft|sp=us}}</nowiki></code> &rarr; {{convert|1|m|ft|sp=us}}

===Spell out numbers: ''ten miles''===
To write a number in words, use {{para|spell|in}}:
:<code><nowiki>{{convert|10|mi|m|spell=in}}</nowiki></code> &rarr; {{convert|10|mi|m|spell=in}}

To spell out both in and out values, use {{para|spell|on}}:
:<code><nowiki>{{convert|10|mi|m|spell=on}}</nowiki></code> &rarr; {{convert|10|mi|m|spell=on}}

To make first letter a capital, use {{para|spell|In}}, {{para|spell|On}}
:<code><nowiki>{{convert|10|mi|m|spell=In}}</nowiki></code> &rarr; {{convert|10|mi|m|spell=In}}
:<code><nowiki>{{convert|10|mi|m|spell=On}}</nowiki></code> &rarr; {{convert|10|mi|m|spell=On}}

Remember that the spelling of the units (ft, m) is independently set by {{para|abbr|}}. To the extreme:
:<code><nowiki>{{convert|10|mi|m|spell=on|abbr=off|sp=us}}</nowiki></code> &rarr; {{convert|10|mi|m|spell=on|abbr=off|sp=us}}

===Extra words: ''4 planted acres'' ===
:''Incomplete secion'':
:<code><nowiki>{{convert|4|acre||adj=pre|planted}}</nowiki></code> &rarr; {{convert|4|acre||adj=pre|planted}}

== Table options ==
For the [[Help:Table/Manual tables|wikitable]] structure, there are two options: split over columns and make the table sortable.
=== Result split over columns in a table ===
Using {convert} in a table cell, with {{para|disp|table}} splits the result over two columns:
:<code><nowiki>{{convert|10|m|ft|disp=table}}</nowiki></code> &rarr; {{convert|10|m|ft|disp=table}}

{{para|disp|tablecen}} does the same, and also centers the text:
:<code><nowiki>{{convert|20|m|ft|disp=tablecen}}</nowiki></code> &rarr; {{convert|20|m|ft|disp=tablecen}}

The units are added as a column header:
:{| class=wikitable
!
! m
! ft
|-
| {{para|disp|table}}
| {{convert|10|m|ft|disp=table}}
|-
|{{para|disp|tablecen}}
| {{convert|20|m|ft|disp=tablecen}}
|-
|{{para|disp|&lt;other>}} <small>(default)</small>
|{{convert|30|m|ft|disp=}}
|}

=== Sorting ===
:Use both {{para|disp|table}} {{para|sortable|on}} to make a table column sortable. Only the first column will sort correct.

:<nowiki>{{convert|10|m|ft|disp=table|sortable=on}}</nowiki> &rarr; ''<small>(don't let this frighten you)</small>''
{{convert|10|m|ft|disp=table|sortable=on}}

:{| class="wikitable sortable"
! m
! ft
|-
| {{convert|10|m|ft|disp=table|sortable=on}}
|-
| {{convert|20|m|ft|disp=table|sortable=on}}
|-
| {{convert|30|m|ft|disp=table|sortable=on}}
|}

==Units overview==
{{selfref|See also: complete [[Template:Convert/list of units|Convert/list of units]]}}
<div style="height: 400px; overflow: auto; padding: 3px; border: 1px solid #aaa;">
{{Convert/list of units}}
</div>

==Parameter list==
{| class="wikitable"
! Option !! Description
|-
| <code>&#124;abbr=comma</code> || No comma in input or output numbers.
|-
| <code>&#124;abbr=in</code> || Use symbol for LHS unit.
|-
| <code>&#124;abbr=off</code> || Use name for all units.
|-
| <code>&#124;abbr=on</code> || Use symbol for all units.
|-
| <code>&#124;abbr=out</code> || Use symbol for RHS unit (default).
|-
| <code>&#124;abbr=values</code> || Show only input and output numbers, not units.
|-
| <code>&#124;abbr=~</code> || Show input unit symbol as well as name.
|-
| <code>&#124;adj=1</code> || Unit name is singular when value is 1 or less, but not zero.
|-
| <code>&#124;adj=flip</code> || Reverse order of input/output.
|-
| <code>&#124;adj=j</code> || Join value and unit name using "&amp;nbsp;" instead of a space.
|-
| <code>&#124;adj=mid</code> || Same as <code>adj=on</code> with user-specified text after input unit.
|-
| <code>&#124;adj=nocomma</code> || No comma in input or output numbers.
|-
| <code>&#124;adj=on</code> || Unit name is singular and hyphenated.
|-
| <code>&#124;adj=pre</code> || User-specified text before input unit.
|-
| <code>&#124;adj=ri1</code> || Round input with precision 1.
|-
| <code>&#124;adj=ri2</code> || Round input with precision 2.
|-
| <code>&#124;adj=ri3</code> || Round input with precision 3.
|-
| <code>&#124;disp=/</code> || Join input/output using "/".
|-
| <code>&#124;disp=2</code> || Display only output value and symbol/name.
|-
| <code>&#124;disp=5</code> || Round output value to nearest 5.
|-
| <code>&#124;disp=b</code> || Join input/output using "(...)".
|-
| <code>&#124;disp=br</code> || Join input/output using "&lt;br/>".
|-
| <code>&#124;disp=comma</code> || Join input/output using ",".
|-
| <code>&#124;disp=flip</code> || Reverse order of input/output.
|-
| <code>&#124;disp=flip5</code> || Same as <code>disp=flip</code> with <code>disp=5</code>.
|-
| <code>&#124;disp=nocomma</code> || No comma in input or output numbers.
|-
| <code>&#124;disp=number</code> || Display output value only.
|-
| <code>&#124;disp=or</code> || Join input/output using "or".
|-
| <code>&#124;disp=out</code> || Same as <code>disp=2</code>.
|-
| <code>&#124;disp=output number only</code> || Same as <code>disp=number</code>.
|-
| <code>&#124;disp=output only</code> || Same as <code>disp=2</code>.
|-
| <code>&#124;disp=preunit</code> || User-specified text before input and output units.
|-
| <code>&#124;disp=s</code> || Same as <code>disp=/</code>.
|-
| <code>&#124;disp=slash</code> || Same as <code>disp=/</code>.
|-
| <code>&#124;disp=sqbr</code> || Join input/output using "[...]".
|-
| <code>&#124;disp=table</code> || Output is suitable for a table cell with align="right".
|-
| <code>&#124;disp=tablecen</code> || Output is suitable for a table cell with align="center".
|-
| <code>&#124;disp=u2</code> || Display output symbol/name (not input; not output value).
|-
| <code>&#124;disp=unit</code> || Display input symbol/name (not output; not input value).
|-
| <code>&#124;disp=unit2</code> || Same as <code>disp=u2</code>.
|-
| <code>&#124;disp=x</code> || Join input/output using user-specified text.
|-
| <code>&#124;comma=5</code> || Only use comma grouping if 5 or more digits.
|-
| <code>&#124;comma=gaps</code> || Use gaps, not comma, to separate groups of digits.
|-
| <code>&#124;comma=gaps5</code> || Use gaps, but only if 5 or more digits.
|-
| <code>&#124;debug=yes</code> || Make the normally hidden sort key visible.
|-
| <code>&#124;frac=''N''</code> || Display the output as fractions with ''N'' as the largest denominator.
|-
| <code>&#124;lk=in</code> || Link LHS unit name or symbol.
|-
| <code>&#124;lk=on</code> || Link all unit names or symbols (but not twice for the same unit).
|-
| <code>&#124;lk=out</code> || Link RHS unit name or symbol.
|-
| <code>&#124;sigfig=''N''</code> || Round output value to ''N'' significant figures (''N'' is a positive integer).
|-
| <code>&#124;sortable=on</code> || Output numeric hidden sort field for use in a sortable table.
|-
| <code>&#124;sp=us</code> || Use U.S. spelling (like "meter" instead of default "metre").
|-
| <code>&#124;spell=in</code> || Spell input value in words.
|-
| <code>&#124;spell=In</code> || Spell input value in words with first letter uppercase.
|-
| <code>&#124;spell=on</code> || Spell input and output values in words.
|-
| <code>&#124;spell=On</code> || Spell input and output values in words with first letter uppercase.
|}

Examples of number grouping:
*<code><nowiki>{{convert|1234|m|ft}}</nowiki></code> → {{convert|1234|m|ft}}
*<code><nowiki>{{convert|1234|m|ft|comma=5}}</nowiki></code> → {{convert|1234|m|ft|comma=5}}
*<code><nowiki>{{convert|12345|m|ft|comma=5}}</nowiki></code> → {{convert|12345|m|ft|comma=5}}
*<code><nowiki>{{convert|1234|m|ft|comma=gaps}}</nowiki></code> → {{convert|1234|m|ft|comma=gaps}}
*<code><nowiki>{{convert|1234|m|ft|comma=gaps5}}</nowiki></code> → {{convert|1234|m|ft|comma=gaps5}}
*<code><nowiki>{{convert|123,456,789|m|ft|comma=gaps5}}</nowiki></code> → {{convert|123,456,789|m|ft|comma=gaps5}}

Examples of spelling input values:
*<code><nowiki>{{convert|10|mi|km|spell=in}}</nowiki></code> → {{convert|10|mi|km|spell=in}}
*<code><nowiki>{{convert|10|mi|km|spell=In}}</nowiki></code> → {{convert|10|mi|km|spell=In}}
*<code><nowiki>{{convert|1/3|mi|km|adj=on|spell=in}}</nowiki></code> → {{convert|1/3|mi|km|adj=on|spell=in}}

==Options ''not'' supported==
===Free text in a range: ''12 m but not greater than 14 m''===
The range-indicator options like {{code|1=–}} are limited to a list (see above). It might be needed to use ''&lt;any text>'' in a conversion situation, to get a result like:
:<code>{{convert/2|12|but not greater than|14|m}}</code><br>
{{tl|convert}} does not have this option. One can use variant templates:
:<code><nowiki>{{</nowiki>'''convert/2'''<nowiki>|12|but not greater than|14|m}}</nowiki></code> &rarr;
:<code>{{convert/2|12|but not greater than|14|m}}</code>

For these situations, see the documentation of:
* {{tl|convert/2}}
* {{tl|convert/3}}
* {{tl|convert/4}}

==TemplateData==
{{TemplateDataHeader}}

<templatedata>{
"description": "Converts measurements to other units.",
"params": {
"1": {
  "label": "value",
  "description": "the value to convert",
  "type": "number"
},
"2": {
  "label": "from unit",
  "description": "",
  "type": "string/line"
},
"3": {
  "label": "to units",
  "description": "",
  "type": "string/line"
},
"4": {
  "label": "precision or suffix",
  "description": "significant digits after decimal dot or, if negative, exponent of ten",
  "type": "number"
},
"lk": {
  "label": "link units",
  "description": "“on” all, “in” input, “out” output or “off” no units",
  "default": "off",
  "type": "string/line"
},
"abbr": {
  "label": "abbreviation",
  "description": "show “on” unit symbols, “off” all unit names in full words, “in” abbreviated input units, “out” abbreviated output units or “values” no unit names",
  "type": "string/line"
},
"sp": {
  "label": "spelling",
  "description": "“us” US",
  "type": "string/line"
},
"adj": {
  "label": "adjective",
  "description": "adjective form (singular unit name appended by hyphen) “on” or “mid” to put conversion at end",
  "type": "string/line"
},
"disp": {
  "label": "conversion",
  "description": "show conversion … “or” after ‘or’, “b” in parentheses, “x” with custom prefix and suffix, “table”/“tablecen”, “output only” alone, “output number only” alone and without unit, “flip” first, “unit” not at all but input unit; if the value is a number it is used as precision",
  "default": "b",
  "type": "string/line"
},
"sigfig": {
  "label": "significant figures",
  "description": "number that sets the number of significant figures",
  "type": "number"
},
"sortable": {
  "label": "sort key",
  "description": "“on” generates a hidden sort key",
  "type": "string/line"
}
}}</templatedata>

==See also==
* [[Template:Convert/old]] - pre-2014 version
* [[:Category:Convert error categories]]
{{Math templates|conversion}}<noinclude>
[[Category:Subtemplates of Template Convert/documentation|Convert]]
</noinclude><includeonly>
<!-- ADD CATEGORIES BELOW THIS LINE -->
[[Category:Conversion templates| ]]
[[Category:Convert templates| ]]
[[Category:Inline cleanup templates]]
</includeonly>