net.sf.saxon.ma.map

Class RangeKey

java.lang.Object

net.sf.saxon.ma.map.RangeKey

All Implemented Interfaces:

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

public class RangeKey
extends java.lang.Object
implements MapItem

This class implements an XPath map item as a view of an XSLT key index. It is possible to specify a minimum and maximum key value to be included in the map, and keys are returned in sorted order.

At present range keys are only available for string-valued keys using the Unicode codepoint collating sequence.

Constructor Summary

Constructors

Constructor and Description
RangeKey(java.lang.String min, java.lang.String max, java.util.TreeMap<AtomicMatchKey,java.util.List<NodeInfo>> index)

Method Summary

Modifier and Type	Method and Description
MapItem	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
boolean	conforms(AtomicType keyType, SequenceType valueType, TypeHierarchy th) Ask whether the map conforms to a given map type
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
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.
MapType	getFunctionItemType() Get the item type of the 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
int	getLength() Get the size of the value (the number of items)
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.
Function	head() Get the first item in the sequence.
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
Function	itemAt(int n) Get the n'th item in the value, counting from 0
UnfailingIterator	iterate() Get an iterator over all the items in the sequence
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
GroundedValue	reduce() Reduce the sequence to its simplest form.
MapItem	remove(AtomicValue key) Remove an entry from the map
int	size() Get the size of the map
GroundedValue	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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

RangeKey

public RangeKey(java.lang.String min,
                java.lang.String max,
                java.util.TreeMap<AtomicMatchKey,java.util.List<NodeInfo>> index)
         throws XPathException

Throws:

XPathException

Method Detail

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

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

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

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

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

keys

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

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

remove

public MapItem 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

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)

addEntry

public MapItem 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

conforms

public boolean conforms(AtomicType keyType,
                        SequenceType valueType,
                        TypeHierarchy th)

Ask whether the map conforms to a given map type

Specified by:

conforms in interface MapItem

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

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.

Specified by:

getItemType in interface MapItem

Parameters:

th - the type hierarchy (not used)

Returns:

the type of this map

getFunctionItemType

public MapType getFunctionItemType()

Get the item type of the function item

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 a dynamic error occurs within the function

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 Function itemAt(int n)

Get the n'th item in the value, counting from 0

Specified by:

itemAt in interface GroundedValue

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 subsequence(int start,
                                 int length)

Get a subsequence of the value

Specified by:

subsequence in interface GroundedValue

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

getLength

public int getLength()

Get the size of the value (the number of items)

Specified by:

getLength in interface GroundedValue

Returns:

the number of items in the sequence

effectiveBooleanValue

public boolean effectiveBooleanValue()
                              throws XPathException

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)

reduce

public GroundedValue reduce()

Reduce the sequence to its simplest form. If the value is an empty sequence, the result will be EmptySequence.getInstance(). If the value is a single atomic value, the result will be an instance of AtomicValue. If the value is a single item of any other kind, the result will be an instance of SingletonItem. Otherwise, the result will typically be unchanged.

Specified by:

reduce in interface GroundedValue

Returns:

the simplified sequence

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

head

public Function head()

Get the first item in the sequence.

Specified by:

head in interface GroundedValue

Specified by:

head in interface Item

Specified by:

head in interface Sequence

Returns:

the first item in the sequence if there is one, or null if the sequence is empty

iterate

public UnfailingIterator iterate()

Get an iterator over all the items in the sequence

Specified by:

iterate in interface Function

Specified by:

iterate in interface GroundedValue

Specified by:

iterate in interface Sequence

Returns:

an iterator over all the items

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