Package net.sf.saxon.ma.map

## Interface MapItem

- All Superinterfaces:
    `Callable`, `Function`, `GroundedValue`, `Item`, `Sequence`
  All Known Implementing Classes:
    `DelegatingMapItem`, `DictionaryMap`, `HashTrieMap`, `PedigreeMapItem`, `RangeKey`, `SingleEntryMap`

      public interface MapItem
      extends Function

  Interface supported by different implementations of an XDM map item

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `MapItem` | `addEntry​(AtomicValue key, GroundedValue value)` | Create a new map containing the existing entries in the map plus an additional entry, without modifying the original.
    `default AtomicSequence` | `atomize()` | Atomize the item.
    `default Sequence` | `call​(XPathContext context, Sequence[] args)` | Invoke the function
    `boolean` | `conforms​(AtomicType keyType, SequenceType valueType, TypeHierarchy th)` | Ask whether the map conforms to a given map type
    `default boolean` | `deepEquals​(Function 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
    `default boolean` | `effectiveBooleanValue()` | Get the effective boolean value of this sequence
    `default void` | `export​(ExpressionPresenter out)` | Export information about this function item to the export() or explain() output
    `GroundedValue` | `get​(AtomicValue key)` | Get an entry from the Map
    `default AnnotationList` | `getAnnotations()` | Get the function annotations (as defined in XQuery).
    `default int` | `getArity()` | Get the arity of the function
    `default java.lang.String` | `getDescription()` | Get a description of this function for use in error messages.
    `default FunctionItemType` | `getFunctionItemType()` | Get the item type of this item as a function item.
    `default StructuredQName` | `getFunctionName()` | Get the name of the function, or null if it is anonymous
    `default Genre` | `getGenre()` | Get the genre of this item
    `ItemType` | `getItemType​(TypeHierarchy th)` | Get the type of the map.
    `static ItemType` | `getItemTypeOfSequence​(Sequence val)` | Get an item type to which all the values in a sequence are known to conform
    `UType` | `getKeyUType()` | Get the lowest common item type of the keys in the map
    `default OperandRole[]` | `getOperandRoles()` | Get the roles of the arguments, for the purposes of streaming
    `default java.lang.String` | `getStringValue()` | Get the value of the item as a string.
    `default java.lang.CharSequence` | `getStringValueCS()` | Get the string value of the item as a CharSequence.
    `default SequenceIterator` | `getTypedValue()` | Get the typed value of the item.
    `default boolean` | `isArray()` | Ask whether this function item is an array
    `boolean` | `isEmpty()` | Ask whether the map is empty
    `static boolean` | `isKnownToConform​(Sequence value, ItemType itemType)` | Ask whether all the items in a sequence are known to conform to a given item type
    `default boolean` | `isMap()` | Ask whether this function item is a map
    `default boolean` | `isTrustedResultType()` | Check that result type is of the trusted system functions to return a result of the correct type
    `default MapItem` | `itemAt​(int n)` | Get the n'th item in the value, counting from 0
    `AtomicIterator<? extends AtomicValue>` | `keys()` | Get the set of all key values in the map.
    `java.lang.Iterable<KeyValuePair>` | `keyValuePairs()` | Get the set of all key-value pairs in the map
    `default XPathContext` | `makeNewContext​(XPathContext callingContext, ContextOriginator originator)` | Prepare an XPathContext object for evaluating the function
    `static java.lang.String` | `mapToString​(MapItem map)` | Returns a string representation of the object.
    `MapItem` | `remove​(AtomicValue key)` | Remove an entry from the map
    `int` | `size()` | Get the size of the map
    `default java.lang.String` | `toShortString()` | Provide a short string showing the contents of the item, suitable for use in error messages

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

      `asIterable, concatenate, containsNode, materialize`

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

      `getLength, head, isStreamed, iterate, reduce, subsequence`

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

      `makeRepeatable`

- - ### Method Detail

    - #### get

          GroundedValue get​(AtomicValue key)

      Get an entry from the Map
      Parameters:
        `key` - the value of the key
      Returns:
        the value associated with the given key, or null if the key is not present in the map.

    - #### size

          int size()

      Get the size of the map
      Returns:
        the number of keys/entries present in this map

    - #### isEmpty

          boolean isEmpty()

      Ask whether the map is empty
      Returns:
        true if and only if the size of the map is zero

    - #### keys

          AtomicIterator<? extends AtomicValue> keys()

      Get the set of all key values in the map.
      Returns:
        a set containing all the key values present in the map, in unpredictable order

    - #### keyValuePairs

          java.lang.Iterable<KeyValuePair> keyValuePairs()

      Get the set of all key-value pairs in the map
      Returns:
        an iterable containing all the key-value pairs

    - #### addEntry

          MapItem addEntry​(AtomicValue key,
                           GroundedValue value)

      Create a new map containing the existing entries in the map plus an additional entry, without modifying the original. If there is already an entry with the specified key, this entry is replaced by the new entry.
      Parameters:
        `key` - the key of the new entry
        `value` - the value associated with the new entry
      Returns:
        the new map containing the additional entry

    - #### remove

          MapItem remove​(AtomicValue key)

      Remove an entry from the map
      Parameters:
        `key` - the key of the entry to be removed
      Returns:
        a new map in which the requested entry has been removed; or this map unchanged if the specified key was not present

    - #### conforms

          boolean conforms​(AtomicType keyType,
                           SequenceType valueType,
                           TypeHierarchy th)

      Ask whether the map conforms to a given map type
      Parameters:
        `keyType` - the required keyType
        `valueType` - the required valueType
        `th` - the type hierarchy cache for the configuration
      Returns:
        true if the map conforms to the required type

    - #### getItemType

          ItemType getItemType​(TypeHierarchy th)

      Get the type of the map. This method is used largely for diagnostics, to report the type of a map when it differs from the required type.
      Returns:
        the type of this map

    - #### getKeyUType

          UType getKeyUType()

      Get the lowest common item type of the keys in the map
      Returns:
        the most specific type to which all the keys belong. If the map is empty, return UType.VOID

    - #### toShortString

          default java.lang.String toShortString()

      Provide a short string showing the contents of the item, suitable for use in error messages
      Specified by:
        `toShortString` in interface `Function`
      Specified by:
        `toShortString` in interface `GroundedValue`
      Specified by:
        `toShortString` in interface `Item`
      Returns:
        a depiction of the item suitable for use in error messages

    - #### getGenre

          default Genre getGenre()

      Get the genre of this item
      Specified by:
        `getGenre` in interface `Function`
      Specified by:
        `getGenre` in interface `Item`
      Returns:
        the genre: specifically, Map.

    - #### isArray

          default boolean isArray()

      Ask whether this function item is an array
      Specified by:
        `isArray` in interface `Function`
      Returns:
        false (it is not an array)

    - #### isMap

          default boolean isMap()

      Ask whether this function item is a map
      Specified by:
        `isMap` in interface `Function`
      Returns:
        true (it is a map)

    - #### getAnnotations

          default AnnotationList getAnnotations()

      Get the function annotations (as defined in XQuery). Returns an empty list if there are no function annotations.
      Specified by:
        `getAnnotations` in interface `Function`
      Returns:
        the function annotations

    - #### atomize

          default AtomicSequence atomize()
                                  throws XPathException

      Atomize the item.
      Specified by:
        `atomize` in interface `Item`
      Returns:
        the result of atomization
      Throws:
        `XPathException` - if atomization is not allowed for this kind of item

    - #### isKnownToConform

          static boolean isKnownToConform​(Sequence value,
                                          ItemType itemType)

      Ask whether all the items in a sequence are known to conform to a given item type
      Parameters:
        `value` - the sequence
        `itemType` - the given item type
      Returns:
        true if all the items conform; false if not, or if the information cannot be efficiently determined

    - #### getItemTypeOfSequence

          static ItemType getItemTypeOfSequence​(Sequence val)

      Get an item type to which all the values in a sequence are known to conform
      Parameters:
        `val` - the sequence
      Returns:
        the type of the first item in the sequence, provided that all subsequent values in the sequence are known to conform to this type; otherwise item().

    - #### getOperandRoles

          default OperandRole[] getOperandRoles()

      Get the roles of the arguments, for the purposes of streaming
      Specified by:
        `getOperandRoles` in interface `Function`
      Returns:
        an array of OperandRole objects, one for each argument

    - #### getFunctionItemType

          default FunctionItemType getFunctionItemType()

      Get the item type of this item as a function item. Note that this returns the generic function type for maps, not a type related to this specific map.
      Specified by:
        `getFunctionItemType` in interface `Function`
      Returns:
        the function item's type

    - #### getFunctionName

          default StructuredQName getFunctionName()

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

    - #### getDescription

          default java.lang.String getDescription()

      Get a description of this function for use in error messages. For named functions, the description is the function name (as a lexical QName). For others, it might be, for example, "inline function", or "partially-applied ends-with function".
      Specified by:
        `getDescription` in interface `Function`
      Returns:
        a description of the function for use in error messages

    - #### getArity

          default int getArity()

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

    - #### makeNewContext

          default XPathContext makeNewContext​(XPathContext callingContext,
                                              ContextOriginator originator)

      Prepare an XPathContext object for evaluating the function
      Specified by:
        `makeNewContext` in interface `Function`
      Parameters:
        `callingContext` - the XPathContext of the function calling expression
        `originator` -
      Returns:
        a suitable context for evaluating the function (which may or may not be the same as the caller's context)

    - #### call

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

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

    - #### getStringValue

          default java.lang.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:
        `java.lang.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

          default java.lang.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:
        `java.lang.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

          default SequenceIterator 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

          default boolean deepEquals​(Function 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 `Function`
      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

          default MapItem itemAt​(int n)

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

          default 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)

    - #### mapToString

          static java.lang.String mapToString​(MapItem map)

      Returns a string representation of the object.
      Returns:
        a string representation of the object.

    - #### export

          default void export​(ExpressionPresenter out)
                       throws XPathException

      Export information about this function item to the export() or explain() output
      Specified by:
        `export` in interface `Function`
      Throws:
        `XPathException`

    - #### isTrustedResultType

          default boolean isTrustedResultType()

      Description copied from interface: `Function`
      Check that result type is of the trusted system functions to return a result of the correct type
      Specified by:
        `isTrustedResultType` in interface `Function`