This function is very similar to EXSLT
dynamic:map function. The description
below is almost literally taken from the EXSLT
specification.
The xsh:map function evaluates the
expression passed as the second argument for each of
the nodes passed as the first argument, and returns a
node-set of those values.
The expressions are evaluated relative to the nodes
passed as the first argument. In other words, the value
for each node is calculated by evaluating the XPath
expression with all context information being the same as
that for the call to the xsh:map
function itself, except for the following:
1) the context node is the node whose value is being
calculated, 2) the context position is the position of the
node within the node set passed as the first argument to
the xsh:map function, arranged in
document order, and 3) the context size is the number of
nodes passed as the first argument to the dyn:map function.
If the expression string passed as the second argument is an invalid XPath expression (including an empty string), this function returns an empty node set.
If XPATH evaluates as a node set, the
xsh:map function returns the union of
the node sets returned by evaluating the expression for
each of the nodes in the first argument. Note that this
may mean that the node set resulting from the call to the
xsh:map function contains a different
number of nodes from the number in the node set passed as
the first argument to the function.
If XPATH evaluates as a number, the
xsh:map function returns a node set
containing one xsh:number element
(namespace
http://xsh.sourceforge.net/xsh/) for
each node in the node set passed as the first argument to
the dyn:map function, in document order. The string value
of each xsh:number element is the same
as the result of converting the number resulting from
evaluating the expression to a string as with the number
function, with the exception that Infinity results in an
xsh:number holding the highest number
the implementation can store, and -Infinity results in an
xsh:number holding the lowest number
the implementation can store.
If XPATH evaluates as a boolean, the
xsh:map function returns a node set
containing one xsh:boolean element
(namespace
http://xsh.sourceforge.net/xsh/) for
each node in the node set passed as the first argument to
the xsh:map function, in document
order. The string value of each
xsh:boolean element is
true if the expression evaluates as
true for the node, and is empty if the expression evaluates as
false.
Otherwise, the xsh:map function returns
a node set containing one xsh:string
element (namespace
http://xsh.sourceforge.net/xsh/) for
each node in the node set passed as the first argument to
the xsh:map function, in document
order. The string value of each
xsh:string element is the same as the
result of converting the result of evaluating the
expression for the relevant node to a string as with the
string function.