A value is the result of an expression but it is also an expression in its own right.
Note that every value can be regarded as a sequence - in many cases, a sequence of
length one.
asItem
public Item asItem()
throws XPathException
Return the value in the form of an Item
- the value in the form of an Item
asItem
public static Item asItem(ValueRepresentation value)
throws XPathException
Static method to make an Item from a Value
value
- the value to be converted
- null if the value is an empty sequence; or the only item in the value
if it is a singleton sequence
asIterator
public static SequenceIterator asIterator(ValueRepresentation val)
throws XPathException
Static method to get an Iterator over any ValueRepresentation (which may be either a Value
or a NodeInfo
val
- The supplied value, or null, indicating the empty sequence.
- The supplied value, if it is a value, or a SingletonNode that
wraps the item, if it is a node. If the supplied value was null,
return an EmptySequence
asValue
public static Value asValue(ValueRepresentation val)
Static method to make a Value from a given Item (which may be either an AtomicValue
or a NodeInfo
val
- The supplied value, or null, indicating the empty sequence.
- The supplied value, if it is a value, or a SingletonNode that
wraps the item, if it is a node. If the supplied value was null,
return an EmptySequence
checkPermittedContents
public void checkPermittedContents(SchemaType parentType,
StaticContext env,
boolean whole)
throws XPathException
Check statically that the results of the expression are capable of constructing the content
of a given schema type.
parentType
- The schema typeenv
- the static contextwhole
- true if this value accounts for the entire content of the containing node
XPathException
- if the expression doesn't match the required content type
convertJavaObjectToXPath
public static Value convertJavaObjectToXPath(Object object,
SequenceType requiredType,
XPathContext context)
throws XPathException
Convert a Java object to an XPath value. This method is called to handle the result
of an external function call, and also to process global parameters passed to the stylesheet or query.
object
- The Java object to be convertedrequiredType
- The required type of the result (if known)context
- The XPath dynamic context
- the result of converting the value. If the value is null, returns null.
convertToJava
public Object convertToJava(Class target,
XPathContext context)
throws XPathException
Convert to Java object (for passing to external functions)
target
- the required target classcontext
- the XPath dynamic evaluation context
- the (boxed) Java object that best represents the XPath value
convertToJava
public static Object convertToJava(Item item)
throws XPathException
Convert an XPath value to a Java object.
An atomic value is returned as an instance
of the best available Java class. If the item is a node, the node is "unwrapped",
to return the underlying node in the original model (which might be, for example,
a DOM or JDOM node).
item
- the item to be converted
- the value after conversion
effectiveBooleanValue
public boolean effectiveBooleanValue()
throws XPathException
Get the effective boolean value of the expression. This returns false if the value
is the empty sequence, a zero-length string, a number equal to zero, or the boolean
false. Otherwise it returns true.
- the effective boolean value
XPathException
- if any dynamic error occurs evaluating the
expression
equals
public boolean equals(Object obj)
Compare two (sequence) values for equality. This method implements the XPath eq operator, for cases
where it is defined. For values containing nodes, nodes are compared for identity.
In cases where eq is not defined, it throws ClassCastException. In cases
where the result of eq is an empty sequence, this function returns false, except that two empty
sequences compare equal. The method also returns a ClassCastException
if any failure occurs evaluating either of the values.
fromItem
public static Value fromItem(Item item)
Static method to get a Value from an Item
- the item expressed as a Value
getCanonicalLexicalRepresentation
public CharSequence getCanonicalLexicalRepresentation()
Get the canonical lexical representation as defined in XML Schema. This is not always the same
as the result of casting to a string according to the XPath rules.
- the canonical lexical representation if defined in XML Schema; otherwise, the result
of casting to string according to the XPath 2.0 rules
getCardinality
public int getCardinality()
Determine the cardinality
getItemType
public ItemType getItemType(TypeHierarchy th)
Determine the data type of the items in the expression, if possible
th
- The TypeHierarchy. Can be null if the target is an AtomicValue.
- for the default implementation: AnyItemType (not known)
getLength
public int getLength()
throws XPathException
Get the length of the sequence
- the number of items in the sequence
getSchemaComparable
public Comparable getSchemaComparable()
Get a Comparable value that implements the XML Schema ordering comparison semantics for this value.
The default implementation is written to compare sequences of atomic values.
This method is overridden for AtomicValue and its subclasses.
In the case of data types that are partially ordered, the returned Comparable extends the standard
semantics of the compareTo() method by returning the value
INDETERMINATE_ORDERING
when there
is no defined order relationship between two given values.
- a Comparable that follows XML Schema comparison rules
getStringValue
public String getStringValue()
throws XPathException
Convert the value to a string, using the serialization rules.
For atomic values this is the same as a cast; for sequence values
it gives a space-separated list.
- getStringValue in interface ValueRepresentation
XPathException
- The method can fail if evaluation of the value
has been deferred, and if a failure occurs during the deferred evaluation.
No failure is possible in the case of an AtomicValue.
getStringValueCS
public CharSequence getStringValueCS()
throws XPathException
Get the value of the item as a CharSequence. This is in some cases more efficient than
the version of the method that returns a String.
- getStringValueCS in interface ValueRepresentation
itemAt
public Item itemAt(int n)
throws XPathException
Get the n'th item in the sequence (starting from 0). This is defined for all
Values, but its real benefits come for a sequence Value stored extensionally
(or for a MemoClosure, once all the values have been read)
n
- position of the required item, counting from zero.
- the n'th item in the sequence, where the first item in the sequence is
numbered zero. If n is negative or >= the length of the sequence, returns null.
iterate
public abstract SequenceIterator iterate()
throws XPathException
Iterate over the items contained in this value.
- an iterator over the sequence of items
XPathException
- if a dynamic error occurs. This is possible only in the case of values
that are materialized lazily, that is, where the iterate() method leads to computation of an
expression that delivers the values.
makeQNameValue
public static QNameValue makeQNameValue(Object object,
Configuration config)
Temporary method to make a QNameValue from a JAXP 1.3 QName, without creating a compile-time link
to the JDK 1.5 QName class
object
- an instance of javax.xml.namespace.QNameconfig
- the Saxon configuration (used for dynamic loading)
- a corresponding Saxon QNameValue, or null if any error occurs performing the conversion
process
public void process(XPathContext context)
throws XPathException
Process the value as an instruction, without returning any tail calls
context
- The dynamic context, giving access to the current node,
the current variables, etc.
reduce
public Value reduce()
throws XPathException
Reduce a value to its simplest form. If the value is a closure or some other form of deferred value
such as a FunctionCallPackage, then it is reduced to a SequenceExtent. If it is a SequenceExtent containing
a single item, then it is reduced to that item. One consequence that is exploited by class FilterExpression
is that if the value is a singleton numeric value, then the result will be an instance of NumericValue
- the value in simplified form
stringToNumber
public static double stringToNumber(CharSequence s)
throws NumberFormatException
Static method to convert strings to doubles.
s
- the String to be converted
- a double representing the value of the String
toString
public String toString()
Convert to a string for diagnostic output