Template:To USD round/doc: Difference between revisions

Content deleted Content added

Inline

Latest revision as of 11:03, 7 August 2024

This is a documentation subpage for Template:To USD round.
It may contain usage information, categories and other content that is not part of the original template page.

Shortcuts

{{USDr}}
{{To USD r}}
{{ToUSDr}}

This template converts a value given in the national currency of a given country to a round US dollar figure. The intended use is for large round figures, when you don't want €3.2 million turning into US$3,784,640, you just want a round figure like US$3,600,000. It tries to mimic the same number of significant figures as are present in the original amount. The template uses values published by the IMF.^[1]

Usage

{{To USD round|AMOUNT|COUNTRY|YEAR|sf=SIGFIG}}

Parameters

There are three unnamed parameters, and one named parameter:

|1= is the amount in local currency to be converted to US dollars. Required.
|2= is the name or 3-letter ISO code of the country whose currency is being converted. Required.
|3= is the year to use for the US dollar exchange rate against the currency of the other country. Possible values: see § Data subtemplates below. Optional; default = 2019.
|sf= is number of significant figures. The converted value is displayed to that precision. Optional; the default is the number of significant figures in the amount given in param 1.

Examples

{{To USD round|5200|Mexico}} displays 270. That is, 5200 Mexican pesos would exchange to roughly 270 US dollars (to two significant digits) at the 2019 exchange rate.
{{To USD round|5200|MEX}} → 270
{{To USD round|1250|FRA}} → 1,400
{{To USD round|5200|MEX}} → 270
{{Formatnum:{{To USD round|185000|RUS}}}} ⟶ 28,600.
{{To USD round|5200|MEX|year=1998}} displays Undefined year "1998" since data for 1998 has not been defined. It will add the page to Category:Pages using an undefined year in Template:To USD round/doc
{{To USD round|5200|MEX|year=2009}} displays 380 since data for 2009 has not been entered for Mexico. It will add the page to Category:Pages using an undefined country code in Template:To USD round/doc

{{To USD round|586000|BRA|year=2011}} → 350,000
{{To USD round|586000|BRA|year=2019}} → 149,000
{{To USD round|586000|BRA|year=}} → 149,000
{{To USD round|586000|BRA}} → 149,000
{{To USD round|620000000|BRA|year=2015}} → 190,000,000
{{To USD round|620000000|BRA|year=2015|sf=4}} → 186,400,000
{{To USD round|640|MEX|sf=5}} → 33.220 # Some combos make no sense; USD doesn't have tenths of a cent.

Data subtemplates

References

^ "Official exchange rate (LCU per US$, period average)". Retrieved 14 April 2013.

TemplateData

This is the TemplateData for this template used by TemplateWizard, VisualEditor and other tools. See a monthly parameter usage report for Template:To USD round in articles based on its TemplateData.

TemplateData for To USD round

Template to convert other currencies into United States dollars, by year, based on information from the International Monetary Fund, and with selected number of significant figures

Template parameters
Parameter		Description	Type	Status
amount	`1`	value in foreign currency to convert to USD Example 175000	Number	required
country code	`2` `country`	ISO 3166-1 alpha-3 country code Example MEX	Line	required
year	`year`	Year to convert currency. Values: 1960–2022. Default 2019 Example 2002	Number	optional
significant figures	`sf`	If numeric, rounds to that many significant figures. If omitted, rounds to number of significant figures in 'amount'. Example 3	Number	optional

[1] "Official exchange rate (LCU per US$, period average)". Retrieved 14 April 2013.

[1]

@@ Line 1: / Line 1: @@
 {{documentation subpage}}
+{{tsh|USDr|To USD r|ToUSDr}}
-This template converts a value given in the national currency of a given country to a round [[United States dollar|US dollar]] figure. The intended use is for large round figures, when you don't want 3.2 million euros turning into ${{Formatnum:{{To USD|3200000|FRA}}}} dollars, you just want a round figure like ${{To USD round|3200000|FRA}}. It tries to mimic the same number of significant figures, as are present in the original amount.  The template uses values published by the [[International Monetary Fund|IMF]].<ref>{{cite web|url=http://data.worldbank.org/indicator/PA.NUS.FCRF|title=Official exchange rate (LCU per US$, period average)|accessdate = 14 April 2013}}</ref>
+This template converts a value given in the national currency of a given country to a round [[United States dollar|US dollar]] figure. The intended use is for large round figures, when you don't want {{euro|3.2 million}} turning into {{US$|{{To USD|3200000|FRA}}}}, you just want a round figure like {{US$|{{To USD round|3200000|FRA}}}}. It tries to mimic the same number of significant figures as are present in the original amount.  The template uses values published by the [[International Monetary Fund|IMF]].<ref>{{cite web|url=http://data.worldbank.org/indicator/PA.NUS.FCRF|title=Official exchange rate (LCU per US$, period average)|accessdate = 14 April 2013}}</ref>
-=== Syntax ===
+=== Usage ===
 <code><nowiki>{{</nowiki>To USD round|''AMOUNT''|''COUNTRY''|''YEAR''|sf=''SIGFIG''<nowiki>}}</nowiki></code>
+=== Parameters ===
-* ''AMOUNT'' is the value in the local currency to be converted.
+There are three [[WP:PARAMETER|unnamed parameters]], and one named parameter:
-* ''COUNTRY'' is the country name or [[ISO 3166-1 alpha-3 | 3-letter ISO code]] for the country whose currency is being converted.
-* ''YEAR'' (optional) is the year to use for the US dollar exchange rate value against the currency of the other country.  The default is currently 2021. Possible values: 2002, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021.
+* {{para|1}} is the amount in local currency to be converted to US dollars. Required.
-* ''SIGFIG'' (optional) is a numerical value. If present, the converted value is displayed to the that number of [[significant figures]]. The default is the number of significant figures in ''AMOUNT''.
+* {{para|2}}  is the name or [[ISO 3166-1 alpha-3|3-letter ISO code]] of the country whose currency is being converted. Required.
+* {{para|3}} is the year to use for the US dollar exchange rate against the currency of the other country. Possible values: see {{slink||Data subtemplates}} below. Optional; default = {{pval|2019}}.
+* {{para|sf}} is number of [[significant figures]]. The converted value is displayed to that precision. Optional; the default is the number of significant figures in the amount given in param 1.
 ===Examples===
-*<code><nowiki>{{To USD round|5200|Mexico}}</nowiki></code> displays {{To USD round|5200|Mexico}}.  That is, 5200 [[Mexican peso]]s would exchange to ''roughly'' {{To USD round|5200|MEX}} [[United States dollar | US dollars]] (to two signficant digits) at the 2021 exchange rate.
+*<code><nowiki>{{To USD round|5200|Mexico}}</nowiki></code> displays {{To USD round|5200|Mexico}}.  That is, 5200 [[Mexican peso]]s would exchange to ''roughly'' {{To USD round|5200|MEX}} [[United States dollar|US dollars]] (to two significant digits) at the 2019 exchange rate.
-* <code><nowiki>{{To USD round|5200|MEX}}</nowiki></code> also displays {{To USD round|5200|MEX}}.
+* {{tlg|To USD round|5200|MEX|code=1|_show_result=1}}
-* <code><nowiki>{{To USD round|1250|FRA}}</nowiki></code> displays {{To USD round|1250|FRA}}.
+* {{tlg|To USD round|1250|FRA|code=1|_show_result=1}}
-* <code><nowiki>{{To USD round|5200|MEX|sf=3}}</nowiki></code> displays {{To USD round|5200|MEX|sf=3}}.
+* {{tlg|To USD round|5200|MEX|sf=3|code=1|_show_result=1}}
-* <code><nowiki>{{Formatnum:{{To USD round|18000|RUS}}}}</nowiki></code> displays {{Formatnum:{{To USD round|180000|RUS}}}}.
+* <code><nowiki>{{Formatnum:{{To USD round|185000|RUS}}}}</nowiki></code> ⟶ {{Formatnum:{{To USD round|1850000|RUS}}}}.
 * <code><nowiki>{{To USD round|5200|MEX|year=1998}}</nowiki></code> displays {{To USD round|5200|MEX|year=1998}} since data for 1998 has not been defined. It will add the page to [[:Category:Pages using an undefined year in {{ARTICLEPAGENAME}}]]
 * <code><nowiki>{{To USD round|5200|MEX|year=2009}}</nowiki></code> displays {{To USD round|5200|MEX|year=2009}} since data for 2009 has not been entered for Mexico. It will add the page to [[:Category:Pages using an undefined country code in {{ARTICLEPAGENAME}}]]
 ----
-* <code><nowiki>{{To USD round|586000|BRA|year=2011}}</nowiki></code> = {{To USD round|586000|BRA|year=2011}}
+* {{tlg|To USD round|586000|BRA|year{{=}}2011|code=1|_show_result=1}}
-* <code><nowiki>{{To USD round|586000|BRA|year=2019}}</nowiki></code> = {{To USD round|586000|BRA|year=2019}}
+* {{tlg|To USD round|586000|BRA|year{{=}}2019|code=1|_show_result=1}}
-* <code><nowiki>{{To USD round|586000|BRA|year=2021}}</nowiki></code> = {{To USD round|586000|BRA|year=2021}}
+* {{tlg|To USD round|586000|BRA|year{{=}}|code=1|_show_result=1}}
-* <code><nowiki>{{To USD round|586000|BRA|year=}}</nowiki></code> = {{To USD round|586000|BRA|year=}} (last year available)
+* {{tlg|To USD round|586000|BRA|code=1|_show_result=1}}
-* <code><nowiki>{{To USD round|586000|BRA}}</nowiki></code> = {{To USD round|586000|BRA}} (last year available)
+* {{tlg|To USD round|620000000|BRA|year{{=}}2015|code=1|_show_result=1}}
-* <code><nowiki>{{To USD round|620000000|BRA|year=2015}}</nowiki></code> = {{To USD round|620000000|BRA|year=2015}}
+* {{tlg|To USD round|620000000|BRA|year{{=}}2015|sf{{=}}4|code=1|_show_result=1}}
+* {{tlg|To USD round|640|MEX|sf{{=}}5|code=1|_show_result=1}} # Some combos make no sense; USD doesn't have tenths of a cent.
-* <code><nowiki>{{To USD round|620000000|BRA|year=2015|sf=4}}</nowiki></code> = {{To USD round|620000000|BRA|year=2015|sf=4}}
-* <code><nowiki>{{To USD round|640|MEX|sf=5}}</nowiki></code> displays {{To USD round|640|MEX|sf=5}}. # Some combos make no sense; USD doesn't have tenths of a cent.
 ===See also===
@@ Line 35: / Line 38: @@
 * [[Template:Round]]
 * [[Template:significant figures]]
-* [[Template:International dollars]]:  Converts a value in a given country in a given year to [[Geary–Khamis dollar | international dollars]].
+* [[Template:International dollars]]:  Converts a value in a given country in a given year to [[Geary–Khamis dollar|international dollars]].
+* [[Template:Per capita]]
 * {{tlc|[[Help:Parser functions|formatnum:]]}}
 ===Data subtemplates===
+{{excerpt|Template:To USD/doc|Data subtemplates|hat=no}}
-{{hlist| [[Template:To USD/data/2002|2002]] | [[Template:To USD/data/2011|2011]] | [[Template:To USD/data/2012|2012]] | [[Template:To USD/data/2013|2013]] | [[Template:To USD/data/2014|2014]] | [[Template:To USD/data/2015|2015]] | [[Template:To USD/data/2016|2016]] | [[Template:To USD/data/2017|2017]] | [[Template:To USD/data/2018|2018]] | [[Template:To USD/data/2019|2019]] }} | [[Template:To USD/data/2020|2020]] }} | [[Template:To USD/data/2020|2020]] }}
 ===References===
@@ Line 48: / Line 52: @@
 {{DEFAULTSORT:{{BASEPAGENAME}}}}
 [[Category:Currency conversion templates]]
 }}</includeonly>
 ==TemplateData==
 {{TemplateDataHeader}}
@@ Line 72: / Line 77: @@
 		},
 		"year": {
-			"description": "Year to convert currency. Values: 2002, 2011–2021.",
+			"description": "Year to convert currency. Values: 1960–2022.",
 			"example": "2002",
 			"type": "number",
+			"default": "2019",
 			"required": false
 		},