XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (603 page)

See Also

boolean()
on page 721

string()
on page 877

cast
expression in Chapter 11 on page 655

one-or-more

The
one-or-more()
function returns its argument unchanged, provided that it is a sequence containing one or more items. If the input is an empty sequence, it reports an error.

Signature

Effect

The
one-or-more()
function returns its argument unchanged, provided that it is a sequence containing at least one item. If an empty sequence is supplied, it reports an error.

This function is useful with XPath processors that perform static type checking, as described in Chapter 5. Calling this function acts as a promise by the programmer that the argument will be a sequence containing at least one item. This allows the expression to be used in contexts that require a single value (for example, a call to a function that has a parameter with the required type
item()+
) when the processor might otherwise have reported a static type error. The XPath expression is still type-safe, because the check that the sequence does indeed contain at least one item will be done at runtime, just as it would with a processor that does not enforce static type checking.

Examples

Usage

As it happens, functions in the core library do not generally have a required type such as
item()+
, even in cases like
min()
,
max()
and
avg()
where there is no meaningful result that can be returned for an empty sequence. This is because the designers decided that rather than reporting an error for these functions when the argument is an empty sequence, it made more sense to return an empty sequence as the result. However, if you do want to make a runtime check that a sequence is not empty before calling a function such as
avg()
, then calling
one-or-more()
is a simple way to do the check.

See Also

exactly-one()
on page 777

zero-or-one()
on page 912

treat as
expression on page 678 in Chapter 11

position

The
position()
function returns the value of the context position. When processing a list of items,
position()
gives the number assigned to the current item in the list, with the first item being numbered as 1.

Changes in 2.0

None.

Signature

This function takes no arguments.

Effect

The XPath specification defines the value of the
position()
function in terms of the
context position
.

The context position is part of the
focus
, which is described in the spec as having three components: the context item, the context position, and the context size. However, it may be easier to think of the focus as being a bit like an
Iterator
object in a language such as Java. Behind the iterator is a list of items that are processed individually (though not necessarily in any particular order). The context item, position, and size can be thought of as three methods provided by this iterator object: the context position is a number that ranges from 1 to the size of the list, the context item is the item found at the context position, and the context size is the number of items in the list.

When a top-level XPath expression is evaluated (that is, an XPath expression that is not part of another expression), the context position is set by the host language. In XSLT, it is set from the XSLT context. For example:

• When a global
  
  declaration is being evaluated, or in certain other contexts such as evaluating the
  use
  expression in
  
  , or evaluating the initial template that matches the root node, it is normally set to 1 (one).
  
• When
  
  or
  
  is called to process a sequence of nodes, the nodes are numbered 1 to N in their sorted order, and while each node is being processed the context position is the number assigned to that node. (There is no implication that node 1 is processed before node 2, incidentally.)
  

This means that within an

iteration, the test

succeeds when the last item in the sequence is being processed.

Many APIs that enable XPath expressions to be executed from languages like Java or JavaScript allow the caller to set the context item, but not the context position or size. In such cases, the context position and size on entry to the XPath expression will both be one.

Within an XPath expression, the context size changes within a predicate and on the right-hand side of the
/
operator.

• In a predicate,
  position()
  refers to the position of the item that is being filtered using the predicate within the sequence of items being filtered. For example,
  $seq[position()!=1]
  selects all items except the first in a sequence, because the first item is the only one for which the predicate is false.
  
• It's less common to find
  position()
  being used on the right-hand-side of a
  /
  operator. It refers to the position of the context item in the sequence selected by the left-hand operand of the
  /
  . So
  $x/position()
  is another way of writing
  1 to count($x)
  . A more interesting example is: