net.sf.saxon.value

Class Value

public abstract class Value extends Object implements Serializable, SequenceIterable, ValueRepresentation

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.
Field Summary
static intINDETERMINATE_ORDERING
Constant returned by compareTo() method to indicate an indeterminate ordering between two values
Method Summary
static ItemasItem(ValueRepresentation value)
Static method to make an Item from a Value
ItemasItem()
Return the value in the form of an Item
static SequenceIteratorasIterator(ValueRepresentation val)
Static method to get an Iterator over any ValueRepresentation (which may be either a Value or a NodeInfo or a FunctionItem
static ValueasValue(ValueRepresentation val)
Static method to make a Value from a given Item (which may be either an AtomicValue or a NodeInfo or a FunctionItem
voidcheckPermittedContents(SchemaType parentType, StaticContext env, boolean whole)
Check statically that the results of the expression are capable of constructing the content of a given schema type.
static ObjectconvertToJava(Item item)
Convert an XPath value to a Java object.
booleaneffectiveBooleanValue()
Get the effective boolean value of the expression.
booleanequals(Object obj)
Compare two (sequence) values for equality.
static ValuefromItem(Item item)
Static method to get a Value from an Item
CharSequencegetCanonicalLexicalRepresentation()
Get the canonical lexical representation as defined in XML Schema.
intgetCardinality()
Determine the cardinality
ItemTypegetItemType(TypeHierarchy th)
Determine the data type of the items in the expression, if possible
static SequenceIteratorgetIterator(ValueRepresentation val)
Get a SequenceIterator over a ValueRepresentation
intgetLength()
Get the length of the sequence
ComparablegetSchemaComparable()
Get a Comparable value that implements the XML Schema ordering comparison semantics for this value.
StringgetStringValue()
Convert the value to a string, using the serialization rules.
CharSequencegetStringValueCS()
Get the value of the item as a CharSequence.
booleanisIdentical(Value v)
Determine whether two values are identical, as determined by XML Schema rules.
ItemitemAt(int n)
Get the n'th item in the sequence (starting from 0).
abstract SequenceIteratoriterate()
Iterate over the items contained in this value.
SequenceIteratoriterate(XPathContext context)
Return an iterator over the results of evaluating an expression
voidprocess(XPathContext context)
Process the value as an instruction, without returning any tail calls
Valuereduce()
Reduce a value to its simplest form.
static doublestringToNumber(CharSequence s)
Static method to convert strings to doubles.

Field Detail

INDETERMINATE_ORDERING

public static final int INDETERMINATE_ORDERING
Constant returned by compareTo() method to indicate an indeterminate ordering between two values

Method Detail

asItem

public static Item asItem(ValueRepresentation value)
Static method to make an Item from a Value

Parameters: value the value to be converted

Returns: null if the value is an empty sequence; or the only item in the value if it is a singleton sequence

Throws: XPathException if the Value contains multiple items

asItem

public Item asItem()
Return the value in the form of an Item

Returns: the value in the form of an Item

asIterator

public static SequenceIterator asIterator(ValueRepresentation val)
Static method to get an Iterator over any ValueRepresentation (which may be either a Value or a NodeInfo or a FunctionItem

Parameters: val The supplied value, or null, indicating the empty sequence.

Returns: 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 or a FunctionItem

Parameters: val The supplied value, or null, indicating the empty sequence.

Returns: 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)
Check statically that the results of the expression are capable of constructing the content of a given schema type.

Parameters: parentType The schema type env the static context whole true if this value accounts for the entire content of the containing node

Throws: XPathException if the expression doesn't match the required content type

convertToJava

public static Object convertToJava(Item item)
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).

Parameters: item the item to be converted

Returns: the value after conversion

effectiveBooleanValue

public boolean effectiveBooleanValue()
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.

Returns: the effective boolean value

Throws: XPathException if any dynamic error occurs evaluating the expression

equals

public boolean equals(Object obj)
Compare two (sequence) values for equality. This method throws an UnsupportedOperationException, because it should not be used: there are too many "equality" operators that can be defined on values for the concept to be meaningful.

Consider creating an XPathComparable from each value, and comparing those; or creating a SchemaComparable to achieve equality comparison as defined in XML Schema.

Throws: UnsupportedOperationException (always)

fromItem

public static Value fromItem(Item item)
Static method to get a Value from an Item

Parameters: item the supplied item

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

Returns: 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

Returns: the cardinality

getItemType

public ItemType getItemType(TypeHierarchy th)
Determine the data type of the items in the expression, if possible

Parameters: th The TypeHierarchy. Can be null if the target is an AtomicValue.

Returns: for the default implementation: AnyItemType (not known)

getIterator

public static SequenceIterator getIterator(ValueRepresentation val)
Get a SequenceIterator over a ValueRepresentation

Parameters: val the value to iterate over

Returns: the iterator

getLength

public int getLength()
Get the length of the sequence

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

Returns: a Comparable that follows XML Schema comparison rules

getStringValue

public String getStringValue()
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.

Throws: 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()
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.

isIdentical

public boolean isIdentical(Value v)
Determine whether two values are identical, as determined by XML Schema rules. This is a stronger test than equality (even schema-equality); for example two dateTime values are not identical unless they are in the same timezone.

Note that even this check ignores the type annotation of the value. The integer 3 and the short 3 are considered identical, even though they are not fully interchangeable. "Identical" means the same point in the value space, regardless of type annotation.

Although the schema rules cover nodes only, this method also handles values that include nodes, using node identity in this case.

The empty sequence is considered identical to the empty sequence.

NaN is identical to itself.

Parameters: v the other value to be compared with this one

Returns: true if the two values are identical, false otherwise.

itemAt

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

Parameters: n position of the required item, counting from zero.

Returns: 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()
Iterate over the items contained in this value.

Returns: an iterator over the sequence of items

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

iterate

public final SequenceIterator iterate(XPathContext context)
Return an iterator over the results of evaluating an expression

Parameters: context the dynamic evaluation context (not used in this implementation)

Returns: an iterator over the items delivered by the expression

process

public void process(XPathContext context)
Process the value as an instruction, without returning any tail calls

Parameters: context The dynamic context, giving access to the current node, the current variables, etc.

reduce

public Value reduce()
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

Returns: the value in simplified form

stringToNumber

public static double stringToNumber(CharSequence s)
Static method to convert strings to doubles.

Parameters: s the String to be converted

Returns: a double representing the value of the String

Throws: NumberFormatException if the value cannot be converted