net.sf.saxon.ma.map

Class HashTrieMap

java.lang.Object

net.sf.saxon.om.AbstractItem

net.sf.saxon.ma.map.HashTrieMap

All Implemented Interfaces:

java.lang.Iterable<KeyValuePair>, Callable, MapItem, Function, GroundedValue, Item, Sequence

public class HashTrieMap
extends AbstractItem
implements MapItem, GroundedValue

An immutable map. This is the Saxon 9.6 implementation, which uses a hash trie

Field Summary

Fields

Modifier and Type	Field and Description
static SequenceType	SINGLE_MAP_TYPE

Constructor Summary

Constructors

Constructor and Description
HashTrieMap() Create an empty map
HashTrieMap(ImmutableMap<AtomicMatchKey,KeyValuePair> imap) Create a map whose contents are a copy of an existing immutable map

Method Summary

Modifier and Type	Method and Description
HashTrieMap	addEntry(AtomicValue key, Sequence value) Create a new map containing the existing entries in the map plus an additional entry, without modifying the original.
TupleItemType	asTupleType(TypeHierarchy th)
AtomicSequence	atomize() Atomize the item.
Sequence	call(XPathContext context, Sequence[] args) Invoke the function
boolean	conforms(AtomicType requiredKeyType, SequenceType requiredValueType, TypeHierarchy th) Ask whether the map conforms to a given map type
static HashTrieMap	copy(MapItem map) Create a map whose entries are copies of the entries in an existing MapItem
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
void	diagnosticDump()
boolean	effectiveBooleanValue() Get the effective boolean value of this sequence
void	export(ExpressionPresenter out) Output information about this function item to the diagnostic explain() output
Sequence	get(AtomicValue key) Get an entry from the Map
AnnotationList	getAnnotations() Get the function annotations (as defined in XQuery).
int	getArity() Get the arity of the function
java.lang.String	getDescription() Get a description of this function for use in error messages.
FunctionItemType	getFunctionItemType() 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
MapType	getItemType(TypeHierarchy th) Get the type of the map.
UType	getKeyUType() Get the lowest common item type of the keys in the map
KeyValuePair	getKeyValuePair(AtomicValue key) Get an key/value pair from the Map
OperandRole[]	getOperandRoles() Get the roles of the arguments, for the purposes of streaming
java.lang.String	getStringValue() Get the value of the item as a string.
java.lang.CharSequence	getStringValueCS() Get the string value of the item as a CharSequence.
SequenceIterator	getTypedValue() Get the typed value of the item.
boolean	initialPut(AtomicValue key, Sequence value) Add a new entry to this map.
boolean	isArray() Ask whether this function item is an array
boolean	isEmpty() Ask whether the map is empty
boolean	isMap() Ask whether this function item is a map
boolean	isTrustedResultType() Check that result type is of the trusted system functions to return a result of the correct type
MapItem	itemAt(int n) Get the n'th item in the value, counting from 0
java.util.Iterator<KeyValuePair>	iterator() Get the set of all key-value pairs in the map
AtomicIterator	keys() Get the set of all key values in the map
XPathContext	makeNewContext(XPathContext callingContext) Prepare an XPathContext object for evaluating the function
HashTrieMap	remove(AtomicValue key) Remove an entry from the map
static HashTrieMap	singleton(AtomicValue key, Sequence value, XPathContext context) Create a singleton map with a single key and value
int	size() Get the size of the map
java.lang.String	toString() Returns a string representation of the object.

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

getLength, head, isStreamed, iterate, reduce, subsequence

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.saxon.om.Function

iterate

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

head

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

getLength, head, reduce, subsequence

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

SINGLE_MAP_TYPE

public static final SequenceType SINGLE_MAP_TYPE

Constructor Detail

HashTrieMap

public HashTrieMap()

Create an empty map

HashTrieMap

public HashTrieMap(ImmutableMap<AtomicMatchKey,KeyValuePair> imap)

Create a map whose contents are a copy of an existing immutable map

Parameters:

imap - the map to be copied

Method Detail

singleton

public static HashTrieMap singleton(AtomicValue key,
                                    Sequence value,
                                    XPathContext context)
                             throws XPathException

Create a singleton map with a single key and value

Parameters:

key - the key value

value - the associated value

context - dynamic evaluation context. Gives access to type information.

Returns:

a singleton map

Throws:

XPathException - if map mixes timezoned and timezoneless values

copy

public static HashTrieMap copy(MapItem map)

Create a map whose entries are copies of the entries in an existing MapItem

Parameters:

map - the existing map to be copied

Returns:

the new map

isArray

public boolean isArray()

Ask whether this function item is an array

Specified by:

isArray in interface Function

Returns:

false (it is not an array)

isMap

public boolean isMap()

Ask whether this function item is a map

Specified by:

isMap in interface Function

Returns:

true (it is a map)

getAnnotations

public 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

public 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

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

conforms

public boolean conforms(AtomicType requiredKeyType,
                        SequenceType requiredValueType,
                        TypeHierarchy th)

Ask whether the map conforms to a given map type

Specified by:

conforms in interface MapItem

Parameters:

requiredKeyType - the required keyType

requiredValueType - the required valueType

th - the type hierarchy cache for the configuration

Returns:

true if the map conforms to the required type

getItemType

public MapType 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. This method has the side-effect of updating the internal type information held within the map.

Specified by:

getItemType in interface MapItem

Parameters:

th - The type hierarchy cache for the configuration

Returns:

the type of this map

getKeyUType

public UType getKeyUType()

Get the lowest common item type of the keys in the map

Specified by:

getKeyUType in interface MapItem

Returns:

the most specific type to which all the keys belong. If the map is empty, return UType.VOID (the type with no instances)

getOperandRoles

public 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

addEntry

public HashTrieMap addEntry(AtomicValue key,
                            Sequence 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.

Specified by:

addEntry in interface MapItem

Parameters:

key - the key of the new entry

value - the value associated with the new entry

Returns:

the new map containing the additional entry

initialPut

public boolean initialPut(AtomicValue key,
                          Sequence value)

Add a new entry to this map. Since the map is supposed to be immutable, this method must only be called while initially populating the map, and must not be called if anyone else might already be using the map.

Parameters:

key - the key of the new entry. Any existing entry with this key is replaced.

value - the value associated with the new entry

Returns:

true if an existing entry with the same key was replaced

remove

public HashTrieMap remove(AtomicValue key)

Remove an entry from the map

Specified by:

remove in interface MapItem

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

get

public Sequence get(AtomicValue key)

Get an entry from the Map

Specified by:

get in interface MapItem

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

getKeyValuePair

public KeyValuePair getKeyValuePair(AtomicValue key)

Get an key/value pair from the Map

Parameters:

key - the value of the key

Returns:

the key-value-pair associated with the given key, or null if the key is not present in the map

keys

public AtomicIterator keys()

Get the set of all key values in the map

Specified by:

keys in interface MapItem

Returns:

an iterator over the keys, in undefined order

iterator

public java.util.Iterator<KeyValuePair> iterator()

Get the set of all key-value pairs in the map

Specified by:

iterator in interface java.lang.Iterable<KeyValuePair>

Specified by:

iterator in interface MapItem

Returns:

an iterator over the key-value pairs

getFunctionItemType

public 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

public 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

public 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

public int getArity()

Get the arity of the function

Specified by:

getArity in interface Function

Returns:

the number of arguments in the function signature

makeNewContext

public XPathContext makeNewContext(XPathContext callingContext)

Prepare an XPathContext object for evaluating the function

Specified by:

makeNewContext in interface Function

Parameters:

callingContext - the XPathContext of the function calling expression

Returns:

a suitable context for evaluating the function (which may or may not be the same as the caller's context)

call

public 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

public 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

public 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

public 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

public 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

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)

asTupleType

public TupleItemType asTupleType(TypeHierarchy th)

toString

public java.lang.String toString()

Returns a string representation of the object.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the object.

export

public void export(ExpressionPresenter out)
            throws XPathException

Output information about this function item to the diagnostic explain() output

Specified by:

export in interface Function

Throws:

XPathException

isTrustedResultType

public 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

diagnosticDump

public void diagnosticDump()