com.saxonica.expr

## Class MultiIndex

- java.lang.Object
- - com.saxonica.expr.MultiIndex

-     public class MultiIndex
      extends Object

  A MultiIndex provides fast access to the items in a sequence. The sequence is referred to as the "population", and may consist of nodes and/or atomic values. The items are identified by means of a key value computed using an expression called the "use" expression. This may be multivalued: each item in the result of the use expression is regarded as a separate key, and a match occurs if any of the items is matched.

  A MultiIndex handles a single "use" expression, for a single population.

  The class is used to support a variety of indexes: indexes to support the saxon:index() and saxon:find extension functions; and indexes over the value of a variable, as determined by the Saxon-EE optimizer.

  The class supports two kinds of equality matching. In ConvertUntypedToOther mode, corresponding to the XPath "=" operator, an untyped value is converted to the type of the other item, so the double 5e0 will match the untypedAtomic value "5". In ConvertUntypedToString mode, untyped atomic values are always converted to strings: this corresponds to the XPath "eq" operator (and to the rules for xsl:key).

  Each MultiIndex index is in fact a set of sub-indexes, one for each primitive type encountered. In an expression such as $seq[./A = $B], one sub-index is built for each primitive type that occurs in the sequence $B. In this index, any untyped atomic values in ./A are converted to that primitive type. For an expression such as $seq[./A eq $B], a single index is built, in which untyped atomic values in ./A are converted to strings.

  A particular difficulty arises where $B (in the expression $seq[./A eq $B]) is untypedAtomic. In this situation an index is built in which any untypedAtomic values in ./A are indexed as strings. While building the index, we note all the primitive types that occur in ./A, and then we convert the search term $B to each of these types in turn before doing the index lookup. In practice, of course, it is very rare for the index to be heterogeneous.

  This class was previously IndexedClosure, and inherited from MemoClosure, so that the contents of the sequence were built lazily. In most cases, however, an index will be built as soon as the variable is used, so there is no benefit in delaying matters. Making the class a Value in its own right means that the class can be used in both compiled and interpreted scenarios.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `MultiIndex(GroundedValue indexedValue)` Create a MultiIndex

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `SequenceIterator` | `findItems(Expression use, SequenceIterator values, boolean convertUntypedToOther, boolean firstOnly, AtomicComparer comparer, XPathContext context)` Retrieve items that match a given index value

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### MultiIndex

          public MultiIndex(GroundedValue indexedValue)

      Create a MultiIndex
      Parameters:
        `indexedValue` - the sequence to be indexed

  - ### Method Detail

    - #### findItems

          public SequenceIterator findItems(Expression use,
                                   SequenceIterator values,
                                   boolean convertUntypedToOther,
                                   boolean firstOnly,
                                   AtomicComparer comparer,
                                   XPathContext context)
                                     throws XPathException

      Retrieve items that match a given index value
      Parameters:
        `use` - the expression whose value is to be matched
        `values` - the set of values to be found
        `convertUntypedToOther` - true if untypedAtomic values are to be converted to the type of the other operand
        `firstOnly` - true if only the first matching value is needed
        `comparer` - AtomicComparer used to compare values for equality (encapsulates a collation if necessary)
        `context` - the dynamic evaluation context
      Returns:
        an iterator over the items that match the specified values
      Throws:
        `XPathException` - if a failure occurs

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.