View source for Template:Convert/doc

{{Documentation subpage}}
<!-- PLEASE ADD CATEGORIES AND INTERWIKIS AT THE BOTTOM OF THIS PAGE -->
'''Template {{tl|convert}}''' ''calculates'' from one measurement unit to another one, and then ''presents'' the results formatted. 

== Usage ==
For example:
: <code><nowiki>{{convert|2|km|mi}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|2|km|mi}} <small>(km entered, so converted into mile)</small>
: <code><nowiki>{{convert|7.1|mi|km}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|7.1|mi|km}} <small>(mi entered, so converted into km)</small>
: <code><nowiki>{{convert|7.0|mi|km}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|7.0|mi|km}} <small>(mi entered, so converted into km)</small>

''Numbers'' can be rounded, ''units'' can be abbreviated into symbols:
: <code><nowiki>{{convert|2|km|mi|2|abbr=on}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|2|km|mi|2|abbr=on}}
: <code><nowiki>{{convert|7|mi|km|2|abbr=on}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|7|mi|km|2|abbr=on}}

Value ''ranges'' can be entered using <code>|to|...</code> or <code>|-|...</code>:
: <code><nowiki>{{convert|2|to|5|km|mi}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|2|to|5|km|mi}}
: <code><nowiki>{{convert|2|-|5|km|mi}}</nowiki></code>  → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|2|-|5|km|mi}}

Combined effect example:
: <code><nowiki>{{convert|2|-|5|km|mi|2|abbr=on}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|2|-|5|km|mi|2|abbr=on}}
: <code><nowiki>{{convert|2|and|5|km|mi|sigfig=3|abbr=off}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|2|and|5|km|mi|sigfig=3|abbr=off}}

==Units to convert==
Enter units to convert:
* <code><nowiki>{{convert|1|lb|kg}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1|lb|kg}}

SI units generally accept prefixes, like "m" for milli (10<sup>−3</sup>), and "M" for mega (10<sup>6</sup>). For "per" units, use "/" (slash): kg/ha.

==Unit name or symbol (abbreviation): ''1 pound'' or ''1 lb''?==
By default, the first quantity shows unit name, the second shows the symbol (or abbreviation):
* <code><nowiki>{{convert|1|lb|kg}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1|lb|kg}}

Using {{para|abbr|in}} is the ''reverse behaviour'' to the default:
*<code><nowiki>{{convert|1|lb|kg|abbr=in}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1|lb|kg|abbr=in}}

To abbreviate both or neither:
* <code><nowiki>{{convert|1|lb|kg|abbr=on}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1|lb|kg|abbr=on}} 
* <code><nowiki>{{convert|1|lb|kg|abbr=off}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1|lb|kg|abbr=off}}

When using scientific notation, the default is for the second (converted) quantity to be displayed using scientific notation:
* <code><nowiki>{{convert|100|e6mi|e6km}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|100|e6mi|e6km}}

To display thousands, millions, etc., while abbreviating both input and output units use {{para|abbr|unit}}:
* <code><nowiki>{{convert|100|e6mi|e6km|abbr=unit}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|100|e6mi|e6km|abbr=unit}}

==Adjective: ''a 10-mile distance''==
Use {{para|adj|on}} to produce the adjectival (hyphenated) form:
* <code><nowiki>A {{convert|10|mi|km|adj=on}} distance</nowiki></code> → A {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10|mi|km|adj=on}} distance.
Default behaviour, for comparison:
* <code><nowiki>{{convert|10|mi|km}} to go</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10|mi|km}} to go.

Even with {{para|abbr|on}}, no hyphen is produced with unit symbols.

=={{anchor|Rounding}}Rounding: ''100 ft'' is ''30&nbsp;m'' or ''30.5&nbsp;m'' or ''30.48&nbsp;m''?==
{{hatnote|See [[w:Help:Convert#Rounding]] for a more mathematical description of the rounding options}}
By definition, 100&nbsp;ft equals {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|100|ft|m|sigfig=4|disp=out}}. In practical use, it is common to round the calculated metric number. With that, there are several possibilities.

===Default rounding===
By {{T|Convert}} default, the conversion result 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 ''rounding temperatures'' (see [[#Rounding temperatures|below]]).

{| class="wikitable"
|+ Examples of rounding
|-
! Input !! Displays as !! Note
|-
| <code><nowiki>{{convert|123|ft|m|-1}}</nowiki></code> || {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|123|ft|m|-1}} ||
|-
| <code><nowiki>{{convert|123|ft|m}}</nowiki></code> || {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|123|ft|m}} || Same output as with 0 (below)
|-
| <code><nowiki>{{convert|123|ft|m|0}}</nowiki></code> || {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|123|ft|m|0}} ||
|-
| <code><nowiki>{{convert|123|ft|m|1}}</nowiki></code> || {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|123|ft|m|1}} ||
|-
| <code><nowiki>{{convert|123|ft|m|2}}</nowiki></code> || {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|123|ft|m|2}} || Exact value is 37.4904 m
|-
| <code><nowiki>{{convert|500|ft|m|-1}}</nowiki></code> || {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|500|ft|m|-1}} ||
|-
| <code><nowiki>{{convert|500|ft|m}}</nowiki></code> || {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|500|ft|m}} || Same output as with -1 (above)
|-
| <code><nowiki>{{convert|500|ft|m|0}}</nowiki></code> || {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|500|ft|m|0}} || 
|-
| <code><nowiki>{{convert|500|ft|m|1}}</nowiki></code> || {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|500|ft|m|1}} ||
|-
| <code><nowiki>{{convert|500|ft|m|2}}</nowiki></code> || {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|500|ft|m|2}} || Exact value is 152.4 m 
|-
| <code><nowiki>{{convert|500|ft|cm}}</nowiki></code> || {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|500|ft|cm}} || Different output as with 0 (below)
|-
| <code><nowiki>{{convert|500|ft|cm|0}}</nowiki></code> || {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|500|ft|cm|0}} ||
|}<!--NOTE: rows require "nowiki", using &#123;{ disappears. -->

''Convert'' supports four types of rounding:

===Round to a given precision: ''use a precision number''===
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 multiple of {{frac|10}} to the power of 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.

===Round to a given number of significant figures: ''{{para|sigfig|}}''===
To specify the output number to be with ''n'' significant figures use {{para|sigfig|&lt;number>}}:
* <code><nowiki>{{convert|1200|ft|m|sigfig=4}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1200|ft|m|sigfig=4}}
* <code><nowiki>{{convert|1200|ft|m|sigfig=3}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1200|ft|m|sigfig=3}}
* <code><nowiki>{{convert|1200|ft|m|sigfig=2}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1200|ft|m|sigfig=2}}
* <code><nowiki>{{convert|1200|ft|m|sigfig=1}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1200|ft|m|sigfig=1}}

Default behaviour, for comparison:
* <code><nowiki>{{convert|1200|ft|m}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1200|ft|m}}
Setting {{para|sigfig}} to a value less than 1 is meaningless:
* <code><nowiki>{{convert|1200|ft|m|sigfig=0}}</nowiki></code> {{nay}} → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1200|ft|m|sigfig=0}}

===Round to a multiple of 5: ''15'', ''20'', ''25'', ...===
Using {{para|round|5}} rounds the outcome to a multiple of 5.
* <code><nowiki>{{convert|10|m|ft}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10|m|ft}}
* <code><nowiki>{{convert|10|m|ft|round=5}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10|m|ft|round=5}}

Similar: using {{para|round|25}} rounds the outcome to a multiple of 25.
* <code><nowiki>{{convert|10|m|ft}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10|m|ft}}
* <code><nowiki>{{convert|10|m|ft|round=25}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10|m|ft|round=25}}
Default behaviour, for comparison:
* <code><nowiki>{{convert|10|m|ft|sigfig=4}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10|m|ft|sigfig=4}}

In a range, one can round ''each value'' individually to the default. Use {{para|round|each}}:
* <code><nowiki>{{convert|10 x 200 x 3000|m|ft}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10 x 200 x 3000|m|ft}}
* <code><nowiki>{{convert|10 x 200 x 3000|m|ft|round=each}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10 x 200 x 3000|m|ft|round=each}}

===<span id="Round to a multiple of a given fraction"></span>Round to a multiple of a given fraction: ''{{frac|2|3|16}} inch''===
Specify the desired ''denominator'' using {{para|frac|&lt;some positive integer&gt;}}. ([[w:Fraction (mathematics)|Denominator]] is the below-the-slash number, for example the 3 in {{frac|1|3}}).
* <code><nowiki>{{convert|5.56|cm|in|frac=16}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|5.56|cm|in|frac=16}}
* <code><nowiki>{{convert|8|cm|in|frac=4}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|8|cm|in|frac=4}}

The fraction is reduced when possible:
* <code><nowiki>{{convert|8|cm|in|frac=100}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|8|cm|in|frac=100}}
Default behaviour uses decimal notation:
* <code><nowiki>{{convert|5.56|cm|in}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|5.56|cm|in}}

==={{anchor|Rounding temperatures}}Rounding temperatures: ''°C'', ''°F'' and ''K''===
In temperatures, the conversion will be rounded either to the 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.

The precision of the input number in example (1) is one digit, but the precision of its Kelvins expression is three, so the precision of the Fahrenheit conversion is ''made'' three (made 180...) . (1) and (2) seem to belie the fact that a {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|0.1|C-change|F-change|disp=x| is a |abbr=off}}, and make the 32 degrees difference shown in (1) begin to seem off somehow.
Result (1) seems off until you set the [[significant figures]] yourself with {{para|sigfig}} or you set the precision ''positionally'', relative to the decimal point (zero being ''at'' the decimal point).

The precision of the input number in example (2) is six, so the precision of the Fahrenheit output is, whereas before, Kelvins had determined it to be three. Examples (3) and (4) show how this can be hidden and generate questions, but it occurs there because the Kelvins conversion generated two fractional parts. (Before it was the input number that generated the fractional part.)  In example (3) the three input digits converted into five significant output digits because of the two digits after the decimal point, generated by the Kelvins conversion. This happened again in (5), but in (6) decimal fractions were neither given as input nor induced by the Kelvins conversion.

===Rounding input===
There is limited support for rounding the displayed ''input'' number.  The rounding takes place ''after'' conversion, so the output is based on the full-precision input.  This is useful when the input is produced by <code><nowiki>{{#expr:}}</nowiki></code> or otherwise available to a higher precision than is usefully displayed, and it's desirable to avoid double-rounding.

To round the input to a specified number of digits after the decimal point, use one of the parameters:
* {{para|adj|ri0}}
* {{para|adj|ri1}}
* {{para|adj|ri2}}
* {{para|adj|ri3}}
Note that there is no {{para|adj|ri-1}}{{nay}} or similar for rounding above the decimal place.  Neither is there support for significant figures, multiples of 5, or any other output-rounding feature.

The default precision is computed based on the input, so an explicit output precision must usually be supplied:
* {{tl|convert|4.14159|mi|km|adj{{=}}ri0}} → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|4.14159|mi|km|adj=ri0}} {{nay}} (precisions are mismatched)
* {{tl|convert|4.14159|mi|km|0|adj{{=}}ri0}} → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|4.14159|mi|km|0|adj=ri0}} {{aye}}

In this case, if the input were rounded before conversion, a different result would be obtained:
* {{tl|convert|<nowiki>{{#expr:4.14159 round 0}}</nowiki>|mi|km|0}} → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|{{#expr:4.14159 round 0}}|mi|km|0}} {{nay}} (double rounding)

==Into multiple units: ''{{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10|C|F K}}''==
Separate the multiple output units by a space:
* <code><nowiki>{{convert|10|C|F K}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10|C|F K}}
* <code><nowiki>{{convert|5|km|mi nmi}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|5|km|mi nmi}}
If the output unit names contain spaces, use <code>+</code> as the separator.

See also:
* For multiple-unit options like ''1 ft 5 in'', see [[#In input]] and [[#In output]].

==Ranges of values==
A ''range'' converts ''two'' values and separates them by your choice of words and punctuation.

===A range: ''6 to 17 kg (13 to 37 lb)''===
Range indicators are entered as the second parameter (between the values). For range separators, see [[w:Template:Convert/doc/range separator list]].

===Multiple dimensions: ''{{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|6|x|12|m|ft|abbr=on}}''===
Use <code>by</code>:
* <code><nowiki>{{convert|6|by|12|ft|m}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|6|by|12|ft|m}}

Use <code>×</code>, multiplication sign, or <code>x</code>, letter:
* <code><nowiki>{{convert|6|x|12|m|ft}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|6|x|12|m|ft}}

In science, the formal way is to set <code>&#x7c;x&#x7c;</code> and {{para|abbr|on}} (keeping dimensions right, like in ''area = x km<sup>2</sup>''):
* <code><nowiki>{{convert|6|x|12|m|ft|abbr=on}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|6|x|12|m|ft|abbr=on}}

===About ''feet, inch'' in ranges and multiples===
While it is possible to enter feet, inch in a simple conversion, this is not possible for ranges:
* <code><nowiki>{{convert|1|ft|3|in|x|3|ft|5|in|mm}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1|ft|3|in|x|3|ft|5|in|mm}} {{nay}}
Default behaviour, for comparison:
* <code><nowiki>{{convert|1|ft|3|in|mm}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1|ft|3|in|mm}}

==Words==
===Spelling of unit name: 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> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|1|m|ft}}—''default''
:<code><nowiki>{{convert|1|m|ft|sp=us}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|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> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|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> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|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> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10|mi|m|spell=In}}
* <code><nowiki>{{convert|10|mi|m|spell=On}}</nowiki></code> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|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> → {{<includeonly>{{PAGENAME}}</includeonly><noinclude>convert</noinclude>|10|mi|m|spell=on|abbr=off|sp=us}}

== See also ==
* [[w:Help:Convert]] for more detailed technical information
<includeonly>
<!-- CATEGORIES AND INTERWIKIS HERE, THANKS -->
[[Category:Subtemplates of Template Convert| ]]
</includeonly>