net.sf.saxon.ma.map

Interface MapItem

All Superinterfaces:

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

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

Modifier and Type	Method and 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	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.Function

argumentArray

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

getLength, head, isStreamed, iterate, iterator, reduce, subsequence, toGroundedValue

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

asIterable, materialize

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

makeRepeatable

Methods inherited from interface java.lang.Iterable

forEach, spliterator

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

Specified by:

toShortString in interface Item<Function>

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

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

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

Specified by:

getStringValue in interface Item<Function>

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

Specified by:

getStringValueCS in interface Item<Function>

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

Specified by:

itemAt in interface Item<Function>

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

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