Changes in 4.0 ⬇ ⬆
Introduced the concept of function identity. [Issue 520 PR 525 30 May 2023]
The parameter names property of a function item is dropped; the property never had any effect on the semantics of the language. [Issue 1896 ]
The parameter names property of a function item is dropped; the property never had any effect on the semantics of the language. [Issue 1896 ]
[Definition: A function item is an item that can be called. ] Function items have no serialization.
Note:
XDM 4.0 uses the term function item where XDM 3.1 used function. There is no distinction in meaning, but function item is preferred for clarity, because the unqualified term function has additional meanings in relation to function definitions in XSLT and XQuery.
A function item has the following properties:
name(xs:QName): An expanded QName, possibly absent.
identity: An abstract property that can be used to test whether two variables refer to the same function or to different functions. This property is exposed only for this purpose.
Note:
Currently, the concept of function identity is used for two purposes: firstly, when functions appear in the arguments supplied to the fn:deep-equal function; and secondly, in establishing whether the arguments and results of a function are "the same" when deciding whether the function is deterministic.
parameter names(xs:QName*): A list of distinct names, one for each of the function’s parameters.
Note:
This property is currently unused. There is no way of discovering the parameter names of a function item, and there is no functionality that depends on the parameter names.
parameter names(xs:QName*): A list of distinct names, one for each of the function’s parameters.
Note:
This property is currently unused. There is no way of discovering the parameter names of a function item, and there is no functionality that depends on the parameter names.
signature [Definition: A function signature represents the type of a function.] The signature of a function item comprises:
annotations A sequence of zero or more function annotations. [Definition: A function annotation consists of an annotation name (an instance of xs:QName) and an annotation value (an arbitrary sequence of atomic items).] Annotations are ordered and it is permitted for two annotations to share the same name.
body The body of a function provides the logic to map the arguments supplied in a function call into an instance of the function’s result type.
The function body is generally one of the following:
a user-written construct in XPath, XQuery, XSLT, or some other host language known to the processor.
vendor-supplied logic internal to the processor.
external logic written in some third-party programming language, to be invoked by the processor using implementation-dependent mechanisms.
These categories are not mutually exclusive; they may be used in combination.
Note:
The term “function body” replaces “function implementation”, to avoid confusion with the use of the term “implementation” in phrases such as “implementation-defined”.
captured context This includes a static and dynamic context for evaluation of the function body, as described in Section 2.2 Expression ContextXP. In particular it includes a set of nonlocal variable bindings (a mapping from xs:QName to item()*), which provides a value for each of the function’s free variables (i.e., variables referenced by the function’s body, other than locals and parameters).
Note:
Where the function body is implemented in XPath, XQuery, or XSLT, the captured context includes the static context for the user-written code (for example, its in-scope namespaces) as well as any nonlocal variable bindings.
Functions implemented internally by the processor may capture specific parts of the static or dynamic context, for example fn:position#0 captures the value of the context position.
[Definition: The arity of a function item is the number of its parameters. ] The number of names in a function’s parameter names, and the number of parameter types in its signature, must equal the function’s arity. [Definition: The arity of a function item is the number of its parameters. ] The number of parameter types in a function's signature, must equal the function’s arity. [Definition: The arity of a function item is the number of its parameters. ] The number of names in a function’s parameter names, and the number of parameter types in itsparameter types in a function's signature, must equal the function’s arity.
All function items match the generic function type function(*), which is itself a subtype of item(). A function signature defines a more specific function type, which is always a subtype of function(*). A function signature function(T1, T2, T3, ...) as TR is a subtype of another function signature function(U1, U2, U3, ...) as UR if (a) the two signatures have the same arity, (b) the return type TR is a subtype of UR, and (c) for each pair of parameter types, Tn is a supertype of Un. The rules are explained more fully in Section 3.3 Subtype RelationshipsXP. For example:
function(item()) as item() is a subtype of function(*)
function(item()) as xs:integer is a subtype of function(item()) as item()
function(item()) as item() is a subtype of function(xs:string) as item()
Changes in 4.0 ⬇ ⬆
Constructors are added, and the single accessor function is now an iterator over the key/value pairs in the map. [Issue 1335 20 July 2024]
Ordered maps are introduced. [Issue 1651 PR 1703 14 January 2025]
[Definition: A map item (also called simply a map) is a function item that represents an ordered sequence of key/value pairs, in which the keys are unique.] In other languages this is sometimes called a hash, dictionary, or associative array. The keys are atomic items, and each key in the map is unique (there is no other key to which it is equal). Each key is associated with a value that may be any sequence of zero or more items. There is no uniqueness constraint on values, only on keys. The semantics of equality when comparing keys are described in Section 14.2.1 fn:atomic-equalFO.
[Definition: The key/value pairs in a map are referred to as entries.]
Considered as a function item, a map is a function from atomic items to values: if M is a map and K is an atomic item, then the function call M(K) returns the value associated with the key K, if present, or an empty sequence otherwise. More specifically, the properties of a map when considered as a function item are:
name: absent.
identity: implementation dependent.
parameter names: A single parameter named key, in no namespace.
parameter names: A single parameter named key, in no namespace.
signature: function(xs:anyAtomicType) as item()*.
annotations: none.
body: equivalent to a call on map:get.
captured context: empty.
[Definition: A map containing exactly one entry is referred to as a single-entry map.]
[Definition: A map containing no entries is referred to as an empty map.]
Note:
Maps have no intrinsic identity separate from their content. A map can be given a transient identity, represented by an id property in its label, by applying the fn:pin function. This property is expected to be used in defining operations for deep update of maps.
[Definition: The order of entries in a map is referred to as entry order.] The entry order affects the result of functions such as map:keys and map:for-each, and also determines the order of entries when a map is serialized using the JSON output method.
Constructor and accessor functions for maps are defined in the following sections.
Changes in 4.0 ⬆
Constructors are added, and the single accessor function is now an iterator over the members of the array. [Issue 1335 20 July 2024]
[Definition: An array item (also called simply an array) is a function item that represents an array.] [Definition: An array is an ordered list of values; these values are called the members of the array.] Unlike sequences, a member of an array can be any value (including a sequence or an array). The number of members in an array is called its size, and they are referenced by their position, in the range 1 to the size of the array.
Considered as a function item, an array is a function from integers to values: if A is an array and N is an integer, then the function call A(N) returns the Nth member of the array (counting from one). More specifically, the properties of an array, considered as a function item, are:
Considered as a function item, a map is a function from atomic items to values: if M is a map and K is an atomic item, then the function call M(K) returns the value associated with the key K, if present, or an empty sequence otherwise. More specifically, the properties of a map when considered as a function item are:
name: absent.
identity: implementation dependent.
parameter names: A single parameter named index, in no namespace.
parameter names: A single parameter named index, in no namespace.
signature: function(xs:integer) as item()*.
annotations: none.
body: equivalent to a call on array:get.
captured context: empty.
[Definition: An array containing exactly one member is referred to as a single-member array.]
[Definition: An array containing no members is referred to as an empty array.]
Note:
Arrays have no intrinsic identity separate from their content. An array can be given a transient identity, represented by an id property in its label, by applying the fn:pin function. This property is expected to be used in defining operations for deep update of arrays.
Constructor and accessor functions for arrays are defined in the following sections.