{ "category": "User defined functions that are installed with add-ins", "display_name": "EUROCONVERT", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.EUROCONVERT", "implementation_state": { "answer_bank": { "excel_builds": [ "20527" ], "larger_numeric": 0, "last_bit": 0, "matched": 0, "other_mismatch": 0, "refused": 13, "rows": 13, "unread": 0, "worst_ulp": 0 }, "detail": "No catalogue row at this commit. In Excel it comes with the Euro Currency Tools add-in; build 20527 on Windows gives #NAME? without it.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": false, "state": "refuses", "state_label": "Refuses or not implemented", "summary": "Not yet implemented", "workbook_corpus": { "cells": 128, "matched": 128 } }, "implementations": [], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.EUROCONVERT.json", "name": "EUROCONVERT", "notes": [], "schema": "efh.function-reference/v1", "section_order": [ "what-it-does", "try-it", "quirks", "how-to-implement", "version-differences", "alternatives" ], "sections": { "alternatives": "\n### Relationships\n\n\n- **`CONVERT`** — the function readers reach for and the one that does *not* do currencies.\n `CONVERT` handles physical units (mass, distance, time, temperature). The two are neighbours\n in intent and disjoint in domain.\n- **`CALL` and `REGISTER.ID`** — the other entries in the same \"installed with add-ins\"\n category, though they are a registration seam rather than a computation. What `EUROCONVERT`\n shares with them is the `#NAME?`-when-absent behaviour.\n- **`STOCKHISTORY`** and the Currencies linked data type — the modern, *market-rate* path for\n currency conversion. They are not replacements for `EUROCONVERT` and must not be treated as\n such: `EUROCONVERT` implements a legal conversion at a frozen rate, not a market quote. Using\n a live rate to convert a legacy amount is a different and usually wrong operation.\n- **`ROUND`** — worth naming because the temptation is to reimplement `EUROCONVERT` as a\n multiplication plus a `ROUND`. That reproduces neither the two-column precision table nor the\n triangulation intermediate.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n- **Triangulation is not associative with plain rounding.** Convert FRF → DEM directly by a\n composed rate and you get a different answer from the mandated route through a\n significant-digit-rounded euro intermediate. The intermediate rounding is the specification,\n not an implementation detail.\n- **Significant digits, not decimal places.** `triangulation_precision` is documented as\n significant digits with a floor of 3. Implementing it as decimal places will agree on some\n magnitudes and diverge on others, which is the worst kind of bug.\n- **Calculation precision and display precision are two columns.** See `PTE` and `GRD` above.\n- **The array-formula restriction is a real behavioural axis.** A modern reimplementation will\n naturally lift over arrays and will thereby accept formulas Excel refuses. Whether that\n matters depends on whether the goal is compatibility or utility — the Handbook's four-flavour\n framing is exactly the place to make that choice explicit (see\n [implementation options](../model/07-implementation-options.md)).\n\n\n", "quirks": "\n### Result and edge cases\n\n\nA number, with two documented behaviours that are easy to miss:\n\n- **\"Excel truncates any trailing zeros in the return value.\"** So the *value* is rounded to\n the currency's precision but the *representation* does not preserve trailing zeros — a\n conversion to a 2-decimal currency landing on a round amount does not come back as `12.50`.\n- **\"This function does not apply a number format.\"** The result is a bare number; currency\n formatting is the workbook's job. That separation is consistent with the Handbook's model, in\n which function pages describe values and not cell presentation (see\n [the call pipeline](../model/03-call-pipeline.md)).\n\nAnd one structural restriction with no analogue elsewhere in this batch: **\"This function\ncannot be used in array formulas.\"** Almost every scalar function in Excel lifts over arrays;\nthis one is documented as refusing to. That makes `EUROCONVERT` an explicit exception to the\narray-lifting baseline described in\n[coercion and lifting](../model/02-coercion-and-lifting.md), and the manner of the refusal —\nerror, first-element-only, or entry-time rejection — is not stated.\n\n\n\n### Errors\n\n\nAs documented by Microsoft:\n\n- **`#NAME?`** — the Euro Currency Tools add-in is not installed and loaded. This is the\n characteristic failure of the whole add-in-owned category: the workbook is fine, the formula\n is fine, and the name simply does not exist in this session.\n- **`#VALUE!`** — \"Invalid parameters return #VALUE.\" Microsoft gives no finer breakdown, so an\n unrecognized ISO code, a non-numeric `number`, and a `triangulation_precision` below 3 are\n all documented as landing on the same code.\n\n\n", "sources": "- Microsoft, \"EUROCONVERT function\" —\n \n (syntax, all five arguments and their stated requiredness, the fourteen supported ISO codes,\n the calculation/display precision table, the identity rule, the trailing-zero and\n no-number-format remarks, the array-formula restriction, and the `#NAME?` and `#VALUE!`\n conditions).\n- Council Regulation (EC) No 2866/98 of 31 December 1998 on the conversion rates between the\n euro and the currencies of the Member States adopting the euro, together with the later\n regulations covering the currencies that joined afterwards — the authoritative source of the\n fixed rates this function applies. Named here as where an implementation should obtain the\n table; the Handbook does not transcribe it on this page.\n- Handbook `data/presence/FUNC.EUROCONVERT.json` — the implementing module\n `earlier-implementation/misc_conversion_family.rs` and its surface-dispatch entry.\n- Handbook `content/model/02-coercion-and-lifting.md`, `03-call-pipeline.md` and\n `07-implementation-options.md` — the array-lifting baseline this function is documented to\n refuse, the value-versus-presentation split, and the flavour framing referenced above.\n\n", "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.", "what-it-does": "\n`EUROCONVERT` is a historical artifact with unusually precise semantics. It converts between\nthe euro and the currencies it replaced, at the **irrevocably fixed** conversion rates set when\neach currency joined — not at market rates, which is why the function can be deterministic and\noffline at all. It exists to implement the conversion *rules* that came with those rates,\nincluding a mandated rounding regime and a mandated way of routing one legacy currency to\nanother.\n\n\nThree conversion directions, with different arithmetic:\n\n1. **National → euro.** Divide by that currency's fixed rate.\n2. **Euro → national.** Multiply by that currency's fixed rate.\n3. **National → national (triangulation).** Convert the source to euro, round that intermediate\n euro amount to `triangulation_precision` significant digits, then convert the rounded\n intermediate to the target currency. The mandated intermediate step is what \"triangulation\"\n names, and it is the reason this function cannot be replaced by a single multiplication: a\n direct source-to-target rate would give a different, non-conforming answer.\n\nAnd one identity case Microsoft states explicitly: **if the source ISO code is the same as the\ntarget ISO code, the original number is returned.**\n\nThe rate table covers fourteen ISO codes:\n\n`BEF` `LUF` `DEM` `ESP` `FRF` `IEP` `ITL` `NLG` `ATS` `PTE` `FIM` `GRD` `SIT` `EUR`\n\nThe rates themselves are not Excel's invention — they are the fixed conversion rates adopted in\nEU law when each currency's euro entry was settled, and they never change. The Handbook does\nnot transcribe them on this page; the authoritative source is named under Sources, and any\nimplementation should take them from there rather than from a spreadsheet.\n\n### The rounding regime\n\n`full_precision` selects between two very different results. When it is FALSE (Microsoft\ndocuments FALSE as the default), the result is rounded according to **currency-specific**\nrules; when TRUE, all significant digits from the calculation are kept.\n\nMicrosoft's documented precision table:\n\n| ISO codes | Calculation precision | Display precision |\n|---|---|---|\n| `BEF`, `LUF`, `ESP`, `ITL` | 0 | 0 |\n| `DEM`, `FRF`, `IEP`, `NLG`, `ATS`, `FIM`, `SIT`, `EUR` | 2 | 2 |\n| `PTE`, `GRD` | 0 | 2 |\n\nThe third row is the interesting one and is not a typo: for the escudo and the drachma,\ncalculation precision and display precision differ. Those currencies had subunits that were no\nlonger in practical use, so amounts were computed to whole units but presented with two\ndecimals. Any implementation that collapses the two columns into one will be wrong for exactly\ntwo of the fourteen currencies — a defect that is invisible for most test data.\n\nNote also that these are *currency* precisions, not a single function-wide rounding rule. The\nsame formula rounds differently depending on which target currency you name.\n\n\n\n### Arguments\n\n\n`EUROCONVERT(number, source, target, [full_precision], [triangulation_precision])`\n\n- **`number`** (required) — the currency value to convert, or a reference to a cell containing\n it.\n- **`source`** (required) — a three-letter ISO code from the list above, as text or a cell\n reference.\n- **`target`** (required) — likewise, the ISO code to convert to.\n\n\n" }, "signature": { "display": "EUROCONVERT(number, source, target, [full_precision], [triangulation_precision])", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false }, { "description": null, "name": "source", "optional": false, "repeats": false }, { "description": null, "name": "target", "optional": false, "repeats": false }, { "description": null, "name": "full_precision", "optional": true, "repeats": false }, { "description": null, "name": "triangulation_precision", "optional": true, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "not_implemented", "reason": "No catalogue row at this commit. In Excel it comes with the Euro Currency Tools add-in; build 20527 on Windows gives #NAME? without it." }, "arity": { "max": 5, "min": 3 }, "category": "User defined functions that are installed with add-ins", "classification": { "arg_preparation_profile": "ValuesOnlyPreAdapter", "coercion_lift_profile": "Custom", "determinism_class": "Deterministic", "error_collapse_profile": "None", "fec_dependency_profile": "None", "host_interaction_class": "None", "kernel_signature_class": "Custom", "rich_value_usage": "RichBlind", "surface_fec_dependency_profile": "RefOnly", "thread_safety_class": "SafePure", "volatility_class": "NonVolatile" }, "descriptions": { "long": null, "short": "An amount converted between euro member currencies through the euro", "short_source": "dna-calc-own" }, "docs": { "english_description": "Converts a number to euros, converts a number from euros to a euro member currency, or converts a number from one euro member currency to another by using the euro as an intermediary (triangulation)", "microsoft_url": "https://support.microsoft.com/en-us/office/euroconvert-function-79c8fd67-c665-450c-bb6c-15fc92f8345c" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "EUROCONVERT" }, { "locale": "bg-BG", "name": "EUROCONVERT" }, { "locale": "cs-CZ", "name": "EUROCONVERT" }, { "locale": "da-DK", "name": "EUROCONVERT" }, { "locale": "de-DE", "name": "EUROCONVERT" }, { "locale": "el-GR", "name": "EUROCONVERT" }, { "locale": "en-AU", "name": "EUROCONVERT" }, { "locale": "en-GB", "name": "EUROCONVERT" }, { "locale": "en-US", "name": "EUROCONVERT" }, { "locale": "es-ES", "name": "EUROCONVERT" }, { "locale": "et-EE", "name": "EUROCONVERT" }, { "locale": "fi-FI", "name": "EUROCONVERT" }, { "locale": "fr-FR", "name": "EUROCONVERT*" }, { "locale": "he-IL", "name": "EUROCONVERT" }, { "locale": "hr-HR", "name": "EUROCONVERT" }, { "locale": "hu-HU", "name": "EUROCONVERT" }, { "locale": "id-ID", "name": "EUROCONVERT" }, { "locale": "it-IT", "name": "EUROCONVERT" }, { "locale": "ja-JP", "name": "EUROCONVERT" }, { "locale": "ko-KR", "name": "EUROCONVERT" }, { "locale": "lt-LT", "name": "EUROCONVERT" }, { "locale": "lv-LV", "name": "EUROCONVERT" }, { "locale": "nb-NO", "name": "EUROCONVERT" }, { "locale": "nl-NL", "name": "EUROCONVERT" }, { "locale": "pl-PL", "name": "EUROCONVERT" }, { "locale": "pt-BR", "name": "EUROCONVERT" }, { "locale": "pt-PT", "name": "EUROCONVERT" }, { "locale": "ro-RO", "name": "EUROCONVERT" }, { "locale": "ru-RU", "name": "EUROCONVERT" }, { "locale": "sk-SK", "name": "EUROCONVERT" }, { "locale": "sl-SI", "name": "EUROCONVERT" }, { "locale": "sr-Latn-RS", "name": "EUROCONVERT" }, { "locale": "sv-SE", "name": "EUROCONVERT" }, { "locale": "th-TH", "name": "EUROCONVERT" }, { "locale": "tr-TR", "name": "EUROCONVERT işlevi" }, { "locale": "uk-UA", "name": "EUROCONVERT" }, { "locale": "vi-VN", "name": "EUROCONVERT" }, { "locale": "zh-CN", "name": "EUROCONVERT" }, { "locale": "zh-HK", "name": "EUROCONVERT" }, { "locale": "zh-TW", "name": "EUROCONVERT" } ], "signature": { "display": "EUROCONVERT(number, source, target, [full_precision], [triangulation_precision])", "parameters": [ { "description": null, "name": "number", "optional": false, "repeats": false }, { "description": null, "name": "source", "optional": false, "repeats": false }, { "description": null, "name": "target", "optional": false, "repeats": false }, { "description": null, "name": "full_precision", "optional": true, "repeats": false }, { "description": null, "name": "triangulation_precision", "optional": true, "repeats": false } ], "trailing_repeats": false }, "surface_name": "EUROCONVERT", "version_marker": null, "xlcall": null }, "microsoft": "https://support.microsoft.com/en-us/office/euroconvert-function-79c8fd67-c665-450c-bb6c-15fc92f8345c" }, "try_it": { "formula": "=EUROCONVERT(100,\"DEM\",\"EUR\")", "note": "This spelling is not registered in the OneCalc preview engine, so calculation returns #NAME? here. See the function guide for Excel availability.", "preview_status": "worksheet-error" }, "url": "https://handbook.dnacalc.com/functions/EUROCONVERT.html", "variants": [], "versions": [] }