XPath and XQuery Functions and Operators 4.0

20.1.1 fn:jnode

Summary

Delivers a root JNode^DM wrapping a map or array, enabling the use of lookup expression to navigate a JTree^DM rooted at that map or array.

Signature

fn:jnode(
$input	as (map(*)|array(*))
) as jnode-type(map(*)|array(*))

Properties

This function is nondeterministic, context-independent, and focus-independent.

Rules

The function creates a JNode^DM that wraps the supplied map or array. Specifically, it creates a root JNode whose ·content· property is $input, and whose ·parent·, ·position·, and ·selector· properties are absent.

This has the effect that lookup expressions starting from this JNode retain information for subsequent navigation.

A JNode has unique identity. If two maps or arrays M₁ and M₂ have the same function identity, as determined by the function-identity function, then jnode(M1) is jnode(M2)must return true: that is, the same JNode must be delivered for both.

Notes

It is to some extent implementation-defined whether two maps or arrays have the same function identity. Processors should ensure as a minimum that when a variable $m is bound to a map or array, calling jnode($m) more than once (with the same variable reference) will deliver the same JNode each time.

The effect of the coercion rules is technically that if an existing JNode is supplied as $input, the wrapped value will be extracted, and then rewrapped as a JNode: in practice, this can be short-circuited by returning the supplied JNode unchanged.

Although fn:jnode is available as a function for user applications to call explicitly, it is also invoked implicitly by some expressions, notably when a path expression is written in a form such as $map/child::*. Specifically, if the left-hand operand of the / operator is a map or array, then the supplied map or array is implicitly wrapped in a JNode.

The effect of applying fn:jnode to a map or array is that subsequent retrieval operations within the wrapped map or array return results that retain useful information about where the results were found. For example, consider an expression such as json-doc($source)//name. This expression returns a set of JNodes representing all entries in the JTree having the key "name"; each of these JNodes contains not only the value of the relevant "name" entry, but also the key (which in this simple example is always "name" and the containing map. This means, for example, if $result is the result of the expression json-doc($source) // name, then:

• $result / .. / ssn locates the map that contained each name, and returns the value of the ssn entry in that map.

• $result / ancestor::course returns any course entries in containing maps.

• $result / ancestor::* => jnode-selector() returns a sequence of map keys and array index values representing the location of the found entries within the JSON structure.

An alternative way of wrapping a map or array, rather than calling jnode($X), is to use the path expression $X/..

There are two situations where a map or array is implicitly wrapped in a JNode:

• When the value of the left-hand operand of the / operator includes a map or array;

• When the context value for evaluation of an AxisStep includes a map or array.

Examples

Expression:	jnode([ "a", "b", "c" ])/*[1]/../*[last()] => string()
Result:	"c" (The call on fn:jnode would happen automatically).
Expression:	jnode([ "a", "b", "c", "d" ])/* => jnode-selector()
Result:	1, 2, 3, 4
Expression:	let $data := { "fr": { "capital": "Paris", "languages": [ "French" ] }, "de": { "capital": "Berlin", "languages": [ "German" ] } } return jnode($data)//languages[. = 'German']/../capital) => string()
Result:	"Berlin"