Template:Convert/doc

Template {{Convert}} calculates from one measurement unit to another one, and then presents the results formatted.

Usage

For example:

{{convert|2|km|mi}} → 2 kilometres (1.2 mi) (km entered, so converted into mile)

{{convert|7.1|mi|km}} → 7.1 miles (11.4 km) (mi entered, so converted into km)

{{convert|7.0|mi|km}} → 7.0 miles (11.3 km) (mi entered, so converted into km)

Numbers can be rounded, units can be abbreviated into symbols:

{{convert|2|km|mi|2|abbr=on}} → 2 km (1.24 mi)

{{convert|7|mi|km|2|abbr=on}} → 7 mi (11.27 km)

Value ranges can be entered using |to|... or |-|...:

{{convert|2|to|5|km|mi}} → 2 to 5 kilometres (1.2 to 3.1 mi)

{{convert|2|-|5|km|mi}} → 2–5 kilometres (1.2–3.1 mi)

Combined effect example:

{{convert|2|-|5|km|mi|2|abbr=on}} → 2–5 km (1.24–3.11 mi)

{{convert|2|and|5|km|mi|sigfig=3|abbr=off}} → 2 and 5 kilometres (1.24 and 3.11 miles)

Units to convert

Enter units to convert:

• {{convert|1|lb|kg}} → 1 pound (0.45 kg)

SI units generally accept prefixes, like "m" for milli (10⁻³), and "M" for mega (10⁶). 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):

• {{convert|1|lb|kg}} → 1 pound (0.45 kg)

Using |abbr = in is the reverse behaviour to the default:

• {{convert|1|lb|kg|abbr=in}} → 1 lb (0.45 kilograms)

To abbreviate both or neither:

• {{convert|1|lb|kg|abbr=on}} → 1 lb (0.45 kg)
• {{convert|1|lb|kg|abbr=off}} → 1 pound (0.45 kilograms)

When using scientific notation, the default is for the second (converted) quantity to be displayed using scientific notation:

• {{convert|100|e6mi|e6km}} → 100 million miles (160×10^⁶ km)

To display thousands, millions, etc., while abbreviating both input and output units use |abbr = unit:

• {{convert|100|e6mi|e6km|abbr=unit}} → 100 million mi (160 million km)

Adjective: a 10-mile distance

Use |adj = on to produce the adjectival (hyphenated) form:

• A {{convert|10|mi|km|adj=on}} distance → A 10-mile (16 km) distance.

Default behaviour, for comparison:

• {{convert|10|mi|km}} to go → 10 miles (16 km) to go.

Even with |abbr = on, no hyphen is produced with unit symbols.

Rounding: 100 ft is 30 m or 30.5 m or 30.48 m?

See w:Help:Convert#Rounding for a more mathematical description of the rounding options

By definition, 100 ft equals 30.48 m. In practical use, it is common to round the calculated metric number. With that, there are several possibilities.

Default rounding

By {{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 below).

Examples of rounding

Input	Displays as	Note
{{convert|123|ft|m|-1}}	123 feet (40 m)
{{convert|123|ft|m}}	123 feet (37 m)	Same output as with 0 (below)
{{convert|123|ft|m|0}}	123 feet (37 m)
{{convert|123|ft|m|1}}	123 feet (37.5 m)
{{convert|123|ft|m|2}}	123 feet (37.49 m)	Exact value is 37.4904 m
{{convert|500|ft|m|-1}}	500 feet (150 m)
{{convert|500|ft|m}}	500 feet (150 m)	Same output as with -1 (above)
{{convert|500|ft|m|0}}	500 feet (152 m)
{{convert|500|ft|m|1}}	500 feet (152.4 m)
{{convert|500|ft|m|2}}	500 feet (152.40 m)	Exact value is 152.4 m
{{convert|500|ft|cm}}	500 feet (15,000 cm)	Different output as with 0 (below)
{{convert|500|ft|cm|0}}	500 feet (15,240 cm)

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 Template:Frac 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: |sigfig =

To specify the output number to be with n significant figures use |sigfig = <number>:

• {{convert|1200|ft|m|sigfig=4}} → 1,200 feet (365.8 m)
• {{convert|1200|ft|m|sigfig=3}} → 1,200 feet (366 m)
• {{convert|1200|ft|m|sigfig=2}} → 1,200 feet (370 m)
• {{convert|1200|ft|m|sigfig=1}} → 1,200 feet (400 m)

Default behaviour, for comparison:

• {{convert|1200|ft|m}} → 1,200 feet (370 m)

Setting |sigfig = to a value less than 1 is meaningless:

• {{convert|1200|ft|m|sigfig=0}} → 1,200 feet (370 m)

Round to a multiple of 5: 15, 20, 25, ...

Using |round = 5 rounds the outcome to a multiple of 5.

• {{convert|10|m|ft}} → 10 metres (33 ft)
• {{convert|10|m|ft|round=5}} → 10 metres (35 ft)

Similar: using |round = 25 rounds the outcome to a multiple of 25.

• {{convert|10|m|ft}} → 10 metres (33 ft)
• {{convert|10|m|ft|round=25}} → 10 metres (25 ft)

Default behaviour, for comparison:

• {{convert|10|m|ft|sigfig=4}} → 10 metres (32.81 ft)

In a range, one can round each value individually to the default. Use |round = each:

• {{convert|10 x 200 x 3000|m|ft}} → 10 by 200 by 3,000 metres (33 ft × 656 ft × 9,843 ft)
• {{convert|10 x 200 x 3000|m|ft|round=each}} → 10 by 200 by 3,000 metres (33 ft × 660 ft × 9,800 ft)

Round to a multiple of a given fraction: Template:Frac inch

Specify the desired denominator using |frac = <some positive integer>. (Denominator is the below-the-slash number, for example the 3 in Template:Frac).

• {{convert|5.56|cm|in|frac=16}} → 5.56 centimetres (2 ³⁄₁₆ in)
• {{convert|8|cm|in|frac=4}} → 8 centimetres (3 ¹⁄₄ in)

The fraction is reduced when possible:

• {{convert|8|cm|in|frac=100}} → 8 centimetres (3 ³⁄₂₀ in)

Default behaviour uses decimal notation:

• {{convert|5.56|cm|in}} → 5.56 centimetres (2.19 in)

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 0.1 degrees Celsius change is a 0.18 degrees Fahrenheit change, 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 |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 Template:Tlc 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:

• |adj = ri0
• |adj = ri1
• |adj = ri2
• |adj = ri3

Note that there is no |adj = ri-1 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:

• {{Convert|4.14159|mi|km|adj= ri0 }} → 4 miles (6.66524 km) (precisions are mismatched)
• {{Convert|4.14159|mi|km|0|adj= ri0 }} → 4 miles (7 km) Template:Aye

In this case, if the input were rounded before conversion, a different result would be obtained:

• {{Convert|{{#expr:4.14159 round 0}}|mi|km|0}} → 4 miles (6 km) (double rounding)

Into multiple units: 10 °C (50 °F; 283 K)

Separate the multiple output units by a space:

• {{convert|10|C|F K}} → 10 °C (50 °F; 283 K)
• {{convert|5|km|mi nmi}} → 5 kilometres (3.1 mi; 2.7 nmi)

If the output unit names contain spaces, use + 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: 6 m × 12 m (20 ft × 39 ft)

Use by:

• {{convert|6|by|12|ft|m}} → 6 by 12 feet (1.8 by 3.7 m)

Use ×, multiplication sign, or x, letter:

• {{convert|6|x|12|m|ft}} → 6 by 12 metres (20 ft × 39 ft)

In science, the formal way is to set |x| and |abbr = on (keeping dimensions right, like in area = x km²):

• {{convert|6|x|12|m|ft|abbr=on}} → 6 m × 12 m (20 ft × 39 ft)

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:

• {{convert|1|ft|3|in|x|3|ft|5|in|mm}} → 1 foot 3 inches ()

Default behaviour, for comparison:

• {{convert|1|ft|3|in|mm}} → 1 foot 3 inches (380 mm)

Words

Spelling of unit name: UK metre or US meter?

Default spelling of units is en-UK. To show en-US spelling, use |sp = us:

{{convert|1|m|ft}} → 1 metre (3.3 ft)—default

{{convert|1|m|ft|sp=us}} → 1 meter (3.3 ft)

Spell out numbers: ten miles

To write a number in words, use |spell = in:

• {{convert|10|mi|m|spell=in}} → ten miles (16,000 m)

To spell out both in and out values, use |spell = on:

• {{convert|10|mi|m|spell=on}} → ten miles (sixteen thousand metres)

To make first letter a capital, use |spell = In, |spell = On

• {{convert|10|mi|m|spell=In}} → Ten miles (16,000 m)
• {{convert|10|mi|m|spell=On}} → Ten miles (sixteen thousand metres)

Remember that the spelling of the units (ft, m) is independently set by |abbr = . To the extreme:

• {{convert|10|mi|m|spell=on|abbr=off|sp=us}} → ten miles (sixteen thousand meters)

See also

• w:Help:Convert for more detailed technical information