Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.saxonica.functions.map
Class ImmutableMap

    java.lang.Object
      com.saxonica.functions.map.ImmutableMap

All Implemented Interfaces:
  MapItem, PullEvent, FunctionItem<MapItem>, GroundedValue<MapItem>, Item<MapItem>, ValueRepresentation<MapItem>

    public class ImmutableMap

extends Object
implements MapItem, GroundedValue<MapItem>

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
`static SequenceType` | `SINGLE_MAP_TYPE`

Fields inherited from interface net.sf.saxon.om.ValueRepresentation
`EMPTY_VALUE_ARRAY`

Constructor Summary
`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
`ImmutableMap` | `copyPut(AtomicValue key, ValueRepresentation<? extends Item> value, XPathContext context)` Create a new map containing the existing entries in the map plus an additional entry, without modifying the original
`FunctionItem` | `curry(ValueRepresentation<? extends Item>[] value)` Curry a function by binding one or more (but not all) of its arguments
`boolean` | `deepEquals(FunctionItem other, XPathContext context, GenericAtomicComparer comparer, int flags)` Test whether this FunctionItem is deep-equal to another function item, under the rules of the deep-equal function
`ValueRepresentation<? extends Item>` | `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
`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.
`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, ValueRepresentation<? extends Item> value, XPathContext context)` Add a new entry to this map, modifying the original in place
`SequenceIterator<? extends Item>` | `invoke(SequenceIterator<? extends Item>[] args, XPathContext context)` Invoke the function
`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
`GroundedValue<MapItem>` | `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`

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

### getLength

    public int getLength()

  Get the size of the value (the number of items)

  Specified by:
    `getLength` in interface `GroundedValue<MapItem>`
  Returns:
    the number of items in the sequence

### 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,
                                ValueRepresentation<? extends Item> 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,
                          ValueRepresentation<? extends Item> 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 ValueRepresentation<? extends Item> 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<MapItem>`
  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<MapItem>`
  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<MapItem>`
  Returns:
    the number of arguments in the function signature

### invoke

    public SequenceIterator<? extends Item> invoke(SequenceIterator<? extends Item>[] args,
                                                   XPathContext context)
                                            throws XPathException

  Invoke the function

  Specified by:
    `invoke` in interface `FunctionItem<MapItem>`
  Parameters:
    `args` - the actual arguments to be supplied
    `context` - the XPath dynamic evaluation context
  Returns:
    the result of invoking the function
  Throws:
    `XPathException`

### curry

    public FunctionItem curry(ValueRepresentation<? extends Item>[] value)
                       throws XPathException

  Curry a function by binding one or more (but not all) of its arguments

  Specified by:
    `curry` in interface `FunctionItem<MapItem>`
  Parameters:
    `value` - the values to which the arguments are to be bound
  Returns:
    a new function item in which the specified arguments of the original function is bound to a value
  Throws:
    `XPathException` - if any 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 `Item<MapItem>`
  Specified by:
    `getStringValue` in interface `ValueRepresentation<MapItem>`
  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 `Item<MapItem>`
  Specified by:
    `getStringValueCS` in interface `ValueRepresentation<MapItem>`
  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.

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

  Specified by:
    `itemAt` in interface `GroundedValue<MapItem>`
  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<MapItem> subsequence(int start,
                                              int length)

  Description copied from interface: `GroundedValue`
  Get a subsequence of the value

  Specified by:
    `subsequence` in interface `GroundedValue<MapItem>`
  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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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