Template:Convert/doc

Template convert calculates measurements from one unit (you entered) to another one, and then presents the results. For example:
 * &rarr; 1 km
 * &rarr; 7 mi

Basic examples

 * 3 kg &rarr; 3 kg
 * 3 kg &rarr; 3 kg
 * 10 kg &rarr; 10 kg
 * 6 ft &rarr; 6 ft
 * 2 m &rarr; 2 m
 * 10 mi &rarr; 10 mi
 * 100 mpgus &rarr; 100 mpgus
 * 120 km/h &rarr; 120 km/h
 * 18 °C &rarr; 18 °C
 * 15 C &rarr; 15 C
 * 9 e6USgal &rarr; 9 e6USgal The "e6" scales the input to millions; the "abbr=off" yields the "mega" in the output. Scaling is only available for Single value conversions. Not all units are supported.
 * 1250 sqft &rarr; 1250 sqft Note 'lk=in' links only the input unit. This example is for illustration only, common units of measurement should not be linked. See: wp:overlink
 * 20.5 m3 &rarr; 20.5 m3 Note 'lk=out' links only the output unit, cu yd
 * 641 acre &rarr; 641 acre Note 'lk=on' links all units. Per guidelines, common units should not be linked. See: wp:overlink
 * 641 acre &rarr; 641 acre Although 640 acres equals 1 square mile; 641 acres rounded to two decimal places equals 1.00 sq mi

Unit abbreviation: 1 pound or 1 lb?
on will produce the unit's symbol:
 * &rarr; 1 lb
 * &rarr; 1 lb

Adjective: a 10-mile distance
Use on to produce the adjective form. The difference:
 * &rarr; 10 mi to go. -- Regular
 * &rarr; A 10 mi distance. -- Adjective

Rounding: 100 ft is 30 m or 30.5 m or 30.48 m?
In detail, it is 100 ft. In practical use, it is common to round the calculated metric number. With that, there are several possibilities.

Default rounding

 * By 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 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.

Convert supports four types of rounding:

Round to a given precision: use 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 $1/undefined$ 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: use sigfig
Specify the desired number of significant figures using &lt;number> as noted above.

Round to a multiple of a given number: use near
Specify the desired multiple using
 * e.g.  &rarr; 11 m

Round to a multiple of a given fraction: use frac
Specify the desired denominator using &lt;some positive integer. (Denominator is the below-slash number, for example the 3 in $1/3$).
 * e.g.  &rarr; 1 in

Into multiple units: 10 C
Separate the multiple output units by a space:
 * &rarr; 10 C
 * &rarr; 5 km

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:
 * ,,   (ndash or hyphen) ,  ,  ,  ,  :
 * &rarr; 6 to 17 kg
 * &rarr; -10 to -20 C
 * &rarr; 6 to(-)
 * &rarr; 6 and 17 kg
 * &rarr; 60 ±
 * &rarr; 60 +/-

Multiple dimensions: 6 by 12 feet (1.8 by 3.7 m)

 * &rarr; 6 by
 * &rarr; 6 x

About feet, inch multiples
It is not possible to produce multiple [feet, inch] measurements.

Spell out numbers: ten miles
To write a number in words, use in:
 * &rarr; 10 mi

To spell out both in and out values, use on:
 * &rarr; 10 mi

To make first letter a capital, use In, On
 * &rarr; 10 mi
 * &rarr; 10 mi

Remember that the spelling of the units (ft, m) is independently set by abbr. To the extreme:
 * &rarr; 10 mi

Spelling of units: UK metre or US meter?
Default spelling of units is en-UK. To show en-US spelling, use us:
 * &rarr; 1 m -- default
 * &rarr; 1 m

Extra words: 4 planted acres

 * Incomplete secion:
 * &rarr; 4 acre

Extra adjective words: A 10 ft corridor

 * &rarr; 10 ft

Fractions: 1/2 in
The number to convert can be expressed in fractions:
 * (the default), ,   (or: s, slash) ,  ,  ,  ,  :
 * &rarr; 10 m --  brackets are the default
 * &rarr; 10 m
 * &rarr; 10 m
 * &rarr; 10 m
 * &rarr; 10 m
 * &rarr; 10 m

Setting br will force a new line


 * &rarr; 10 m

Setting x extra parameter (separator) to add:


 * &rarr; 10 m -- (Take care of the spaces, use &amp;nbsp;)

Converted measurement only: 10 km
Setting out returns the calculated measurement only:
 * &rarr; 10 km


 * &rarr; 10 km

Converted number only: 10 km
Setting number returns the converted number only:
 * &rarr; 10 km

Unit only: 10 km
Setting unit returns the (input) unit only:
 * &rarr; 10 km

Flipping the two measurements: 1 mi
Set flip will flip (swap) the two measurements:
 * &rarr; 1 mi

Table options
For the 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 table splits the result over two columns:
 * &rarr; 10 m

tablecen does the same, and also centers the text:
 * &rarr; 20 m

The units are added as a column header:
 * {| class=wikitable

! ! m ! ft
 * table
 * 10 m
 * tablecen
 * 20 m
 * &lt;other> (default)
 * 30 m
 * }
 * &lt;other> (default)
 * 30 m
 * }

Sorting

 * Use both table on to make a table column sortable. Only the first column will sort correct.


 * 10 m &rarr;  (don't let this frighten you) 

10 m


 * {| class="wikitable sortable"

! m ! ft
 * 10 m
 * 20 m
 * 30 m
 * }
 * 30 m
 * }
 * }

Parameter list
Examples of number grouping:
 * → 1234 m
 * → 1234 m
 * → 12345 m
 * → 1234 m
 * → 1234 m
 * → 123,456,789 m

Examples of spelling input values:
 * → 10 mi
 * → 10 mi
 * → 1/3 mi

Free text in a range: 12 m but not greater than 14 m
The range-indicator options like – 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:

convert does not have this option. One can use variant templates:
 * &rarr;

For these situations, see the documentation of:
 * convert/2, convert/flip2, convert/text2
 * convert/3, convert/flip3, convert/text3
 * convert/4, convert/flip4

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" } }}