Skip to content

Latest commit

 

History

History
87 lines (72 loc) · 4.4 KB

README.md

File metadata and controls

87 lines (72 loc) · 4.4 KB

MessageFormat 2.0 Default Function Registry

Table of Contents

  1. Introduction
  2. String Value Selection and Formatting
    1. :string
  3. Numeric Value Selection and Formatting
    1. :number
    2. :integer
    3. :math
    4. :currency
    5. :unit
  4. Date and Time Value Formatting
    1. :datetime
    2. :date
    3. :time

Introduction

This section defines the REQUIRED functions which are REQUIRED for conformance with this specification, along with RECOMMENDED functions that SHOULD be implemented to support additional functionality.

To accept a function means that an implementation MUST NOT emit an Unknown Function error for that function's identifier. To accept an option means that a function handler MUST NOT emit a Bad Option error for that option's identifier when used with the function it is defined for and MUST NOT emit a Bad Option error for any of the option values defined for that option. Accepting a function or its options does not mean that a particular output is produced. Implementations MAY emit an Unsupported Operation error for options or option values that they cannot support.

Functions can define options. An option can be REQUIRED or RECOMMENDED.

Implementations MUST accept each REQUIRED function and MUST accept all options defined as REQUIRED for those functions.

Implementations SHOULD accept each RECOMMENDED function. For each such function, the implementation MUST accept all options listed as REQUIRED for that function.

Implementations SHOULD accept options that are marked as RECOMMENDED.

Implementations MAY accept functions not defined in this specification. In addition, implementations SHOULD provide mechanisms for users to register and use user-defined functions and their associated functional handlers. Functions not defined by any version of this specification SHOULD use an implementation-defined or user-defined namespace.

Implementations MAY implement additional options not defined by any version of this specification for REQUIRED and RECOMMENDED functions. Such options MUST use an implementation-specific namespace.

Implementations MAY accept, for options defined in this specification, option values which are not defined in this specification. However, such values might become defined with a different meaning in the future, including with a different, incompatible name or using an incompatible value space. Supporting implementation-specific option values for REQUIRED or RECOMMENDED functions is NOT RECOMMENDED.

Implementations MAY accept, for operands or options defined in this specification, values with implementation-defined types. Such values can be useful to users in cases where local usage and support exists (including cases in which details vary from those defined by Unicode and CLDR).

For example:

  • Implementations are encouraged to accept some native representation for currency amounts as the operand in the function :currency.
  • A Java implementation might accept a java.time.chrono.Chronology object as a value for the date/time override option calendar
  • ICU4J's implementation might accept a com.ibm.icu.text.NumberingSystem object instead of using a Unicode Numbering System Identifier for the option numberingSystem in functions such as :number or :integer.

Future versions of this specification MAY define additional options and option values, subject to the rules in the Stability Policy, for functions found in this specification. As implementations are permitted to ignore options that they do not support, it is possible to write messages using options not defined below which currently format with no error, but which could produce errors when formatted with a later edition of this specification. Therefore, using options not explicitly defined here is NOT RECOMMENDED.