com.saxonica.functions.map

## Class RangeKey

- java.lang.Object
- - com.saxonica.functions.map.RangeKey

- All Implemented Interfaces:
    MapItem, PullEvent, Callable, FunctionItem, GroundedValue, Item, Sequence

      public class RangeKey
      extends Object
      implements MapItem

  This class implements an XPath map item as a view of an XSLT key index. It is possible to specify a minimum and maximum key value to be included in the map, and keys are returned in sorted order.

  At present range keys are only available for string-valued keys using the Unicode codepoint collating sequence.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `RangeKey(String min, String max, TreeMap<String,List<NodeInfo>> index)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Sequence` | `call(XPathContext context, Sequence[] args)` Invoke the function
    `boolean` | `deepEquals(FunctionItem other, XPathContext context, AtomicComparer comparer, int flags)` Test whether this FunctionItem is deep-equal to another function item, under the rules of the deep-equal function
    `boolean` | `effectiveBooleanValue()` Get the effective boolean value of this sequence
    `Sequence` | `get(AtomicValue key, XPathContext context)` Get an entry from the Map
    `int` | `getArity()` Get the arity of the function
    `StringCollator` | `getCollation()` Get the collation of the map
    `String` | `getCollationName()` Get the name of the collation of the map
    `MapType` | `getFunctionItemType(TypeHierarchy th)` Get the item type of the function item
    `StructuredQName` | `getFunctionName()` Get the name of the function, or null if it is anonymous
    `AtomicType` | `getKeyType(TypeHierarchy th)` Get the lowest common item type of the keys in the map
    `int` | `getLength()` Get the size of the value (the number of items)
    `String` | `getStringValue()` Get the value of the item as a string.
    `CharSequence` | `getStringValueCS()` Get the string value of the item as a CharSequence.
    `SequenceType` | `getValueType(TypeHierarchy th)` Get the lowest common sequence type of all the values in the map
    `Item` | `head()` Get the first item in the sequence.
    `boolean` | `isEmpty()` Ask whether the map is empty
    `Item` | `itemAt(int n)` Get the n'th item in the value, counting from 0
    `SequenceIterator` | `iterate()` Get an iterator over all the items in the sequence
    `UnfailingIterator<StringValue>` | `keys()` Get the set of all key values in the map.
    `GroundedValue` | `reduce()` Reduce the sequence to its simplest form.
    `MapItem` | `remove(AtomicValue key, XPathContext context)` Remove an entry from the map
    `int` | `size()` Get the size of the map
    `GroundedValue` | `subsequence(int start, int length)` Get a subsequence of the value

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

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

- - ### Constructor Detail

    - #### RangeKey

          public RangeKey(String min,
                  String max,
                  TreeMap<String,List<NodeInfo>> index)
                   throws XPathException

      Throws:
        `XPathException`

  - ### Method Detail

    - #### getCollationName

          public String getCollationName()

      Get the name of the collation of the map
      Specified by:
        `getCollationName` in interface `MapItem`
      Returns:
        the collation name

    - #### getCollation

          public StringCollator getCollation()

      Get the collation of the map
      Specified by:
        `getCollation` in interface `MapItem`
      Returns:
        the collation of the map

    - #### get

          public Sequence get(AtomicValue key,
                     XPathContext context)
                       throws XPathException

      Get an entry from the Map
      Specified by:
        `get` in interface `MapItem`
      Parameters:
        `key` - the value of the key
        `context` - the XPath dynamic evaluation context
      Returns:
        the value associated with the given key, or null if the key is not present in the map
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### size

          public int size()

      Get the size of the map
      Specified by:
        `size` in interface `MapItem`
      Returns:
        the number of keys/entries present in this map

    - #### isEmpty

          public boolean isEmpty()

      Ask whether the map is empty
      Specified by:
        `isEmpty` in interface `MapItem`
      Returns:
        true if and only if the size of the map is zero

    - #### keys

          public UnfailingIterator<StringValue> keys()

      Get the set of all key values in the map.
      Specified by:
        `keys` in interface `MapItem`
      Returns:
        a set containing all the key values present in the map.

    - #### remove

          public MapItem remove(AtomicValue key,
                       XPathContext context)
                         throws XPathException

      Remove an entry from the map
      Specified by:
        `remove` in interface `MapItem`
      Parameters:
        `key` - the key of the entry to be removed
        `context` - the XPath dynamic context
      Returns:
        a new map in which the requested entry has been removed; or this map unchanged if the specified key was not present
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### getKeyType

          public AtomicType getKeyType(TypeHierarchy th)

      Get the lowest common item type of the keys in the map
      Specified by:
        `getKeyType` in interface `MapItem`
      Parameters:
        `th` - the type hierarchy
      Returns:
        the most specific type to which all the keys belong. If the map is empty, return AnyAtomicType by convention

    - #### getValueType

          public SequenceType getValueType(TypeHierarchy th)

      Get the lowest common sequence type of all the values in the map
      Specified by:
        `getValueType` in interface `MapItem`
      Parameters:
        `th` - the type hierarchy
      Returns:
        the most specific sequence type to which all the values belong. If the map is empty, return ANY_SEQUENCE by convention

    - #### getFunctionItemType

          public MapType getFunctionItemType(TypeHierarchy th)

      Get the item type of the function item
      Specified by:
        `getFunctionItemType` in interface `FunctionItem`
      Parameters:
        `th` - the type hierarchy cache
      Returns:
        the function item's type

    - #### getFunctionName

          public StructuredQName getFunctionName()

      Get the name of the function, or null if it is anonymous
      Specified by:
        `getFunctionName` in interface `FunctionItem`
      Returns:
        the function name, or null for an anonymous inline function

    - #### getArity

          public int getArity()

      Get the arity of the function
      Specified by:
        `getArity` in interface `FunctionItem`
      Returns:
        the number of arguments in the function signature

    - #### call

          public Sequence call(XPathContext context,
                      Sequence[] args)
                        throws XPathException

      Invoke the function
      Specified by:
        `call` in interface `Callable`
      Specified by:
        `call` in interface `FunctionItem`
      Parameters:
        `context` - the XPath dynamic evaluation context
        `args` - the actual arguments to be supplied
      Returns:
        the result of invoking the function
      Throws:
        `XPathException` - if a dynamic error occurs within the function

    - #### deepEquals

          public boolean deepEquals(FunctionItem other,
                           XPathContext context,
                           AtomicComparer comparer,
                           int flags)
                             throws XPathException

      Test whether this FunctionItem is deep-equal to another function item, under the rules of the deep-equal function
      Specified by:
        `deepEquals` in interface `FunctionItem`
      Parameters:
        `other` - the other function item
        `context` - the dynamic evaluation context
        `comparer` - the object to perform the comparison
        `flags` - options for how the comparison is performed
      Returns:
        true if the two function items are deep-equal
      Throws:
        `XPathException` - if the comparison cannot be performed

    - #### itemAt

          public Item itemAt(int n)

      Get the n'th item in the value, counting from 0
      Specified by:
        `itemAt` in interface `GroundedValue`
      Parameters:
        `n` - the index of the required item, with 0 representing the first item in the sequence
      Returns:
        the n'th item if it exists, or null otherwise

    - #### subsequence

          public GroundedValue subsequence(int start,
                                  int length)

      Get a subsequence of the value
      Specified by:
        `subsequence` in interface `GroundedValue`
      Parameters:
        `start` - the index of the first item to be included in the result, counting from zero. A negative value is taken as zero. If the value is beyond the end of the sequence, an empty sequence is returned
        `length` - the number of items to be included in the result. Specify Integer.MAX_VALUE to get the subsequence up to the end of the base sequence. If the value is negative, an empty sequence is returned. If the value goes off the end of the sequence, the result returns items up to the end of the sequence
      Returns:
        the required subsequence. If min is

    - #### getLength

          public int getLength()

      Get the size of the value (the number of items)
      Specified by:
        `getLength` in interface `GroundedValue`
      Returns:
        the number of items in the sequence

    - #### effectiveBooleanValue

          public boolean effectiveBooleanValue()
                                        throws XPathException

      Get the effective boolean value of this sequence
      Specified by:
        `effectiveBooleanValue` in interface `GroundedValue`
      Returns:
        the effective boolean value
      Throws:
        `XPathException` - if the sequence has no effective boolean value (for example a sequence of two integers)

    - #### reduce

          public GroundedValue reduce()

      Reduce the sequence to its simplest form. If the value is an empty sequence, the result will be EmptySequence.getInstance(). If the value is a single atomic value, the result will be an instance of AtomicValue. If the value is a single item of any other kind, the result will be an instance of SingletonItem. Otherwise, the result will typically be unchanged.
      Specified by:
        `reduce` in interface `GroundedValue`
      Returns:
        the simplified sequence

    - #### getStringValue

          public String getStringValue()

      Get the value of the item as a string. For nodes, this is the string value of the node as defined in the XPath 2.0 data model, except that all nodes are treated as being untyped: it is not an error to get the string value of a node with a complex type. For atomic values, the method returns the result of casting the atomic value to a string.

      If the calling code can handle any CharSequence, the method `getStringValueCS()` should be used. If the caller requires a string, this method is preferred.
      Specified by:
        `getStringValue` in interface `GroundedValue`
      Specified by:
        `getStringValue` in interface `Item`
      Returns:
        the string value of the item
      Throws:
        `UnsupportedOperationException` - if the item is a function item (an unchecked exception is used here to avoid introducing exception handling to a large number of paths where it is not needed)
      Since:
        8.4
      See Also:
        `getStringValueCS()`

    - #### getStringValueCS

          public CharSequence getStringValueCS()

      Get the string value of the item as a CharSequence. This is in some cases more efficient than the version of the method that returns a String. The method satisfies the rule that `X.getStringValueCS().toString()` returns a string that is equal to `X.getStringValue()`.

      Note that two CharSequence values of different types should not be compared using equals(), and for the same reason they should not be used as a key in a hash table.

      If the calling code can handle any CharSequence, this method should be used. If the caller requires a string, the `getStringValue()` method is preferred.
      Specified by:
        `getStringValueCS` in interface `GroundedValue`
      Specified by:
        `getStringValueCS` in interface `Item`
      Returns:
        the string value of the item
      Throws:
        `UnsupportedOperationException` - if the item is a function item (an unchecked exception is used here to avoid introducing exception handling to a large number of paths where it is not needed)
      Since:
        8.4
      See Also:
        `getStringValue()`

    - #### head

          public Item head()
                    throws XPathException

      Get the first item in the sequence.
      Specified by:
        `head` in interface `Sequence`
      Returns:
        the first item in the sequence if there is one, or null if the sequence is empty
      Throws:
        `XPathException` - in the situation where the sequence is evaluated lazily, and evaluation of the first item causes a dynamic error.

    - #### iterate

          public SequenceIterator iterate()
                                   throws XPathException

      Get an iterator over all the items in the sequence
      Specified by:
        `iterate` in interface `Sequence`
      Returns:
        an iterator over all the items
      Throws:
        `XPathException` - in the situation where the sequence is evaluated lazily, and constructing an iterator over the items causes a dynamic error.

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