Project

Profile

Help

How to connect?
Download (69.5 KB) Statistics
| Branch: | Revision:

he / src / userdoc / expressions.xml @ 7728ae0b

1
<?xml version="1.0" encoding="utf-8"?>
2
<article id="expressions" title="Reference: XPath Syntax">
3
   <h1>Reference: XPath Syntax</h1>
4

    
5

    
6
   <p>This section is an informal guide to the syntax of XPath expressions, which are used in Saxon
7
      both within XSLT stylesheets, and as parameters to various Java interfaces. XPath is also a
8
      subset of XQuery. For formal specifications, see the <a href="http://www.w3.org/TR/xpath20/"
9
         class="bodylink">XPath 2.0</a>, <a href="http://www.w3.org/TR/xpath-30/" class="bodylink"
10
         >XPath 3.0</a>, and <a href="http://www.w3.org/TR/xpath-31/" class="bodylink">XPath 3.1</a>
11
      specifications.</p>
12

    
13
   <aside>See the <a class="bodylink" href="/xpath-api">XPath API for Java</a> section for details
14
      on using the XPath Java interfaces, or the <a class="bodylink" href="/dotnet/dotnetapi">Saxon
15
         API for .NET</a> section for the .NET interface.</aside>
16
   
17
   <aside>Saxon provides further extensions to the XPath expression syntax (these require Saxon-PE
18
      or higher), for details see <a class="bodylink" href="/extensions/syntax-extensions">Syntax
19
         Extensions</a>.</aside>
20

    
21
   <h3 class="subtitle">New Features in XPath 3.0 and 3.1</h3>
22

    
23
   <p>There are summaries of <a class="bodylink" href="xpath30new">New Features in XPath 3.0</a>
24
      (originally published as XPath 2.1) and <a class="bodylink" href="xpath31new">New Features in
25
         XPath 3.1</a>, and information about the implementation in Saxon.</p>
26

    
27
   <p>An important new feature in XPath 3.1 is the definition of maps and arrays. These features
28
      are available in all current Saxon editions, whether you are using XPath, XQuery, or XSLT. 
29
      A major motivation for their introduction was to support the data structures that can be defined
30
      in JSON, but they have many other uses where more complex data structures need to be built. For more
31
      details see <a class="bodylink" href="xpath30maps">Maps in XPath</a> and <a class="bodylink"
32
         href="xpath31arrays">Arrays in XPath</a>.</p>
33

    
34
   <h3 class="subtitle">XPath basics</h3>
35

    
36
   <p>In XPath 2.0 (and higher) all values are considered as sequences. A sequence consists of zero
37
      or more items; an item may be a node or an atomic value, or in 3.0 it may also be a function
38
      item. Examples of atomic values are integers, strings, booleans, and dates. A single value
39
      such as a number is considered as a sequence of length 1. The empty sequence is written as
40
         <code>()</code>; a singleton sequence may be written as <code>"a"</code> or
41
         <code>("a")</code>, and a general sequence is written as <code>("a", "b", "c")</code>.</p>
42

    
43
   <p>The node-sets of XPath 1.0 are replaced in XPath 2.0 by sequences of nodes. Path expressions
44
      will return node sequences whose nodes are in document order with no duplicates, but other
45
      kinds of expression may return sequences of nodes in any order, with duplicates permitted.</p>
46

    
47
   <h3 class="subtitle">XPath syntax</h3>
48

    
49
   <p>The functions provided in the XPath function library are listed separately: see the <a
50
         class="bodylink" href="/functions">Function Library</a> section. This section summarizes
51
      the following syntactic constructs and operators provided in XPath 2.0 and higher:</p>
52

    
53
   <nav except="xpath30new xpath31new">
54
      <ul/>
55
   </nav>
56

    
57
   <section id="literals" title="Constants">
58
      <h1>Constants</h1>
59

    
60
      <p><strong>String literals</strong> are written as <code>"London"</code> or
61
            <code>'Paris'</code>. In each case you can use the opposite kind of quotation mark
62
         within the string: <code>'He said "Boo"'</code>, or <code>"That's rubbish"</code>. In a
63
         stylesheet XPath expressions always appear within XML attributes, so it is usual to use one
64
         kind of delimiter for the attribute and the other kind for the literal. Anything else can
65
         be written using XML character entities. String delimiters can be doubled within the string
66
         to represent the delimiter itself: for example <code>&lt;xsl:value-of select='"He said,
67
            ""Go!"""'/&gt;</code></p>
68

    
69
      <p><strong>Numeric constants</strong> follow the Java rules for decimal literals: for example,
70
            <code>12</code> or <code>3.05</code>; a negative number can be written as (say)
71
            <code>-93.7</code>, though technically the minus sign is not part of the literal. (Also,
72
         note that you may need a space before the minus sign to avoid it being treated as a hyphen
73
         within a preceding name). The numeric literal is taken as a double precision floating point
74
         number if it uses scientific notation (e.g. <code>1.0e7</code>), as fixed point decimal if
75
         it includes a full stop, or as an integer otherwise. Decimal values (and integers) in Saxon
76
         have unlimited precision and range (they use the Java classes <code>BigInteger</code> and
77
            <code>BigDecimal</code> internally). Note that a value such as <code>3.5</code> was
78
         handled as a double-precision floating point number in XPath 1.0, but as a decimal number
79
         in XPath 2.0: this may affect the precision of arithmetic results.</p>
80

    
81
      <p>There are no boolean constants as such: instead use the function calls <a
82
            class="bodylink code" href="/functions/fn/true">true()</a> and <a class="bodylink code"
83
            href="/functions/fn/false">false()</a>.</p>
84

    
85
      <p>Constants of other data types can be written using constructors, which look like function
86
         calls but generally take a string literal as their argument. For example,
87
            <code>xs:float("10.7")</code> produces a single-precision floating point number. Saxon
88
         implements constructors for all of the built-in data types defined in XML Schema Part
89
         2.</p>
90

    
91
      <p>An example for <strong>date</strong> and <strong>dateTime</strong> values: you can write
92
         constants for these data types as <code>xs:date("2002-04-30")</code> or
93
            <code>xs:dateTime("1966-07-31T15:00:00Z")</code>.</p>
94

    
95
      <p>The argument to a constructor can contain leading or trailing whitespace, as determined by
96
         the whitespace facet for the target data type.</p>
97
   </section>
98
   <section id="variables" title="Variable References">
99
      <h1>Variable References</h1>
100

    
101
      <p>The value of a variable (local or global variable, local or global parameter) may be
102
         referred to using the construct <code>$<i>name</i></code>, where <code><i>name</i></code>
103
         is the variable name.</p>
104

    
105
      <p>The variable is always bound at the textual place where the expression containing it
106
         appears; for example a variable used within an <a class="bodylink code"
107
            href="/xsl-elements/attribute-set">xsl:attribute-set</a> must be in scope at the point
108
         where the attribute-set is defined, not the point where it is used.</p>
109

    
110
      <p>A variable may be declared to be of a particular type, for example it may be constrained to
111
         be an integer, or a sequence of strings, or an attribute node. In a schema-aware
112
         environment, this may also be a reference to a user-defined type in a schema. If there is
113
         no type declared for the variable, it may take a value of any data type, and in general it
114
         is not possible to determine its data type statically.</p>
115

    
116
      <p>It is an error to refer to a variable that has not been declared.</p>
117

    
118
      <p>Starting with XPath 2.0, variables (known as range variables) may be declared within an
119
         XPath expression, not only using <a class="bodylink code" href="/xsl-elements/variable"
120
            >xsl:variable</a> elements in an XSLT stylesheet. The expressions that declare variables
121
         are the <a class="bodylink" href="../for">for expressions</a>, and <a class="bodylink"
122
            href="../quantified">quantified expressions</a> (<code>some</code> and
123
            <code>every</code>). In XPath 3.0, variables can also be declared in a <a
124
            class="bodylink" href="../let">let expression</a>, as well as in the signature of an
125
         inline function.</p>
126
   </section>
127
   <section id="functioncalls" title="Function Calls">
128
      <h1>Function Calls</h1>
129

    
130
      <p>A function call in XPath 2.0 takes the form <code>F ( arg1, arg2, ...)</code>. In general,
131
         the function name is a QName. A library of core functions is defined in the XPath and XSLT
132
         specifications (in versions 2.0, 3.0, and 3.1). For details of these functions, including
133
         notes on their implementation in this Saxon release, see the <a class="bodylink"
134
            href="/functions">Function Library</a>. Additional functions are available (in a special
135
         namespace) as Saxon extensions: these are also listed in the <a class="bodylink"
136
            href="/functions">Function Library</a>, with some further information in the <a
137
            class="bodylink" href="/extensions">Extensions</a> section. Further functions may be
138
         implemented by the user, either as XSLT <i>stylesheet functions</i> (see <a
139
            class="bodylink code" href="/xsl-elements/function">xsl:function</a>), as XQuery
140
         functions, or as Java <i>extension functions</i> (see the <a class="bodylink"
141
            href="/extensibility">Extensibility Mechanisms</a> section).</p>
142

    
143
      <p>XPath 3.0 introduces dynamic function calls: <code>EXPR ( arg1, arg2, ...)</code> where
144
            <code>EXPR</code> is an expression that evaluates to a function item.</p>
145
   </section>
146
   <section id="axissteps" title="Axis steps">
147
      <h1>Axis steps</h1>
148

    
149

    
150
      <p>The basic primitive for accessing a source document is the <i>axis step</i>. Axis steps may
151
         be combined into path expressions using the path operators <code>/</code> and
152
            <code>//</code>, and they may be filtered using filter expressions in the same way as
153
         the result of any other expression.</p>
154

    
155
      <p>An axis step has the basic form <code>axis :: node-test</code>, and selects nodes on a
156
         given axis that satisfy the node-test. The axes available are:</p>
157
      <table>
158
         <tr>
159
            <td>
160
               <p>ancestor</p>
161
            </td>
162
            <td>
163
               <p>Selects ancestor nodes starting with the current node and ending with the document
164
                  node</p>
165
            </td>
166
         </tr>
167
         <tr>
168
            <td>
169
               <p>ancestor-or-self</p>
170
            </td>
171
            <td>
172
               <p>Selects the current node plus all ancestor nodes</p>
173
            </td>
174
         </tr>
175
         <tr>
176
            <td>
177
               <p>attribute</p>
178
            </td>
179
            <td>
180
               <p>Selects all attributes of the current node (if it is an element)</p>
181
            </td>
182
         </tr>
183
         <tr>
184
            <td>
185
               <p>child</p>
186
            </td>
187
            <td>
188
               <p>Selects the children of the current node, in document order</p>
189
            </td>
190
         </tr>
191
         <tr>
192
            <td>
193
               <p>descendant</p>
194
            </td>
195
            <td>
196
               <p>Selects the children of the current node and their children, recursively (in
197
                  document order)</p>
198
            </td>
199
         </tr>
200
         <tr>
201
            <td>
202
               <p>descendant-or-self</p>
203
            </td>
204
            <td>
205
               <p>Selects the current node plus all descendant nodes</p>
206
            </td>
207
         </tr>
208
         <tr>
209
            <td>
210
               <p>following</p>
211
            </td>
212
            <td>
213
               <p>Selects the nodes that follow the current node in document order, other than its
214
                  descendants</p>
215
            </td>
216
         </tr>
217
         <tr>
218
            <td>
219
               <p>following-sibling</p>
220
            </td>
221
            <td>
222
               <p>Selects all subsequent child nodes of the same parent node</p>
223
            </td>
224
         </tr>
225
         <tr>
226
            <td>
227
               <p>namespace</p>
228
            </td>
229
            <td>
230
               <p>Selects all the in-scope namespaces for an element (this axis is deprecated in
231
                  the W3C XPath specification, but Saxon will continue to support it)</p>
232

    
233
            </td>
234
         </tr>
235
         <tr>
236
            <td>
237
               <p>parent</p>
238
            </td>
239
            <td>
240
               <p>Selects the parent of the current node</p>
241
            </td>
242
         </tr>
243
         <tr>
244
            <td>
245
               <p>preceding</p>
246
            </td>
247
            <td>
248
               <p>Selects the nodes that precede the current node in document order, other than its
249
                  ancestors</p>
250
            </td>
251
         </tr>
252
         <tr>
253
            <td>
254
               <p>preceding-sibling</p>
255
            </td>
256
            <td>
257
               <p>Selects all preceding child nodes of the same parent node</p>
258
            </td>
259
         </tr>
260
         <tr>
261
            <td>
262
               <p>self</p>
263
            </td>
264
            <td>
265
               <p>Selects the current node</p>
266
            </td>
267
         </tr>
268
      </table>
269

    
270
      <p>When the child axis is used, <code>child::</code> may be omitted, and when the attribute
271
         axis is used, <code>attribute::</code> may be abbreviated to <code>@</code>. The expression
272
            <code>parent::node()</code> may be shortened to <code>..</code></p>
273

    
274
      <p>
275
         <i>The expression <code>.</code> is no longer synonymous with <code>self::node()</code>,
276
            since it may now select items that are not nodes. If the context item is not a node, any
277
            use of a path expression will raise an error.</i>
278
      </p>
279

    
280
      <p>The node-test may be, for example:</p>
281
      <ul>
282
         <li>
283
            <p>a node name</p>
284
         </li>
285
         <li>
286
            <p>
287
               <code>prefix:*</code> to select nodes in a given namespace</p>
288
         </li>
289
         <li>
290
            <p>
291
               <code>*:localname</code> to select nodes with a given local name, regardless of
292
               namespace</p>
293
         </li>
294
         <li>
295
            <p>
296
               <code>text()</code> to select text nodes</p>
297
         </li>
298
         <li>
299
            <p>
300
               <code>node()</code> to select any node</p>
301
         </li>
302
         <li>
303
            <p>
304
               <code>processing-instruction()</code> to select any processing instruction</p>
305
         </li>
306
         <li>
307
            <p>
308
               <code>processing-instruction('literal')</code> to select processing instructions with
309
               the given name (target)</p>
310
         </li>
311
         <li>
312
            <p>
313
               <code>comment()</code> to select comment nodes</p>
314
         </li>
315
         <li>
316
            <p>
317
               <code>element()</code> or <code>element(*)</code> to select any element node</p>
318
         </li>
319
         <li>
320
            <p>
321
               <code>element(N)</code> to select any element node named <code>N</code></p>
322
         </li>
323
         <li>
324
            <p>
325
               <code>element(*, T)</code> to select any element node whose type annotation is
326
                  <code>T</code>, or a subtype of <code>T</code></p>
327
         </li>
328
         <li>
329
            <p>
330
               <code>element(N, T)</code> to select any element node whose name is <code>N</code>
331
               and whose type annotation is <code>T</code>, or a subtype of <code>T</code></p>
332
         </li>
333
         <li>
334
            <p>
335
               <code>schema-element(N)</code> to select any element node whose name is
336
                  <code>N</code>, or an element in the substitution group of <code>N</code>, that
337
               conforms to the schema-defined type for a global element declaration named
338
                  <code>N</code> in an imported schema</p>
339
         </li>
340
         <li>
341
            <p>
342
               <code>attribute</code> or <code>attribute(*)</code> to select any attribute node</p>
343
         </li>
344
         <li>
345
            <p>
346
               <code>attribute(N)</code> to select any attribute node named <code>N</code></p>
347
         </li>
348
         <li>
349
            <p>
350
               <code>attribute(*, T)</code> to select any attribute node whose type annotation is
351
                  <code>T</code>, or a subtype of <code>T</code></p>
352
         </li>
353
         <li>
354
            <p>
355
               <code>attribute(N, T)</code> to select any attribute node whose name is
356
                  <code>N</code> and whose type annotation is <code>T</code>, or a subtype of
357
                  <code>T</code></p>
358
         </li>
359
         <li>
360
            <p>
361
               <code>schema-attribute(N)</code> to select any attribute node whose name is
362
                  <code>N</code>, that conforms to the schema-defined type for a global attribute
363
               declaration named <code>N</code> in an imported schema</p>
364
         </li>
365
      </ul>
366
   </section>
367
   <section id="parentheses" title="Parentheses and operator precedence">
368
      <h1>Parentheses and operator precedence</h1>
369

    
370

    
371
      <p>In general an expression may be enclosed in parentheses without changing its meaning.</p>
372

    
373
      <p>If parentheses are not used, operator precedence follows the sequence below, starting with
374
         the operators that bind most tightly. Within each group the operators are evaluated
375
         left-to-right.</p>
376
      <table>
377
         <tr>
378
            <td>
379
               <p>
380
                  <strong>Operator</strong>
381
               </p>
382
            </td>
383
            <td>
384
               <p>
385
                  <strong>Meaning</strong>
386
               </p>
387
            </td>
388
         </tr>
389
         <tr>
390
            <td>
391
               <p>unary <code>?</code></p>
392
            </td>
393
            <td>
394
               <p>unary lookup operator</p>
395
            </td>
396
         </tr>
397
         <tr>
398
            <td>
399
               <p><code>[]</code>, <code>()</code>, binary <code>?</code></p>
400
            </td>
401
            <td>
402
               <p>predicate, function call, lookup operator</p>
403
            </td>
404
         </tr>
405
         <tr>
406
            <td>
407
               <p><code>/</code>, <code>//</code></p>
408
            </td>
409
            <td>
410
               <p>path operator</p>
411
            </td>
412
         </tr>
413
         <tr>
414
            <td>
415
               <p>
416
                  <code>!</code>
417
               </p>
418
            </td>
419
            <td>
420
               <p>simple mapping operator</p>
421
            </td>
422
         </tr>
423
         <tr>
424
            <td>
425
               <p>unary <code>-</code>, unary <code>+</code></p>
426
            </td>
427
            <td>
428
               <p>unary plus and minus</p>
429
            </td>
430
         </tr>
431
         <tr>
432
            <td>
433
               <p>
434
                  <code>=></code>
435
               </p>
436
            </td>
437
            <td>
438
               <p>arrow operator</p>
439
            </td>
440
         </tr>
441
         <tr>
442
            <td>
443
               <p>
444
                  <code>cast as</code>
445
               </p>
446
            </td>
447
            <td>
448
               <p>dynamic type conversion</p>
449
            </td>
450
         </tr>
451
         <tr>
452
            <td>
453
               <p>
454
                  <code>castable as</code>
455
               </p>
456
            </td>
457
            <td>
458
               <p>type test</p>
459
            </td>
460
         </tr>
461
         <tr>
462
            <td>
463
               <p>
464
                  <code>treat as</code>
465
               </p>
466
            </td>
467
            <td>
468
               <p>static type conversion</p>
469
            </td>
470
         </tr>
471
         <tr>
472
            <td>
473
               <p>
474
                  <code>instance of</code>
475
               </p>
476
            </td>
477
            <td>
478
               <p>type test</p>
479
            </td>
480
         </tr>
481
         <tr>
482
            <td>
483
               <p><code>except</code>, <code>intersect</code></p>
484
            </td>
485
            <td>
486
               <p>set difference and intersection</p>
487
            </td>
488
         </tr>
489
         <tr>
490
            <td>
491
               <p><code>|</code>, <code>union</code></p>
492
            </td>
493
            <td>
494
               <p>union operation on sets</p>
495
            </td>
496
         </tr>
497
         <tr>
498
            <td>
499
               <p><code>*</code>, <code>div</code>, <code>idiv</code>, <code>mod</code></p>
500
            </td>
501
            <td>
502
               <p>multiply, divide, integer divide, modulo</p>
503
            </td>
504
         </tr>
505
         <tr>
506
            <td>
507
               <p><code>+</code>, <code>-</code></p>
508
            </td>
509
            <td>
510
               <p>plus, minus</p>
511
            </td>
512
         </tr>
513
         <tr>
514
            <td>
515
               <p>
516
                  <code>to</code>
517
               </p>
518
            </td>
519
            <td>
520
               <p>range expression</p>
521
            </td>
522
         </tr>
523
         <tr>
524
            <td>
525
               <p>
526
                  <code>||</code>
527
               </p>
528
            </td>
529
            <td>
530
               <p>string concatenation (XPath 3.0)</p>
531
            </td>
532
         </tr>
533
         <tr>
534
            <td>
535
               <p><code>=</code>, <code>!=</code>, <code>is</code>, <code>&lt;</code>,
536
                     <code>&lt;=;</code>, <code>&gt;</code>, <code>&gt;=</code>, <code>eq</code>,
537
                     <code>ne</code>, <code>lt</code>, <code>le</code>, <code>gt</code>,
538
                     <code>ge</code></p>
539
            </td>
540
            <td>
541
               <p>comparisons</p>
542
            </td>
543
         </tr>
544
         <tr>
545
            <td>
546
               <p>
547
                  <code>and</code>
548
               </p>
549
            </td>
550
            <td>
551
               <p>Boolean and</p>
552
            </td>
553
         </tr>
554
         <tr>
555
            <td>
556
               <p>
557
                  <code>or</code>
558
               </p>
559
            </td>
560
            <td>
561
               <p>Boolean or</p>
562
            </td>
563
         </tr>
564
         <tr>
565
            <td>
566
               <p>
567
                  <code>if</code>
568
               </p>
569
            </td>
570
            <td>
571
               <p>conditional expressions</p>
572
            </td>
573
         </tr>
574
         <tr>
575
            <td>
576
               <p><code>some</code>, <code>every</code></p>
577
            </td>
578
            <td>
579
               <p>quantified expressions</p>
580
            </td>
581
         </tr>
582
         <tr>
583
            <td>
584
               <p>
585
                  <code>let</code>
586
               </p>
587
            </td>
588
            <td>
589
               <p>variable declaration (XPath 3.0)</p>
590
            </td>
591
         </tr>
592
         <tr>
593
            <td>
594
               <p>
595
                  <code>for</code>
596
               </p>
597
            </td>
598
            <td>
599
               <p>iteration (mapping) over a sequence</p>
600
            </td>
601
         </tr>
602
         <tr>
603
            <td>
604
               <p><code>,</code> (comma)</p>
605
            </td>
606
            <td>
607
               <p>Sequence concatenation</p>
608
            </td>
609
         </tr>
610
      </table>
611

    
612
      <p>The various operators are described, in roughly the above order, in the sections that
613
         follow.</p>
614
   </section>
615
   <section id="filter" title="Filter expressions">
616
      <h1>Filter expressions</h1>
617

    
618

    
619
      <p>The notation <code>E[P]</code> is used to select items from the sequence obtained by
620
         evaluating <code>E</code>. If the predicate <code>P</code> is numeric, the predicate
621
         selects an item if its position (counting from 1) is equal to <code>P</code>; otherwise,
622
         the <i>effective boolean value</i> of <code>P</code> determines whether an item is selected
623
         or not. The effective boolean value of a sequence is false if the sequence is empty, or if
624
         it contains a single item that is one of: the boolean value false, the zero-length string,
625
         or a numeric zero or NaN value. If the first item of the sequence is a node, or if the
626
         sequence is a singleton boolean, number or string other than those listed above, the
627
         effective boolean value is true. In other cases (for example, if the sequence contains two
628
         booleans or a date), evaluating the effective boolean value causes an error.</p>
629

    
630
      <p>From XPath 2.0, <code>E</code> may be any sequence, it is not restricted to a node
631
         sequence. Within the predicate, the expression <code>.</code> (dot) refers to the context
632
         item, that is, the item currently being tested. The XPath 1.0 concept of context node has
633
         thus been generalized, for example <code>.</code> can refer to a string or a number.</p>
634

    
635
      <p>Generally the order of items in the result preserves the order of items in <code>E</code>.
636
         As a special case, however, if <code>E</code> is a step using a reverse axis (e.g.
637
         preceding-sibling), the position of nodes for the purpose of evaluating the predicate is in
638
         reverse document order, but the result of the filter expression is in forwards document
639
         order.</p>
640

    
641
      <p>In XPath 3.0, the postfix operators <code>[]</code> (filter) and <code>()</code> (function
642
         call) may be mixed and apply in left-to-right order. For example <code>$a[3](2)</code>
643
         selects the third item in a sequence (of function items), and calls it with the argument
644
         value 2; while <code>$a(2)[3]</code> calls the function item <code>$a</code> with argument
645
         value 2, and then selects the third item in the resulting sequence.</p>
646
   </section>
647
   <section id="path" title="Path expressions">
648
      <h1>Path expressions</h1>
649

    
650

    
651
      <p>A path expression is a sequence of steps separated by the <code>/</code> or <code>//</code>
652
         operator. For example, <code>../@desc</code> selects the <code>desc</code> attribute of the
653
         parent of the context node.</p>
654

    
655
      <p>In XPath 2.0, path expressions were generalized so that any expression can be used as an
656
         operand of <code>/</code>, (both on the left and the right), so long as the value of the
657
         left-hand operand is a sequence of nodes. For example, it is possible to use a union
658
         expression (in parentheses) or a call to the <a class="bodylink code"
659
            href="/functions/fn/id">id()</a> or <a class="bodylink code" href="/functions/fn/key"
660
            >key()</a> functions. The right-hand operand is evaluated once for each node in the
661
         sequence that results from evaluating the left-hand operand, with that node as the context
662
         item. In the result of the path expression, nodes are sorted in document order, and
663
         duplicates are eliminated.</p>
664

    
665
      <p>In practice, it only makes sense to use expressions on the right of <code>/</code> if they
666
         depend on the context item. It is legal to write <code>$x/$y</code> provided both
667
            <code>$x</code> and <code>$y</code> are sequences of nodes, but the result is exactly
668
         the same as writing <code>./$y</code>.</p>
669

    
670
      <p>Note that the expressions <code>./$X</code> or <code>$X/.</code> can be used to remove
671
         duplicates from <code>$X</code> and sort the results into document order. The same effect
672
         can be achieved by writing <code>$X|()</code>.</p>
673

    
674
      <p>The operator <code>//</code> is an abbreviation for
675
            <code>/descendant-or-self::node()/</code>. An expression of the form <code>/E</code> is
676
         shorthand for <code>root(.)/E</code>, and the expression <code>/</code> on its own is
677
         shorthand for <code>root(.)</code>.</p>
678

    
679
      <p>The expression on the left of the <code>/</code> operator must return a node or sequence of
680
         nodes. The expression on the right can return either a sequence of nodes or a sequence of
681
         atomic values (but not a mixture of the two). This allows constructs such as
682
            <code>$x/number()</code>, which returns the sequence obtained by converting each item in
683
            <code>$x</code> to a number.</p>
684
   </section>
685
   <section id="simplemapping" title="Simple mapping expressions">
686
      <h1>Simple mapping expressions</h1>
687

    
688

    
689
      <p>XPath 3.0 introduces the "simple mapping" operator <code>!</code>. The expression
690
            <code>A!B</code> evaluates expression <code>B</code> once for each item in the result of
691
         evaluating <code>A</code>, and concatenates the results. In the case where evaluating
692
            <code>A</code> returns a sequence of nodes, <code>A!B</code> has the same effect as
693
            <code>A/B</code> except that the result is not sorted into document order, and
694
         duplicates are not eliminated.</p>
695

    
696
      <p>The semantics of the expression <code>A!B</code> are precisely equivalent to the XSLT
697
         construct <code>&lt;xsl:for-each select="A"&gt;&lt;xsl:sequence
698
            select="B"/&gt;&lt;/xsl:for-each&gt;</code>; in Saxon they generate the same internal
699
         code.</p>
700
   </section>
701
   <section id="cast" title="Cast as, Treat as">
702
      <h1>Cast as, Treat as</h1>
703

    
704

    
705
      <p>The expression <code>E cast as T</code> converts the value of expression <code>E</code> to
706
         type <code>T</code>. Whether <code>T</code> is a built-in type or a user-defined type, the
707
         effect is exactly the same as using the constructor function <code>T (E)</code>.</p>
708

    
709
      <p>The expression <code>E treat as T</code> is designed for environments that perform static
710
         type checking. Saxon doesn't do static type checking, so this expression has very little
711
         use, except to document an assertion that the expression <code>E</code> is of a particular
712
         type. A run-time failure will be reported if the value of <code>E</code> is not of type
713
            <code>T</code>; no attempt is made to convert the value to this type.</p>
714
   </section>
715
   <section id="except" title="Set difference and intersection">
716
      <h1>Set difference and intersection</h1>
717

    
718

    
719
      <p>These operators were introduced in XPath 2.0.</p>
720

    
721
      <p>The expression <code>E1 except E2</code> selects all nodes that are in <code>E1</code>
722
         unless they are also in <code>E2</code>. Both expressions must return sequences of nodes.
723
         The results are returned in document order. For example, <code>@* except @note</code>
724
         returns all attributes except the <code>note</code> attribute.</p>
725

    
726
      <p>The expression <code>E1 intersect E2</code> selects all nodes that are in both
727
            <code>E1</code> and <code>E2</code>. Both expressions must return sequences of nodes.
728
         The results are returned in document order. For example, <code>preceding::fig intersect
729
            ancestor::chapter//fig</code> returns all preceding <code>fig</code> elements within the
730
         current chapter.</p>
731
   </section>
732
   <section id="union" title="Union">
733
      <h1>Union</h1>
734

    
735

    
736
      <p>The <code>|</code> operator was available in XPath 1.0; the keyword <code>union</code> was
737
         added in XPath 2.0 as a synonym, because it is familiar to SQL users.</p>
738

    
739
      <p>The expression <code>E1 union E2</code> selects all nodes that are in either
740
            <code>E1</code> or <code>E2</code> or both. Both expressions must return sequences of
741
         nodes. The results are returned in document order. For example, <code>/book/(chapter |
742
            appendix)/section</code> returns all <code>section</code> elements within a
743
            <code>chapter</code> or <code>appendix</code> of the selected <code>book</code>
744
         element.</p>
745
   </section>
746
   <section id="arithmetic" title="Arithmetic expressions">
747
      <h1>Arithmetic expressions</h1>
748
      
749
      <h2 class="subtitle">Unary plus and minus</h2>
750

    
751
      <p>The unary minus operator changes the sign of a number. For example <code>-1</code> is minus
752
         one, and <code>-0e0</code> is the double value negative zero.</p>
753

    
754
      <p>Unary plus has very little effect: the value of <code>+1</code> is the same as the value of
755
            <code>1</code>. It does, however, provide a quick way of forcing untyped values to be
756
         numeric, for example you can write <code>&lt;xsl:sort select="+@price"/&gt;</code> to force
757
         a numeric sort, if you find <code>&lt;xsl:sort select="number(@price)"/&gt;</code> too
758
         verbose for your tastes.</p>
759
      
760
      <h2 class="subtitle">Multiplication and division</h2>
761

    
762
      <p>The operator <code>*</code> multiplies two numbers. If the operands are of different types,
763
         one of them is promoted to the type of the other (for example, an integer is promoted to a
764
         decimal, a decimal to a double). The result is the same type as the operands after
765
         promotion.</p>
766

    
767
      <p>The operator <code>div</code> divides two numbers. Dividing two integers produces a double;
768
         in other cases the result is the same type as the operands, after promotion. In the case of
769
         decimal division, the precision is the sum of the precisions of the two operands, plus
770
         six.</p>
771

    
772
      <p>The operator <code>idiv</code> performs integer division. For example, the result of
773
            <code>10 idiv 3</code> is <code>3</code>.</p>
774

    
775
      <p>The <code>mod</code> operator returns the modulus (or remainder) after division. See the
776
         XPath 2.0 specification for details of the way that negative numbers are handled.</p>
777

    
778
      <p>The operators <code>*</code> and <code>div</code> may also be used to multiply or divide a
779
         duration by a number. For example, <code>fn:dayTimeDuration('PT12H') * 4</code> returns the
780
         duration two days.</p>
781
      
782
      <h2 class="subtitle">Addition and subtraction</h2>
783

    
784
      <p>The operators <code>+</code> and <code>-</code> perform addition and subtraction of
785
         numbers, in the usual way. If the operands are of different types, one of them is promoted,
786
         and the result is the same type as the operands after promotion. For example, adding two
787
         integers produces an integer; adding an integer to a double produces a double.</p>
788

    
789
      <p>Note that the <code>-</code> operator may need to be preceded by a space to prevent it
790
         being parsed as part of the preceding name.</p>
791

    
792
      <p>XPath 2.0 also allows these operators to be used for adding durations to durations or to
793
         dates and times.</p>
794
   </section>
795
   <section id="range" title="Range expressions">
796
      <h1>Range expressions</h1>
797

    
798

    
799
      <p>The expression <code>E1 to E2</code> returns a sequence of integers. For example, <code>1
800
            to 5</code> returns the sequence <code>1, 2, 3, 4, 5</code>. This is useful in
801
            <code>for</code> expressions, for example the first five nodes of a node sequence can be
802
         processed by writing <code>for $i in 1 to 5 return (//x)[$i]</code>.</p>
803

    
804
      <p>If you prefer, you can write this as <code>(//x)[position() = 1 to 5]</code>. This works
805
         because comparison of a single integer (<code>position()</code>) to a sequence of integers
806
            (<code>1 to 5</code>) is true if the integer on the left is equal to any integer in the
807
         sequence.</p>
808

    
809
      <p>Saxon does a good job of optimizing range expressions. For example given the expression
810
            <code>$x = (1 to 1000000)</code>, it won't actually compare <code>$x</code> with every
811
         integer in this range; rather, it tests that <code>$x</code> is a whole number and that it
812
         is greater than 0 and less than 1000001.</p>
813

    
814

    
815
   </section>
816
   <section id="comparisons" title="Comparisons">
817
      <h1>Comparisons</h1>
818

    
819

    
820
      <p>The simplest comparison operators are <code>eq</code>, <code>ne</code>, <code>lt</code>
821
         <code>le</code>, <code>gt</code>, and <code>ge</code>. These compare two atomic values of
822
         the same type, for example two integers, two dates, or two strings. In the case of strings,
823
         the default collation is used (see <code>DEFAULT_COLLATION</code> in <a class="bodylink"
824
            href="/configuration/config-features">Configuration Features</a>). If the operands are
825
         not atomic values, an error is raised.</p>
826

    
827
      <p>The operators <code>=</code>, <code>!=</code>, <code>&lt;</code>, <code>&lt;=</code>,
828
            <code>&gt;</code>, and <code>&gt;=</code> can compare arbitrary sequences. The result is
829
         true if any pair of items from the two sequences has the specified relationship, for
830
         example <code>$A = $B</code> is true if there is an item in <code>$A</code> that is equal
831
         to some item in <code>$B</code>. If an argument is a node, the effect depends on whether
832
         the source document has been validated against a schema. In Saxon-EE, with a validated
833
         source document, Saxon will use the typed value of the node in the comparison. Without
834
         schema validation, the type of the node is <code>untypedAtomic</code>, and the effect is
835
         that the value is converted to the type of the other operand.</p>
836

    
837
      <p>The operator <code>is</code> tests whether the operands represent the same (identical)
838
         node. For example, <code>title[1] is *[@note][1]</code> is true if the first
839
            <code>title</code> child is the first child element that has a <code>note</code>
840
         attribute. If either operand is an empty sequence the result is an empty sequence (which
841
         will usually be treated as false).</p>
842

    
843
      <p>The operators <code>&lt;&lt;</code> and <code>&gt;&gt;</code> test whether one node
844
         precedes or follows another in document order.</p>
845
   </section>
846
   <section id="instanceof" title="Instance of and Castable as">
847
      <h1>Instance of and Castable as</h1>
848

    
849

    
850
      <p>The expression <code>E instance of T</code> tests whether the value of expression
851
            <code>E</code> is an instance of type <code>T</code>, or of a subtype of <code>T</code>.
852
         For example, <code>$p instance of attribute()+</code> is true if the value of
853
            <code>$p</code> is a sequence of one or more attribute nodes. It returns false if the
854
         sequence is empty or if it contains an item that is not an attribute node. The detailed
855
         rules for defining types, and for matching values against a type, are given in the XPath
856
         specification.</p>
857

    
858
      <p>Saxon also allows testing of the type annotation of an element or attribute node using
859
         tests of the form <code>element(*, T)</code>, <code>attribute(*, T)</code>. This is
860
         primarily useful with a schema-aware query or stylesheet, since the only way a node can
861
         acquire a type annotation (other than the special values <code>xs:untyped</code> and
862
            <code>xs:untypedAtomic</code>) is by validating a document against a schema.</p>
863

    
864
      <p>The <code>instance of</code> operator tests whether a value is marked or labelled as an
865
         instance of the relevant type, not whether it is convertible to that type. For example,
866
            <code>5 instance of xs:positiveInteger</code> returns false, because the value
867
            <code>5</code> is labelled with the type <code>xs:integer</code>, not
868
            <code>xs:positiveInteger</code>.</p>
869

    
870
      <p>The expression <code>E castable as T</code> tests whether the expression <code>E cast as
871
            T</code> would succeed. It is useful, for example, for testing whether a string contains
872
         a valid date before attempting to cast it to a date. So <code>5 castable as
873
            xs:positiveInteger</code> succeeds. The construct is useful because XPath provides no
874
         way of trapping the error if the cast is attempted and fails. (Note however that XQuery 3.0
875
         and XSLT 3.0 both introduce a try/catch mechanism.)</p>
876
   </section>
877
   <section id="conditionals" title="Conditional Expressions">
878
      <h1>Conditional Expressions</h1>
879

    
880

    
881
      <p>XPath 2.0 introduced a conditional expression of the form <code>if ( E1 ) then E2 else
882
            E3</code>. For example, <code>if (@discount) then @discount else 0</code> returns the
883
         value of the <code>discount</code> attribute if it is present, or zero otherwise.</p>
884

    
885
      <p>It's also worth noting the coding pattern <code>(@price, 5)[1]</code> which returns the
886
         value of <code>@price</code> if it exists, or 5 otherwise.</p>
887
   </section>
888
   <section id="quantified" title="Quantified Expressions">
889
      <h1>Quantified Expressions</h1>
890

    
891

    
892
      <p>The expression <code>some $x in E1 satisfies E2</code> returns true if there is an item in
893
         the sequence <code>E1</code> for which the <i>effective boolean value</i> of
894
            <code>E2</code> is true. Note that <code>E2</code> must use the range variable
895
            <code>$x</code> to refer to the item being tested; it does not become the context item.
896
         For example, <code>some $x in @* satisfies $x eq ""</code> is true if the context item is
897
         an element that has at least one zero-length attribute value.</p>
898

    
899
      <p>Similarly, the expression <code>every $x in E1 satisfies E2</code> returns true if every
900
         item in the sequence given by <code>E1</code> satisfies the condition.</p>
901
   </section>
902
   <section id="for" title="For Expressions">
903
      <h1>For Expressions</h1>
904

    
905

    
906
      <p>The expression <code>for $x in E1 return E2</code> returns the sequence that results from
907
         evaluating <code>E2</code> once for every item in the sequence <code>E1</code>. Note that
908
            <code>E2</code> must use the range variable <code>$x</code> to refer to the item being
909
         tested; it does not become the context item. For example, <code>sum(for $v in order-item
910
            return $v/price * $v/quantity)</code> returns the total value of (price times quantity)
911
         for all the selected <code>order-item</code> elements.</p>
912
   </section>
913
   <section id="let" title="Let Expressions">
914
      <h1>Let Expressions</h1>
915

    
916
      <p>XPath 3.0 allows <code>let</code> expressions, previously available only in XQuery. For
917
         example the expression <code>let $x := . return //a[@status=$x]</code> binds the variable
918
            <code>$x</code> to the context item, and then evaluates the expression
919
            <code>//a[@status=$x]</code> which makes use of this variable.</p>
920
   </section>
921
   <section id="boolean" title="Boolean expressions: AND and OR">
922
      <h1>Boolean expressions: AND and OR</h1>
923

    
924

    
925
      <p>The expression <code>E1 and E2</code> returns true if the <i>effective boolean values</i>
926
         of <code>E1</code> and <code>E2</code> are both true.</p>
927

    
928
      <p>The expression <code>E1 or E2</code> returns true if the <i>effective boolean values</i> of
929
         either or both of <code>E1</code> and <code>E2</code> are true.</p>
930

    
931
      <p>The specification allows the operands to be evaluated in either order, but Saxon will
932
         normally evaluate them left-to-right, which means if you write something like <code>$a
933
            instance of xs:integer and $x = (1 to $a)</code>, then you won't get an error if
934
            <code>$a</code> is not an integer. But the specification doesn't guarantee this.</p>
935
   </section>
936
   <section id="sequence" title="Sequence expressions">
937
      <h1>Sequence expressions</h1>
938

    
939

    
940
      <p>The expression <code>E1 , E2</code> returns the sequence obtained by concatenating the
941
         sequences <code>E1</code> and <code>E2</code>.</p>
942

    
943
      <p>For example, <code>$x = ("London", "Paris", "Tokyo")</code> returns true if the value of
944
            <code>$x</code> is one of the strings listed.</p>
945

    
946
      <p>A sequence is often written in parentheses, as in the above example, but the parentheses
947
         are technically necessary only for operator precedence reasons.</p>
948

    
949
      <p>The expression <code>()</code> denotes an empty sequence, which is often used to indicate
950
         absence of a value.</p>
951
   </section>
952
   <section id="xpath30new" title="New features in XPath 3.0">
953
      <h1>New features in XPath 3.0</h1>
954

    
955
      <aside>From Saxon 9.6, Saxon supports XPath 3.0 by default. Some features vary by Saxon
956
         edition: higher-order functions require Saxon-PE or higher, and schema-awareness requires
957
         Saxon-EE.</aside>
958

    
959
      <p>Some of the new features in XPath 3.0 are as follows. For full details, see the W3C
960
         specifications, and for further Saxon implementation details see the <a class="bodylink"
961
            href="/conformance/xpath31">Conformance</a> section.</p>
962

    
963
      <ol>
964
         <li>
965
            <p>The concatenation operator <code>||</code> is available (as in SQL). For example,
966
                  <code>('$' || 12.5)</code> returns the string <code>$12.5</code>.</p>
967
         </li>
968

    
969
         <li>
970
            <p>A new <a class="bodylink" href="../simplemapping">simple mapping operator</a> is
971
               available, <code>!</code>. This works rather like <code>/</code>, except there is no
972
               restriction that the left hand operand must be a node sequence, and there is no sorting of
973
               results into document order. For example, <code>(1 to 7)!(.*.)</code> returns the
974
               sequence <code>(1, 4, 9, 16, 25, 36, 49)</code>.</p>
975
         </li>
976

    
977
         <li>
978
            <p>Local variables can be declared in a <a class="bodylink" href="../let">let
979
                  expression</a>, for example <code>let $x := /*/@version return //e[@version =
980
                  $x]</code>.</p>
981
         </li>
982

    
983
         <li>
984
            <p>Inline function items can be declared, and used as arguments to higher-order
985
               functions. For example <code>map(//employee, function($e){$e/salary +
986
                  $e/bonus})</code>. A <i>function item</i> is a third kind of item, alongside nodes
987
               and atomic values. The function represented by a function item <code>$f</code> can be
988
               invoked using a dynamic function call <code>$f(args)</code>. <i>Higher-order
989
                  functions require Saxon-PE or higher.</i></p>
990
         </li>
991

    
992
         <li>
993
            <p>Expanded QNames can be written in the notation <code>Q{uri}local</code>, allowing
994
               XPath expressions to be written that do not depend on an externally-supplied
995
               namespace context.</p>
996
         </li>
997
      </ol>
998

    
999
      <p>A number of new functions are available, including <code>head</code>, <code>tail</code>,
1000
            <code>for-each</code>, <code>filter</code>, <code>for-each-pair</code>, <code>pi</code>,
1001
            <code>sin</code>, <code>cos</code>, <code>tan</code>, <code>asin</code>,
1002
            <code>acos</code>, <code>atan</code>, <code>sqrt</code>, <code>format-integer</code>,
1003
         and others. For details see the <a class="bodylink" href="/functions">Functions</a>
1004
         section.</p>
1005

    
1006

    
1007
      <p>Maps and arrays are defined in XPath 3.1, and are available in Saxon whether you are using XPath, XSLT, or XQuery; 
1008
         for more details see <a class="bodylink" href="../xpath30maps">Maps in XPath</a> and <a class="bodylink" href="../xpath31arrays">Arrays in XPath</a>. 
1009
         </p>
1010

    
1011
   </section>
1012
   <section id="xpath31new" title="New features in XPath 3.1">
1013
      <h1>New features in XPath 3.1</h1>
1014

    
1015
      <aside>From Saxon 9.7, Saxon supports XPath 3.1 by default. Some features vary by Saxon
1016
         edition: streaming and schema-awareness requires Saxon-EE. Higher-order functions
1017
      required Saxon-PE in the past, but are available in Saxon-HE from 10.</aside>
1018

    
1019
      <p>Some of the new features in XPath 3.1 are as follows. For full details, see the W3C
1020
         specifications, and for further Saxon implementation details see the <a class="bodylink"
1021
            href="/conformance/xpath31">Conformance</a> section.</p>
1022

    
1023
      <ol>
1024
         <li>
1025
            <p>The arrow operator <code>=></code> is available to allow function chaining.
1026
            The expression <code>substring-before(substring-after($in, '['), ']')</code> can now
1027
            be replaced by the more legible <code>$in => substring-after('[') => substring-before(']')</code>.</p>
1028
         </li>
1029
         <li>
1030
            <p>Maps are available (for more details see <a class="bodylink" href="../xpath30maps"
1031
                  >Maps in XPath</a>). They provide a similar capability to "objects" in Javascript,
1032
               or "associative arrays" in some other languages. But as befits a function language
1033
               like XPath, they are immutable. A collection of functions is available to operate on
1034
               maps (see the <a class="bodylink" href="/functions/map">Function Library</a>), and in
1035
               addition there is new syntax for a map constructor (of the form <code>map{ key :
1036
                  value, key : value }</code>) where both the keys and values are arbitrary
1037
               expressions. There is a sequence type for maps <code>map(K, V)</code>, defining the
1038
               types of the key and value parts. Maps are functions, so given a map <code>$M</code>,
1039
               the entry for a key <code>$K</code> can be obtained as the result of the function
1040
               call <code>$M($K)</code>. If the key to be accessed is known statically, and if it takes
1041
               the form of an <code>NCName</code>, then a lookup
1042
            expression of the form <code>$employee?name</code> can be used. A unary form of this operator
1043
            is also available, allowing <code>$employees[?name='John']</code>.</p>
1044
         </li>
1045
         <li>
1046
            <p>Arrays are available (for more details see <a class="bodylink" href="../xpath31arrays"
1047
               >Arrays in XPath</a>). Arrays differ from the traditional sequences in that they can be
1048
               nested. The members of an array can be arbitrary values, including sequences and arrays. An array
1049
               is an item, so some care is needed: the syntax <code>$A[1]</code> returns the array item unchanged
1050
               rather than selecting a member of the array. A library of functions is available to operate
1051
               on arrays ((see the <a class="bodylink" href="/functions/array">Function Library</a>). The expression
1052
               <code>[1, 5, 7, (10 to 20)]</code> can be used to construct an array where the number of members is known
1053
               statically (this example creates an array with four members, of which the last is a sequence of 11 items), and the
1054
               expression <code>array{ 1, 5, 7, (10 to 20)}</code> can be used to construct an array with a variable number of 
1055
               members, provided that each member is a single item (in this case the array has 14 members, each a single integer).
1056
               A member of an array can be accessed using the syntax <code>$A(3)</code> or <code>$A?3</code>.</p>
1057
         </li>
1058
      </ol>
1059

    
1060
      <p>A number of new functions are available, including <code>random-number-generator()</code>,
1061
            <code>sort()</code>, <code>parse-ietf-date()</code>, and functions to read and write
1062
         data in JSON format. For details see the <a class="bodylink" href="/functions">Functions
1063
            Library</a>.</p>
1064

    
1065
   </section>
1066
   <section id="xpath30maps" title="Maps in XPath">
1067
      <h1>Maps in XPath</h1>
1068

    
1069
      <aside>Since Saxon 9.7, maps are available in all Saxon editions.</aside>
1070

    
1071
      <p>An important new feature in XPath 3.1 is the definition of maps. (This feature is in fact
1072
         included in the XPath 3.0 implementation in Saxon, and thus was available as an advanced
1073
         feature since Saxon 9.5, before the full implementation of XPath 3.1 in Saxon 9.7).</p>
1074

    
1075
      <p>A map is a new kind of XDM item (alongside nodes and atomic values). In fact, a map is a
1076
         kind of function: you can think of it as a function defined extensionally (by tabulating
1077
         the value of the function for all possible arguments) rather than intensionally (by means
1078
         of an algorithm).</p>
1079

    
1080
      <p>A map is a set of entries. Each entry is a key-value pair. The <i>key</i> is always an
1081
         atomic value. The <i>value</i> is any XDM value: a sequence of nodes, atomic values,
1082
         functions, or maps.</p>
1083

    
1084
      <p>Maps, like sequences, are immutable. When you add an entry to a map, you get a new map; the
1085
         original is unchanged. Saxon provides an efficient implementation of maps that achieves
1086
         this without copying the whole map every time an entry is added.</p>
1087

    
1088
      <p>Also like sequences, maps do not have an intrinsic type of their own, but rather have a
1089
         type that can be inferred from what they contain. A map conforms to the type <code>map(K,
1090
            V)</code> if all the keys are of type <code>K</code> and all the values are of type
1091
            <code>V</code>. For example if the keys are all strings, and the values are all
1092
            <code>employee</code> elements, then the map conforms to the type <code>map(xs:string,
1093
            element(employee))</code>.</p>
1094

    
1095
      <p>There are several ways to create a map:</p>
1096

    
1097
      <ul>
1098
         <li>
1099
            <p>If the number of entries is known, you can use the constructor syntax <code>map { key
1100
                  : value, key : value, ... }</code>. (A previous version of the spec used
1101
                  "<code>:=</code>" rather than <code>":"</code> as the separator, since Saxon 9.7
1102
               this alternative is no longer supported.) Here the keys and values can be any "simple
1103
               expression" (an expression not containing a top-level comma). If the keys and values
1104
               are all known statically, you might write: <code>map { "a" : 1, "e" : 2, "i" : 3, "o"
1105
                  : 4, "u" : 5 }</code>. You can use this construct anywhere an XPath expression can
1106
               be used, for example in the <code>select</code> attribute of an <a
1107
                  class="bodylink code" href="/xsl-elements/variable">xsl:variable</a> element.</p>
1108
         </li>
1109
         <li>
1110
            <p>The function <a class="bodylink code" href="/functions/map/merge">map:merge()</a>
1111
               takes a number of maps as input, and combines them into a single map. This can be
1112
               used to construct a map where the number of entries is not known statically: for
1113
               example <code>map:merge(for $i in 1 to 10 return map{$i :
1114
                  codepoints-to-string($i)})</code>.</p>
1115
            <p>(In previous working drafts, this function was named <code>map:new()</code>, but this
1116
               name is no longer supported since Saxon 9.7.)</p>
1117
         </li>
1118
         <li>
1119
            <p>A single-entry map can also be constructed using the function <code>map:entry($key,
1120
                  $value)</code>.</p>
1121
         </li>
1122
      </ul>
1123

    
1124
      <p>It is also possible to create maps using the XSLT instructions <a class="bodylink code"
1125
            href="/xsl-elements/map">xsl:map</a> and <a class="bodylink code"
1126
            href="/xsl-elements/map-entry">xsl:map-entry</a>.</p>
1127

    
1128
      <p>Given a map <code>$M</code>, the value corresponding to a given key <code>$K</code> can be
1129
         found either by invoking the map as a function: <code>$M($K)</code>, or by calling
1130
            <code>map:get($M, $K)</code>.</p>
1131

    
1132
      <p>The summary of the full list of functions that operate on maps is as follows; for full
1133
         details see the <a class="bodylink" href="/functions/map">Functions Library</a>. The prefix
1134
            <code>map</code> represents the namespace URI
1135
            <code>http://www.w3.org/2005/xpath-functions/map</code>.</p>
1136

    
1137
      <ul>
1138
         <li>
1139
            <p><code>map:merge($maps as map(*)) as map(*)</code>: takes a sequence of maps as input
1140
               and combines them into a single map.</p>
1141
         </li>
1142
         <li>
1143
            <p><code>map:size($map as map(*)) as xs:integer</code>: returns the number of entries
1144
               (key/value pairs) in a map.</p>
1145
         </li>
1146

    
1147
         <li>
1148
            <p><code>map:keys($map as map(*)) as xs:anyAtomicType*</code>: returns the keys that are
1149
               present in a map, in unpredictable order.</p>
1150
         </li>
1151
         <li>
1152
            <p><code>map:contains($map as map(*), $key as xs:anyAtomicType) as xs:boolean</code>:
1153
               returns true if the given key is present in the map.</p>
1154
         </li>
1155
         <li>
1156
            <p><code>map:get($map as map(*), $key as xs:anyAtomicType) as item()*</code>: returns
1157
               the value associated with the given key if present, or the empty sequence otherwise.
1158
               Equivalent to calling <code>$map($key)</code>.</p>
1159
         </li>
1160
         <li>
1161
            <p><code>map:put($map as map(*), $key as xs:anyAtomicType, $value as item()*) as
1162
                  map(*)</code>: adds an entry to a map, which replaces any existing entry for the
1163
               same key, returning a new map.</p>
1164
         </li>
1165
         <li>
1166
            <p><code>map:entry($key as xs:anyAtomicType, $value as item()*)</code>: creates a
1167
               singleton map. Useful as an argument to <code>map:merge()</code>.</p>
1168
         </li>
1169
         <li>
1170
            <p><code>map:remove($map as map(*), $key as xs:anyAtomicType) as map(*)</code>: removes
1171
               an entry from a map (if it was present), returning a new map; if not present, returns
1172
               the existing map unchanged.</p>
1173
         </li>
1174
         <li>
1175
            <p><code>map:for-each($map as map(*), $f as function(xs:anyAtomicType, item()) as
1176
                  item()*) as item()*</code>: processes every key/value pair in a map by applying
1177
               the given function, returning the results as a sequence in unpredictable order.</p>
1178
         </li>
1179
      </ul>
1180
   </section>
1181
   <section id="xpath31arrays" title="Arrays in XPath">
1182
      <h1>Arrays in XPath</h1>
1183
      
1184
      <aside>Since Saxon 9.7, arrays are available in all Saxon editions.</aside>
1185
      
1186
      <p>XPath 3.1 introduces arrays as a new data type. (Unlike maps, arrays are not defined for
1187
      use in XSLT 3.0 unless XPath 3.1 is supported. But Saxon's XSLT 3.0 implementation
1188
      always supports XPath 3.1.)</p>
1189
      
1190
      <p>The main reason arrays were introduced was to allow JSON data structures to be represented
1191
      faithfully. However there are many other ways you can take advantage of arrays.</p>
1192
      
1193
      <p>Arrays differ from sequences in a number of ways:</p>
1194
      
1195
      <ul>
1196
         <li>
1197
            <p>Arrays can be nested (an array can have other arrays as its members). In fact the members
1198
               of an array can be arbitrary XDM values, including nodes, atomic values, sequences, functions, and maps.
1199
               A member of an array can also be an empty sequence. 
1200
            </p>
1201
         </li>
1202
         <li>
1203
            <p>An array is a single item, so you can have a sequence of arrays.</p>
1204
            <aside>Beware: because an array is a single item, <code>$array[1]</code> returns the entire array, not
1205
            the first member of the array. Similarly, <code>for $x in [1, 2, 3] return $x+1</code> throws a type
1206
            error, because <code>$x</code> is bound to the entire array, not to each of its members in turn.</aside>
1207
         </li>
1208
         <li>
1209
            <p>To access the Nth member of an array, use the syntax <code>$array($N)</code>. This works because
1210
            an array is a function: given an integer <code>$N</code> as the argument, this function returns the member 
1211
               in position <code>$N</code>.</p>
1212
         </li>
1213
         <li>
1214
            <p>If you know which member you want statically, you can also use the syntax <code>$array?1</code> which is equivalent
1215
               to $array(1).</p>
1216
         </li>
1217
         <li>
1218
            <p>As with sequences, the members of an array are addressed by integers in the range 1 to N, where
1219
            N is the length of the array. However, unlike sequences, any attempt to access a member using an out-of-range
1220
            index is a dynamic error (<code>FOAY0001</code>).</p>
1221
         </li>
1222
         <li>
1223
            <p>Operators and functions designed to work on sequences, such as <code>count()</code>, for expressions,
1224
            filter expressions, <code>head()</code>, <code>tail()</code>, <code>remove()</code>, <code>insert()</code> and so on, 
1225
               do not work as you might expect on arrays.
1226
            They don't return an error, because an array is a sequence of length one, but they don't return the result you
1227
            might have expected. Instead, there is a library of functions available to perform analogous operations on arrays.</p>
1228
            
1229
            <p>However, operators designed to work on sequences of atomic values will also produce useful results when applied to
1230
            arrays of atomic values. This is because atomizing an array produces the corresponding sequence. So, for example,
1231
            <code>sum([1,2,3,4])</code> returns 10, as does <code>sum([[1,2], [3,4]])</code>.</p>
1232
         </li>
1233
      </ul>
1234
     
1235
      
1236
      <p>Arrays, like all other XDM values, are immutable. When you append or replace or remove a member entry
1237
         in an array, you get a new array; the
1238
         original is unchanged. From Saxon 9.9, the implementation uses a "persistent immutable" data structure
1239
         under the covers, to ensure that making a small change to an array (such as replacing a single member)
1240
         does not require copying the entire array.</p>
1241
      
1242
      <p>As with sequences and maps, arrays do not have an intrinsic type of their own, but rather have a
1243
         type that can be inferred from what they contain. An array conforms to the type <code>array(T)</code> if 
1244
         all of its members are of type <code>T</code>. For example if the members are all strings,
1245
         then the array conforms to the type <code>array(xs:string)</code>.</p>
1246
      
1247
      <p>There are several ways to create an array:</p>
1248
      
1249
      <ul>
1250
         <li>
1251
            <p>If the number of members is known, you can use the constructor syntax <code>[ value, value, value ]</code>.
1252
               Here the values can be any "simple
1253
               expression" (an expression not containing a top-level comma). If the values
1254
               are all known statically, you might write: <code>[1, 2, "a", "b"]</code>. 
1255
               You can use this construct anywhere an XPath expression can
1256
               be used, for example in the <code>select</code> attribute of an <a
1257
                  class="bodylink code" href="/xsl-elements/variable">xsl:variable</a> element.
1258
            The members do not need to be single items: for example <code>[(), 1, 2, 5 to 10]</code>
1259
            constructs an array with four members, the members being sequences of length 0, 1, 1, and 6 respectively.
1260
            The construct <code>[]</code> returns an empty array.</p>
1261
         </li>
1262
         <li>
1263
            <p>If the number of members is unknown, but if you know that each member of the array will be a single item,
1264
               you can use the construct <code>array{ value }</code> where <code>value</code> is any sequence. For example,
1265
               <code>array{(), 1, 2, 5 to 10}</code> constructs an array with eight members, these being the single
1266
            integers 1, 2, 5, 6, 7, 8, 9, and 10.</p>
1267
         </li>
1268
      </ul>
1269
      
1270
      <p>There are no XSLT 3.0 instructions for creating arrays, analogous to the instructions <code>xsl:map</code>
1271
      and <code>xsl:map-entry</code>. Saxon however fills the gap with the instructions <code>saxon:array</code> and
1272
         <code>saxon:array-member</code>: see <a class="bodylink" href="/extensions/instructions">Extension instructions</a>.</p>
1273
      
1274
      <p>The summary of the full list of functions that operate on arrays is as follows; for full
1275
         details see the <a class="bodylink" href="/functions/array">Functions Library</a>. The prefix
1276
         <code>array</code> represents the namespace URI
1277
         <code>http://www.w3.org/2005/xpath-functions/array</code>.</p>
1278
      
1279
      <ul>
1280
         <li>
1281
            <p><code>array:append</code>: adds one new member to the end of an array. For example, <code>array:append([], 5)</code>
1282
            returns <code>[5]</code>.</p>
1283
         </li>
1284
         <li>
1285
            <p><code>array:filter</code>: returns those members of an array that satisfy some condition, expressed as a function.
1286
            For example, <code>array:filter([1 to 5], function($x){$x mod 2 = 1})</code> returns <code>[1, 3, 5]</code>.</p>
1287
         </li>
1288
         <li>
1289
            <p><code>array:flatten</code>: replaces an array by the sequence-concatenation of its members, recursively.
1290
               For example, <code>array:flatten(([1], [2 to 4], [3, [4, 5]]))</code> returns
1291
               <code>(1, 2, 3, 4, 3, 4, 5)</code>.</p>
1292
         </li>
1293
         <li>
1294
            <p><code>array:fold-left</code>: applies a function cumulatively to successive members of the array: each call
1295
               is applied to two arguments, being the value so far, and the next member of the array.
1296
               For example, <code>array:fold-left(array{1 to 5}, 0, function($x, $y){$x + $y})</code> returns <code>15</code>, 
1297
               while <code>array:fold-left(array{1 to 3}, [], function($x, $y){[$x, $y]})</code> returns <code>[[[[], 1], 2], 3]</code>.</p>
1298
         </li>
1299
         <li>
1300
            <p><code>array:fold-right</code>: applies a function cumulatively to successive members of the array: each call
1301
               is applied to two arguments, being the next member of the array, and the result of applying the function to the remainder
1302
               of the array.
1303
               For example, <code>array:fold-right(array{1 to 5}, 0, function($x, $y){$x + $y})</code> returns <code>15</code>, 
1304
               while <code>array:fold-right(array{1 to 3}, [], function($x, $y){[$x, $y]})</code> returns <code>[1, [2, [3, []]]]</code>.</p>
1305
         </li>
1306
         <li>
1307
            <p><code>array:for-each</code>: applies a function to each member of an array, and returns
1308
               an array containing the results.
1309
               For example, <code>array:for-each(array{1 to 5}, function($x){$x + 1})</code> returns <code>[2, 3, 4, 5, 6]</code>.</p>
1310
         </li>
1311
         <li>
1312
            <p><code>array:for-each-pair</code>: applies a function to pairs of corresponding items from two supplied arrays.
1313
               For example, <code>array:for-each-pair(['x', 'y', 'z'], [1, 2, 3], concat#2)</code> returns <code>['x1', 'y2', 'z3']</code>.</p>
1314
         </li>
1315
         <li>
1316
            <p><code>array:get</code>: returns the member at a given position (starting from 1).
1317
               For example, <code>array:get([3, 4, 5], 2)</code> returns <code>4</code>.</p>
1318
         </li>
1319
         <li>
1320
            <p><code>array:head</code>: returns the first member of the array.
1321
               For example, <code>array:head([1 to 5, 1 to 10]</code> returns <code>(1 to 5)</code> (a sequence, not an array).</p>
1322
         </li>
1323
         <li>
1324
            <p><code>array:insert-before</code>: inserts a new member at a given position.
1325
               For example, <code>array:insert-before([1, 2, 3, 4], 3, ()]</code> returns <code>[1, 2, (), 3, 4]</code>.</p>
1326
         </li>
1327
         <li>
1328
            <p><code>array:join</code>: Joins a number of arrays end-to-end to create a new array.
1329
               For example, <code>array:join(([1], [2 to 4], [3, [4, 5]]))</code> returns <code>[1, (2, 3, 4), 3, [4, 5]]</code>.</p>
1330
         </li>
1331
         <li>
1332
            <p><code>array:put</code>: replaces the member at a given position.
1333
               For example, <code>array:put([4, 5, 6], 2, 8)</code> returns <code>[4, 8, 6]</code>.</p>
1334
         </li>
1335
         <li>
1336
            <p><code>array:remove</code>: removes the member at a given position.
1337
               For example, <code>array:remove([4, 5, 6], 2)</code> returns <code>[4, 6]</code>.</p>
1338
         </li>
1339
         <li>
1340
            <p><code>array:reverse</code>: reverses the order of members.
1341
               For example, <code>array:reverse([[1,2], [3,4]])</code> returns <code>[[3,4], [1,2]]</code>.</p>
1342
         </li>
1343
         <li>
1344
            <p><code>array:size</code>: returns the number of members in the array.
1345
               For example, <code>array:size([[1,2], [3,4]])</code> returns <code>2</code>.</p>
1346
         </li>
1347
         <li>
1348
            <p><code>array:sort</code>: sorts the members of an array, either by their own atomic value, or by the result of applying
1349
               a function to compute a sort key. A collation can also be specified.
1350
               For example, <code>array:sort([4, 8, 2])</code> returns <code>[2, 4, 8]</code>.</p>
1351
         </li>
1352
         <li>
1353
            <p><code>array:subarray</code>: returns members of the array starting at a specified position, either
1354
               to the end of the array or up to a specified length.
1355
               For example, <code>array:subarray([1, 2, 3, 4], 2)</code> returns <code>[2, 3, 4]</code>, 
1356
               while <code>array:subarray([1, 2, 3, 4], 2, 2)</code> returns <code>[2, 3]</code>.</p>
1357
         </li>
1358
         <li>
1359
            <p><code>array:tail</code>: removes the first member from an array.
1360
               For example, <code>array:head([1 to 5, 1 to 10]</code> returns <code>[1 to 10]</code>.</p>
1361
         </li>
1362

    
1363
      </ul>
1364
      
1365
      <h2>Arrays: Technical Implementation Details</h2>
1366
      
1367
      <p>Internally Saxon (from release 9.9) uses two implementations of arrays.</p>
1368
      
1369
      <p>The first implementation, <code>SimpleArrayItem</code>, is backed by a Java <code>ArrayList&lt;Sequence&gt;</code>.
1370
      An array constructor (either <code>[x,y,z]</code> or <code>array{a,b,c}</code>) will always deliver a <code>SimpleArrayItem</code>.
1371
      This is economical on storage and has good performance for accessing specific items by index position, or for scanning the entire
1372
      array. It is less well suited to incremental modification.</p>
1373
      <p>The other implementation, <code>PersistentArrayItem</code>, is backed by a persistent (immutable) list implemented as a tree
1374
      structure. This makes it possible to add, replace, or remove entries in constant time without copying the entire array.</p>
1375
      <p>The result of operations such as <code>array:put()</code>, <code>array:insert-before()</code>, and <code>array:remove()</code>
1376
      is always a <code>PersistentArrayItem</code>, even if the input is a <code>SimpleArrayItem</code>. Converting one to the other
1377
      takes time proportional to the size of the array.</p>
1378
      <p>The result of <code>array:filter()</code>, <code>array:for-each()</code>, <code>array:for-each-pair()</code>, and 
1379
      <code>array:reverse()</code> is always a <code>SimpleArrayItem</code>, even if the input is a <code>PersistentArrayItem</code>.
1380
      In cases where an array goes through a construction phase and is then used heavily for retrieval-only access, it might
1381
      be worth forcing it back to a <code>SimpleArrayItem</code> at the end of the construction phase: this can be achieved
1382
      by means of a call on <code>array:filter()</code> with a predicate that selects all members.</p>
1383
     
1384
   </section>
1385
</article>
(10-10/21)