com.saxonica.functions.map
Class ImmutableMap

java.lang.Object
  extended by 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


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