com.saxonica.functions.map

## Class SingletonMap

- java.lang.Object
- - net.sf.saxon.om.AbstractItem
  - - com.saxonica.functions.map.SingletonMap

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

      public class SingletonMap
      extends AbstractItem
      implements MapItem, GroundedValue

  A map containing a single entry

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SingletonMap(AtomicValue key, Sequence value)` Construct the singleton map

  - ### 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
    `FunctionItemType` | `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
    `String` | `getStringValue()` Get the value of the item as a string.
    `CharSequence` | `getStringValueCS()` Get the string value of the item as a CharSequence.
    `SequenceIterator<? extends AtomicValue>` | `getTypedValue()` Get the typed value of the item.
    `SequenceType` | `getValueType(TypeHierarchy th)` Get the lowest common sequence type of all the values in the map
    `boolean` | `isEmpty()` Ask whether the map is empty
    `MapItem` | `itemAt(int n)` Get the n'th item in the value, counting from 0
    `UnfailingIterator<AtomicValue>` | `keys()` Get the set of all key values in the map.
    `MapItem` | `remove(AtomicValue key, XPathContext context)` Remove an entry from the map
    `void` | `setCollation(String collationName, StringCollator collation)` Set the collation of the map
    `int` | `size()` Get the size of the map

    - ### Methods inherited from class net.sf.saxon.om.AbstractItem

      `getLength, head, iterate, reduce, subsequence`

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

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

    - ### Methods inherited from interface net.sf.saxon.om.GroundedValue

      `getLength, reduce, subsequence`

    - ### Methods inherited from interface net.sf.saxon.om.Sequence

      `head, iterate`

- - ### Constructor Detail

    - #### SingletonMap

          public SingletonMap(AtomicValue key,
                      Sequence value)

      Construct the singleton map
      Parameters:
        `key` - the key
        `value` - the value

  - ### Method Detail

    - #### setCollation

          public void setCollation(String collationName,
                          StringCollator collation)

      Set the collation of the map
      Parameters:
        `collationName` - the name of the collation to be used by this map
        `collation` - the corresponding collation object

    - #### getCollation

          public StringCollator getCollation()

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

    - #### getCollationName

          public String getCollationName()

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

    - #### get

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

      Get an entry from the Map. Return null if there is no matching entry.
      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

    - #### 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

    - #### size

          public int size()

      Get the size of the map
      Specified by:
        `size` in interface `MapItem`
      Returns:
        the number of entries in the map (always one for this implementation)

    - #### 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<AtomicValue> 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.

    - #### 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 FunctionItemType getFunctionItemType(TypeHierarchy th)

      Get the item type of the function item
      Specified by:
        `getFunctionItemType` in interface `FunctionItem`
      Parameters:
        `th` - the type hierarchy cache. If null is supplied, the resulting item type may be less precise.
      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

    - #### 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()`

    - #### getTypedValue

          public SequenceIterator<? extends AtomicValue> getTypedValue()
                                                                throws XPathException

      Get the typed value of the item.

      For a node, this is the typed value as defined in the XPath 2.0 data model. Since a node may have a list-valued data type, the typed value is in general a sequence, and it is returned in the form of a SequenceIterator.

      If the node has not been validated against a schema, the typed value will be the same as the string value, either as an instance of xs:string or as an instance of xs:untypedAtomic, depending on the node kind.

      For an atomic value, this method returns an iterator over a singleton sequence containing the atomic value itself.
      Returns:
        an iterator over the items in the typed value of the node or atomic value. The items returned by this iterator will always be atomic values.
      Throws:
        `XPathException` - where no typed value is available, for example in the case of an element with complex content
      Since:
        8.4

    - #### 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 MapItem itemAt(int n)

      Description copied from class: `AbstractItem`
      Get the n'th item in the value, counting from 0
      Specified by:
        `itemAt` in interface `GroundedValue`
      Overrides:
        `itemAt` in class `AbstractItem`
      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

    - #### effectiveBooleanValue

          public boolean effectiveBooleanValue()
                                        throws XPathException

      Description copied from interface: `GroundedValue`
      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)

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