Interface MapItem
-
- All Superinterfaces:
Callable,Function,GroundedValue,Item,Sequence
- 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
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description MapItemaddEntry(AtomicValue key, GroundedValue value)Create a new map containing the existing entries in the map plus an additional entry, without modifying the original.default AtomicSequenceatomize()Atomize the item.default Sequencecall(XPathContext context, Sequence[] args)Invoke the functionbooleanconforms(AtomicType keyType, SequenceType valueType, TypeHierarchy th)Ask whether the map conforms to a given map typedefault booleandeepEquals(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 functiondefault booleaneffectiveBooleanValue()Get the effective boolean value of this sequencedefault voidexport(ExpressionPresenter out)Export information about this function item to the export() or explain() outputGroundedValueget(AtomicValue key)Get an entry from the Mapdefault AnnotationListgetAnnotations()Get the function annotations (as defined in XQuery).default intgetArity()Get the arity of the functiondefault java.lang.StringgetDescription()Get a description of this function for use in error messages.default FunctionItemTypegetFunctionItemType()Get the item type of this item as a function item.default StructuredQNamegetFunctionName()Get the name of the function, or null if it is anonymousdefault GenregetGenre()Get the genre of this itemItemTypegetItemType(TypeHierarchy th)Get the type of the map.static ItemTypegetItemTypeOfSequence(Sequence val)Get an item type to which all the values in a sequence are known to conformUTypegetKeyUType()Get the lowest common item type of the keys in the mapdefault OperandRole[]getOperandRoles()Get the roles of the arguments, for the purposes of streamingdefault java.lang.StringgetStringValue()Get the value of the item as a string.default java.lang.CharSequencegetStringValueCS()Get the string value of the item as a CharSequence.default SequenceIteratorgetTypedValue()Get the typed value of the item.default booleanisArray()Ask whether this function item is an arraybooleanisEmpty()Ask whether the map is emptystatic booleanisKnownToConform(Sequence value, ItemType itemType)Ask whether all the items in a sequence are known to conform to a given item typedefault booleanisMap()Ask whether this function item is a mapdefault booleanisTrustedResultType()Check that result type is of the trusted system functions to return a result of the correct typedefault MapItemitemAt(int n)Get the n'th item in the value, counting from 0AtomicIterator<? extends AtomicValue>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 mapdefault XPathContextmakeNewContext(XPathContext callingContext, ContextOriginator originator)Prepare an XPathContext object for evaluating the functionstatic java.lang.StringmapToString(MapItem map)Returns a string representation of the object.MapItemremove(AtomicValue key)Remove an entry from the mapintsize()Get the size of the mapdefault java.lang.StringtoShortString()Provide a short string showing the contents of the item, suitable for use in error messages-
Methods inherited from interface net.sf.saxon.om.GroundedValue
asIterable, concatenate, containsNode, materialize
-
Methods inherited from interface net.sf.saxon.om.Item
getLength, head, isStreamed, iterate, reduce, subsequence
-
Methods inherited from interface net.sf.saxon.om.Sequence
makeRepeatable
-
-
-
-
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<? extends AtomicValue> 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 entryvalue- 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 keyTypevalueType- the required valueTypeth- 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:
toShortStringin interfaceFunction- Specified by:
toShortStringin interfaceGroundedValue- Specified by:
toShortStringin interfaceItem- Returns:
- a depiction of the item suitable for use in error messages
-
getGenre
default Genre getGenre()
Get the genre of this item
-
isArray
default boolean isArray()
Ask whether this function item is an array
-
isMap
default boolean isMap()
Ask whether this function item 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:
getAnnotationsin interfaceFunction- Returns:
- the function annotations
-
atomize
default AtomicSequence atomize() throws XPathException
Atomize the item.- Specified by:
atomizein interfaceItem- 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 sequenceitemType- 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:
getOperandRolesin interfaceFunction- 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:
getFunctionItemTypein interfaceFunction- Returns:
- the function item's type
-
getFunctionName
default StructuredQName getFunctionName()
Get the name of the function, or null if it is anonymous- Specified by:
getFunctionNamein interfaceFunction- 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:
getDescriptionin interfaceFunction- Returns:
- a description of the function for use in error messages
-
getArity
default int getArity()
Get the arity of the function
-
makeNewContext
default XPathContext makeNewContext(XPathContext callingContext, ContextOriginator originator)
Prepare an XPathContext object for evaluating the function- Specified by:
makeNewContextin interfaceFunction- Parameters:
callingContext- the XPathContext of the function calling expressionoriginator-- 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:
callin interfaceCallable- Specified by:
callin interfaceFunction- Parameters:
context- the XPath dynamic evaluation contextargs- 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:
getStringValuein interfaceGroundedValue- Specified by:
getStringValuein interfaceItem- 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 thatX.getStringValueCS().toString()returns a string that is equal toX.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:
getStringValueCSin interfaceGroundedValue- Specified by:
getStringValueCSin interfaceItem- 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:
deepEqualsin interfaceFunction- Parameters:
other- the other function itemcontext- the dynamic evaluation contextcomparer- the object to perform the comparisonflags- 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:ItemGet the n'th item in the value, counting from 0- Specified by:
itemAtin interfaceGroundedValue- Specified by:
itemAtin interfaceItem- 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 XPathExceptionDescription copied from interface:GroundedValueGet the effective boolean value of this sequence- Specified by:
effectiveBooleanValuein interfaceGroundedValue- 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:
exportin interfaceFunction- Throws:
XPathException
-
isTrustedResultType
default boolean isTrustedResultType()
Description copied from interface:FunctionCheck that result type is of the trusted system functions to return a result of the correct type- Specified by:
isTrustedResultTypein interfaceFunction
-
-