com.saxonica.functions.map

## Class ImmutableMap

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

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

      public class ImmutableMap
      extends AbstractItem
      implements MapItem, GroundedValue

  An immutable map. The put() operation which adds or clears an entry has the effect of creating a new map that is conceptually a modified copy of the old map; in fact the implementation is designed to share storage as far as possible.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static SequenceType` | `SINGLE_MAP_TYPE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ImmutableMap()` Create an empty map
    `ImmutableMap(MapItem map, StringCollator collation, XPathContext context)` Create an ImmutableMap whose entries are copies of the entries in an existing MapItem, and whose collation is as supplied

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Sequence` | `call(XPathContext context, Sequence[] args)` Invoke the function
    `ImmutableMap` | `copyPut(AtomicValue key, Sequence value, XPathContext context)` Create a new map containing the existing entries in the map plus an additional entry, without modifying the original
    `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 used for the map
    `String` | `getCollationName()` Get the name of the collation of the map
    `FunctionItemType` | `getFunctionItemType(TypeHierarchy th)` Get the item type of this item as a 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
    `com.saxonica.functions.map.KeyValuePair` | `getKeyValuePair(AtomicValue key, XPathContext context)` Get an entry from 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<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
    `void` | `inSituPut(AtomicValue key, Sequence value, XPathContext context)` Add a new entry to this map, modifying the original in place
    `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 name, StringCollator collation)` Set the collation to be used for 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`

- - ### Field Detail

    - #### SINGLE_MAP_TYPE

          public static final SequenceType SINGLE_MAP_TYPE

  - ### Constructor Detail

    - #### ImmutableMap

          public ImmutableMap()

      Create an empty map

    - #### ImmutableMap

          public ImmutableMap(MapItem map,
                      StringCollator collation,
                      XPathContext context)
                       throws XPathException

      Create an ImmutableMap whose entries are copies of the entries in an existing MapItem, and whose collation is as supplied
      Parameters:
        `map` - the existing map to be copied
        `collation` - the collation
        `context` - the XPath dynamic context
      Throws:
        `XPathException` - if a dynamic error occurs

  - ### Method Detail

    - #### setCollation

          public void setCollation(String name,
                          StringCollator collation)

      Set the collation to be used for the map
      Parameters:
        `name` - the name of the collation to be used
        `collation` - the corresponding collation object

    - #### getCollation

          public StringCollator getCollation()

      Get the collation used for 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

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

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

    - #### copyPut

          public ImmutableMap copyPut(AtomicValue key,
                             Sequence value,
                             XPathContext context)
                               throws XPathException

      Create a new map containing the existing entries in the map plus an additional entry, without modifying the original
      Parameters:
        `key` - the key of the new entry
        `value` - the value associated with the new entry
        `context` - the XPath dynamic context
      Returns:
        the new map containing the additional entry
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### inSituPut

          public void inSituPut(AtomicValue key,
                       Sequence value,
                       XPathContext context)
                         throws XPathException

      Add a new entry to this map, modifying the original in place
      Parameters:
        `key` - the key of the new entry
        `value` - the value associated with the new entry
        `context` - the XPath dynamic context
      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

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

    - #### getKeyValuePair

          public com.saxonica.functions.map.KeyValuePair getKeyValuePair(AtomicValue key,
                                                                XPathContext context)
                                                                  throws XPathException

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

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

    - #### getFunctionItemType

          public FunctionItemType getFunctionItemType(TypeHierarchy th)

      Get the item type of this item as a function item
      Specified by:
        `getFunctionItemType` in interface `FunctionItem`
      Parameters:
        `th` - the type heirarchy 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`

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