net.sf.saxon.ma.map

Class HashTrieMap

java.lang.Object

net.sf.saxon.om.AbstractItem

net.sf.saxon.ma.map.HashTrieMap

All Implemented Interfaces:

Iterable<KeyValuePair>, PullEvent, 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(ImmutableMap<AtomicMatchKey,KeyValuePair> imap, XPathContext context) Create a map whose contents are a copy of an existing immutable map
HashTrieMap(XPathContext context) Create an empty map

Method Summary

Methods

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.
AtomicSequence	atomize() Atomize the item.
Sequence	call(XPathContext context, Sequence[] args) Invoke the function
static HashTrieMap	copy(MapItem map, XPathContext context) 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
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
int	getArity() Get the arity of the function
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
AtomicType	getKeyType() Get the lowest common item type of the keys in 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
String	getStringValue() Get the value of the item as a string.
CharSequence	getStringValueCS() Get the string value of the item as a CharSequence.
SequenceIterator	getTypedValue() Get the typed value of the item.
SequenceType	getValueType() Get the lowest common sequence type of all the values in the map
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
MapItem	itemAt(int n) Get the n'th item in the value, counting from 0
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
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

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

Field Detail

SINGLE_MAP_TYPE

public static final SequenceType SINGLE_MAP_TYPE

Constructor Detail

HashTrieMap

public HashTrieMap(XPathContext context)

Create an empty map

Parameters:

context - The XPath dynamic context. Gives access to type information.

HashTrieMap

public HashTrieMap(ImmutableMap<AtomicMatchKey,KeyValuePair> imap,
           XPathContext context)
            throws NoDynamicContextException

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

Parameters:

imap - the map to be copied

context - The XPath dynamic context. Used to define the implicit timezone for comparing keys in this map, and also gives access to type information.

Throws:

NoDynamicContextException - if the supplied context has no implicit timezone available

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,
               XPathContext context)
                        throws XPathException

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

Parameters:

map - the existing map to be copied

context - the XPath dynamic context

Returns:

the new map

Throws:

XPathException - if a dynamic error occurs

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)

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

getKeyType

public AtomicType getKeyType()

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

Specified by:

getKeyType in interface MapItem

Returns:

the most specific type to which all the keys belong. If the map is empty, return AnyAtomicType by convention

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 ErrorType.getInstance() (the type with no instances)

getValueType

public SequenceType getValueType()

Get the lowest common sequence type of all the values in the map

Specified by:

getValueType in interface MapItem

Returns:

the most specific sequence type to which all the values belong. If the map is empty, return SequenceType.VOID

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)
                     throws XPathException

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

Throws:

XPathException - if adding the entry violates the rule against mixing keys with timezones and keys with no timezone

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)
                   throws XPathException

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

Throws:

XPathException - if a dynamic error occurs

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 Iterator<KeyValuePair> iterator()

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

Specified by:

iterator in interface 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 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

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

export

public void export(ExpressionPresenter out)

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

Specified by:

export in interface Function