## net.sf.saxon.value
Class Value

    java.lang.Object
      net.sf.saxon.value.Value

All Implemented Interfaces:
  Serializable, Comparable, SequenceIterable, ValueRepresentation

Direct Known Subclasses:
  AtomicValue, Closure, CompiledClosure, EmptySequence, IndexedValue, IntegerRange, ItemClosure, SequenceExtent, ShareableSequence, SingletonNode, Tail

    public abstract class Value

extends Object
implements Serializable, SequenceIterable, ValueRepresentation, Comparable

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.

See Also:
  Serialized Form

Field Summary
`static Class[]` `EMPTY_CLASS_ARRAY`
`static int` `INDETERMINATE_ORDERING` Constant returned by compareTo() method to indicate an indeterminate ordering between two values

Fields inherited from interface net.sf.saxon.om.ValueRepresentation
`EMPTY_VALUE_ARRAY`

Constructor Summary
`Value()`

Method Summary
`Item` `asItem()` Return the value in the form of an Item
`static Item` `asItem(ValueRepresentation value)` Static method to make an Item from a Value
`static SequenceIterator` `asIterator(ValueRepresentation val)` Static method to get an Iterator over any ValueRepresentation (which may be either a Value or a NodeInfo
`static Value` `asValue(ValueRepresentation val)` Static method to make a Value from a given Item (which may be either an AtomicValue or a NodeInfo
`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.
`int` `compareTo(Object o)` Compares this object with the specified object for order.
`static Object` `convert(Item item)` Internal method to convert an XPath value to a Java object.
`static Value` `convertJavaObjectToXPath(Object object, SequenceType requiredType, XPathContext context)` Convert a Java object to an XPath value.
`Object` `convertToJava(Class target, XPathContext context)` Convert to Java object (for passing to external functions)
`boolean` `effectiveBooleanValue()` Get the effective boolean value of the expression.
`boolean` `equals(Object obj)` Compare two (sequence) values for equality.
`static Value` `fromItem(Item item)` Static method to get a Value from an Item
`CharSequence` `getCanonicalLexicalRepresentation()` Get the canonical lexical representation as defined in XML Schema.
`int` `getCardinality()` Determine the cardinality
`ItemType` `getItemType(TypeHierarchy th)` Determine the data type of the items in the expression, if possible
`static SequenceIterator` `getIterator(ValueRepresentation val)` Get a SequenceIterator over a ValueRepresentation
`int` `getLength()` Get the length of the sequence
`Comparable` `getSchemaComparable()` Get a Comparable value that implements the XML Schema ordering comparison semantics for this value.
`String` `getStringValue()` Convert the value to a string, using the serialization rules.
`CharSequence` `getStringValueCS()` Get the value of the item as a CharSequence.
`int` `hashCode()` Return a hash code to support the equals() function
`abstract boolean` `isMultiValued()` Determine whether the value is multivalued, that is, whether it is a sequence that potentially contains more than one item
`Item` `itemAt(int n)` Get the n'th item in the sequence (starting from 0).
`abstract SequenceIterator` `iterate()` Iterate over the items contained in this value.
`SequenceIterator` `iterate(XPathContext context)` Return an iterator over the results of evaluating an expression
`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
`void` `process(XPathContext context)` Process the value as an instruction, without returning any tail calls
`Value` `reduce()` Reduce a value to its simplest form.
`static double` `stringToNumber(CharSequence s)` Static method to convert strings to doubles.
`String` `toString()` Convert to a string for diagnostic output

Methods inherited from class java.lang.Object
`getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### INDETERMINATE_ORDERING

    public static final int INDETERMINATE_ORDERING

  Constant returned by compareTo() method to indicate an indeterminate ordering between two values

  See Also:
    Constant Field Values

### EMPTY_CLASS_ARRAY

    public static final Class[] EMPTY_CLASS_ARRAY

Constructor Detail

### Value

    public Value()

Method Detail

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

  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

### asItem

    public static Item asItem(ValueRepresentation value)
                       throws XPathException

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

  Return the value in the form of an Item

  Returns:
    the value in the form of an Item
  Throws:
    `XPathException`

### fromItem

    public static Value fromItem(Item item)

  Static method to get a Value from an Item

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

  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
  Throws:
    `XPathException`

### stringToNumber

    public static double stringToNumber(CharSequence s)
                                 throws NumberFormatException

  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

### getIterator

    public static SequenceIterator getIterator(ValueRepresentation val)
                                        throws XPathException

  Get a SequenceIterator over a ValueRepresentation

  Throws:
    `XPathException`

### iterate

    public abstract SequenceIterator iterate()
                                      throws XPathException

  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)
                                   throws XPathException

  Return an iterator over the results of evaluating an expression

  Specified by:
    `iterate` in interface `SequenceIterable`
  Parameters:
    `context` - the dynamic evaluation context (not used in this implementation)
  Returns:
    an iterator over the items delivered by the expression
  Throws:
    `XPathException`

### 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.

  Specified by:
    `getStringValueCS` in interface `ValueRepresentation`
  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 or a Node.

### 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.

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

### getCardinality

    public int getCardinality()

  Determine the cardinality

### isMultiValued

    public abstract boolean isMultiValued()

  Determine whether the value is multivalued, that is, whether it is a sequence that potentially contains more than one item

  Returns:
    true if the value might contain more than one item, false if it definitely contains zero or one items

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

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

### getLength

    public int getLength()
                  throws XPathException

  Get the length of the sequence

  Throws:
    `XPathException`

### process

    public void process(XPathContext context)
                 throws XPathException

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

### 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.

  Specified by:
    `getStringValue` in interface `ValueRepresentation`
  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.

### 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.

  Returns:
    the effective boolean value
  Throws:
    `XPathException` - if any dynamic error occurs evaluating the expression

### getSchemaComparable

    public Comparable getSchemaComparable()

  Get a Comparable value that implements the XML Schema ordering comparison semantics for this value. The default implementation returns "this", which ensures that comparisons between list values are handled by the equals() and compareTo() methods on this class itself. This is overridden for atomic values.

  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.

### equals

    public boolean equals(Object obj)

  Compare two (sequence) values for equality. This supports identity constraints in XML Schema, which allow list-valued elements and attributes to participate in key and uniqueness constraints. This method returns false if any error occurs during the comparison, or if any of the items in either sequence is a node rather than an atomic value.

  Overrides:
    `equals` in class `Object`

### hashCode

    public int hashCode()

  Return a hash code to support the equals() function

  Overrides:
    `hashCode` in class `Object`

### compareTo

    public int compareTo(Object o)

  Compares this object with the specified object for order. This implements the comparison semantics for XML Schema ordering facets such as minInclusive etc

  Specified by:
    `compareTo` in interface `Comparable`

### 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.

  Parameters:
    `parentType` - The schema type
    `env` - the static context
    `whole` -
  Throws:
    `XPathException` - if the expression doesn't match the required content type

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

  Throws:
    `XPathException`

### convertToJava

    public Object convertToJava(Class target,
                                XPathContext context)
                         throws XPathException

  Convert to Java object (for passing to external functions)

  Throws:
    `XPathException`

### 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.

  Parameters:
    `object` - The Java object to be converted
    `requiredType` - The required type of the result (if known)
    `context` -
  Returns:
    the result of converting the value. If the value is null, returns null.
  Throws:
    `XPathException`

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

  Parameters:
    `object` - an instance of javax.xml.namespace.QName
  Returns:
    a corresponding Saxon QNameValue, or null if any error occurs performing the conversion

### toString

    public String toString()

  Convert to a string for diagnostic output

  Overrides:
    `toString` in class `Object`

### convert

    public static Object convert(Item item)
                          throws XPathException

  Internal method to 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).

  Throws:
    `XPathException`

Copyright (C) Michael H. Kay. All rights reserved.