|
| 1 | +# MessageFormat 2.0 Default Function Registry |
| 2 | + |
| 3 | +## Table of Contents |
| 4 | + |
| 5 | +1. [Introduction](#introduction) |
| 6 | +1. [String Value Selection and Formatting](string.md) |
| 7 | + 1. [`:string`](string.md#the-string-function) |
| 8 | +1. [Numeric Value Selection and Formatting](number.md) |
| 9 | + 1. [`:number`](number.md#the-number-function) |
| 10 | + 1. [`:integer`](number.md#the-integer-function) |
| 11 | + 1. [`:math`](number.md#the-math-function) |
| 12 | + 1. [`:currency`](number.md#the-currency-function) |
| 13 | + 1. [`:unit`](number.md#the-unit-function) |
| 14 | +1. [Date and Time Value Formatting](datetime.md) |
| 15 | + 1. [`:datetime`](datetime.md#the-datetime-function) |
| 16 | + 1. [`:date`](datetime.md#the-date-function) |
| 17 | + 1. [`:time`](datetime.md#the-time-function) |
| 18 | + |
| 19 | +## Introduction |
| 20 | + |
| 21 | +This section defines the **REQUIRED** _functions_ which are REQUIRED for conformance with this specification, |
| 22 | +along with **RECOMMENDED** _functions_ that SHOULD be implemented to support |
| 23 | +additional functionality. |
| 24 | + |
| 25 | +To **_<dfn>accept</dfn>_** a function means that an implementation MUST NOT |
| 26 | +emit an _Unknown Function_ error for that _function_'s _identifier_. |
| 27 | +To _accept_ an _option_ means that a _function handler_ MUST NOT |
| 28 | +emit a _Bad Option_ error for that _option_'s _identifier_ when used with the _function_ |
| 29 | +it is defined for |
| 30 | +and MUST NOT emit a _Bad Option_ error for any of the _option_ values |
| 31 | +defined for that _option_. |
| 32 | +Accepting a _function_ or its _options_ does not mean that a particular output is produced. |
| 33 | +Implementations MAY emit an _Unsupported Operation_ error for _options_ |
| 34 | +or _option_ values that they cannot support. |
| 35 | + |
| 36 | +_Functions_ can define _options_. |
| 37 | +An _option_ can be **REQUIRED** or **RECOMMENDED**. |
| 38 | + |
| 39 | +Implementations MUST _accept_ each **REQUIRED** _function_ and |
| 40 | +MUST _accept_ all _options_ defined as **REQUIRED** for those _functions_. |
| 41 | + |
| 42 | +Implementations SHOULD _accept_ each **RECOMMENDED** _function_. |
| 43 | +For each such _function_, the implementation MUST accept all _options_ |
| 44 | +listed as **REQUIRED** for that _function_. |
| 45 | + |
| 46 | +Implementations SHOULD _accept_ _options_ that are marked as **RECOMMENDED**. |
| 47 | + |
| 48 | +Implementations MAY _accept_ _functions_ not defined in this specification. |
| 49 | +In addition, implementations SHOULD provide mechanisms for users to |
| 50 | +register and use user-defined _functions_ and their associated _functional handlers_. |
| 51 | +Functions not defined by any version of this specification SHOULD use |
| 52 | +an implementation-defined or user-defined _namespace_. |
| 53 | + |
| 54 | +Implementations MAY implement additional _options_ not defined |
| 55 | +by any version of this specification |
| 56 | +for **REQUIRED** and **RECOMMENDED** functions. |
| 57 | +Such _options_ MUST use an implementation-specific _namespace_. |
| 58 | + |
| 59 | +Implementations MAY _accept_, for _options_ defined in this specification, |
| 60 | +_option_ values which are not defined in this specification. |
| 61 | +However, such values might become defined with a different meaning in the future, |
| 62 | +including with a different, incompatible name |
| 63 | +or using an incompatible value space. |
| 64 | +Supporting implementation-specific _option_ values for **REQUIRED** or **RECOMMENDED** functions is NOT RECOMMENDED. |
| 65 | + |
| 66 | +Implementations MAY _accept_, for _operands_ or _options_ defined in this specification, |
| 67 | +values with implementation-defined types. |
| 68 | +Such values can be useful to users in cases where local usage and support exists |
| 69 | +(including cases in which details vary from those defined by Unicode and CLDR). |
| 70 | + |
| 71 | +> For example: |
| 72 | +> - Implementations are encouraged to _accept_ some native representation |
| 73 | +> for currency amounts as the _operand_ in the _function_ `:currency`. |
| 74 | +> - A Java implementation might _accept_ a `java.time.chrono.Chronology` object |
| 75 | +> as a value for the _date/time override option_ `calendar` |
| 76 | +> - ICU4J's implementation might _accept_ a `com.ibm.icu.text.NumberingSystem` object |
| 77 | +> instead of using a [Unicode Numbering System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeNumberSystemIdentifier) |
| 78 | +> for the option `numberingSystem` in _functions_ such as `:number` or `:integer`. |
| 79 | +
|
| 80 | +Future versions of this specification MAY define additional _options_ and _option_ values, |
| 81 | +subject to the rules in the [Stability Policy](#stability-policy), |
| 82 | +for _functions_ found in this specification. |
| 83 | +As implementations are permitted to ignore _options_ that they do not support, |
| 84 | +it is possible to write _messages_ using _options_ not defined below |
| 85 | +which currently format with no error, but which could produce errors |
| 86 | +when formatted with a later edition of this specification. |
| 87 | +Therefore, using _options_ not explicitly defined here is NOT RECOMMENDED. |
0 commit comments