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

See Also

months-from-duration
on page 834

zero-or-one

The
zero-or-one()
function returns its argument unchanged, provided that it is a sequence containing no more than one item. In other cases, it reports an error.

Signature

Effect

The
zero-or-one()
function returns its argument unchanged, provided that it is a sequence containing no more than one item. In other cases, 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 that is either empty, or contains exactly one item. This allows the expression to be used in contexts that require an optional single value (for example, the argument of a function such as
root()
) 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 a single item will be done at runtime, just as it would with a processor that does not enforce static type checking.

Examples

Assume the source document:

with a schema that defines the colors attribute with type
xs:NMTOKENS
(that is, it allows a list of colors to be specified, but our sample document only specifies one).

Usage

This function is never needed unless you are using a processor that does static type checking.

However, you may still find it useful as a way of inserting runtime checks into your XPath expressions, and documenting the assumptions you are making about the input data.

See Also

exactly-one()
on page 777

one-or-more()
on page 853

Summary

Much of the power of any programming language comes from its function library, which is why this chapter explaining the function library is one of the longest in the book. The size of the function library has grown greatly since XSLT and XPath 1.0, largely because of the richer set of types supported.

The next chapter defines the syntax of the regular expressions accepted by the three functions
matches()
,
replace()
, and
tokenize()
, and by the XSLT instruction

.

Chapter 14

Regular Expressions

This chapter defines the regular expression syntax accepted by the XPath functions
matches()
,
replace()
, and
tokenize()
, which were described in the previous chapter, as well as the

instruction described in Chapter 6.

This regular expression syntax is based on the definition in XML Schema, which in turn is based on the definition in the Perl language, which is generally taken as the definitive reference for regular expressions. However, all dialects of regular expression syntax have minor variations. Within Perl itself there are features that are deprecated, there are features that differ between Perl versions, and there are features that don't apply when all characters are Unicode.

XML Schema defines a subset of the Perl regular expression syntax; it chose this subset based on the requirements of a language that only does validation (that is, testing whether or not a string matches the pattern) and that only deals with Unicode strings. The requirements of the
matches()
function in XPath are similar, but XPath also uses regular expressions for tokenizing strings and for replacing substrings. These are more complex requirements, so some of Perl's regular expression constructs that XML Schema left out have been added back in for XPath.

In the grammar productions in this chapter, as elsewhere in the book, I generally enclose characters of the target language (that is, the regex language) in chevrons, for example
|
. I have avoided using the more concise notation
[abcd]
because I think it is confusing to use regular expressions when defining regular expressions. If a character is not enclosed in chevrons, then it is either the name of another non-terminal symbol in the grammar, or a symbol that has a special meaning in the grammar.

The description of the syntax of regular expressions closely follows the description given in the XML Schema Recommendation. You can find this in Appendix F of Schema Part 2. The second edition corrects numerous errors in the original. The latest version of the Recommendation can be found at
http://www.w3.org/TR/xmlschema-2
.

Remember that the syntax rules given here apply to the regular expression after it has been preprocessed by the host language.

• If a regular expression is used within an XML document (for example, an XSLT stylesheet), then special characters such as
  &
  must be escaped using XML entity or character references such as
  &
  . If it appears within an XSLT attribute value template (for example, in the
  regex
  attribute of
  
  ), then curly braces must be doubled. If it appears within an XPath string literal, then any apostrophe or quotation mark that matches the string delimiters must be doubled.
  
• On the other hand, if your XPath expression is written as a string literal within a host language such as Java or C#, then a backslash will need to be written as
  \\
  (which means that a regular expression to match a single backslash character becomes
  \\\\
  ).