Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.sf.saxon.value
Class Value<T extends Item>

    java.lang.Object
      net.sf.saxon.value.Value<T>

All Implemented Interfaces:
  ValueRepresentation<T>

Direct Known Subclasses:
  AtomicValue, Closure, EmptySequence, IndexedValue, IntegerRange, SequenceExtent, ShareableSequence, SingletonItem

    public abstract class Value<T extends Item>

extends Object
implements ValueRepresentation<T>

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 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
`<T extends Item> SequenceIterator<T>`
` | `asIterator(ValueRepresentation<T> val)` Static method to get an Iterator over any ValueRepresentation (which may be either a Value or a NodeInfo or a FunctionItem
`static
`<T extends Item> Value<T>`
` | `asValue(ValueRepresentation<T> val)` Static method to make a Value from a given Item (which may be either an AtomicValue or a NodeInfo or a FunctionItem
`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.
`static Object` | `convertToJava(Item item)` Convert an XPath value to a Java object.
`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.
`static int` | `getSequenceLength(ValueRepresentation val)` Static method to get the length of a ValueRepresentation (the number of items in the sequence)
`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()`
`boolean` | `isIdentical(Value v)` Determine whether two values are identical, as determined by XML Schema rules.
`T` | `itemAt(int n)` Get the n'th item in the sequence (starting from 0).
`abstract SequenceIterator<T>` | `iterate()` Iterate over the items contained in this value.
`void` | `process(XPathContext context)` Process the value as an instruction, without returning any tail calls
`Value` | `reduce()` Reduce a value to its simplest form.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, toString, 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

Constructor Detail

### Value

    public Value()

Method Detail

### asValue

    public static <T extends Item> Value<T> asValue(ValueRepresentation<T> 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

### getSequenceLength

    public static int getSequenceLength(ValueRepresentation val)
                                 throws XPathException

  Static method to get the length of a ValueRepresentation (the number of items in the sequence)

  Parameters:
    `val` - The supplied value, or null, indicating the empty sequence.
  Returns:
    The length of the supplied value, considered as a sequence
  Throws:
    `XPathException` - if an error occurs (for example, if the supplied value is a Closure and needs to be evaluated to determine the length of the result)

### 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` - if an error occurs, notably if this value is a sequence containing more than one item

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

### asIterator

    public static <T extends Item> SequenceIterator<T> asIterator(ValueRepresentation<T> val)
                                                       throws XPathException

  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
  Throws:
    `XPathException` - if an error occurs

### getIterator

    public static SequenceIterator getIterator(ValueRepresentation val)
                                        throws XPathException

  Get a SequenceIterator over a ValueRepresentation

  Parameters:
    `val` - the value to iterate over
  Returns:
    the iterator
  Throws:
    `XPathException` - if an error occurs (typically when the value is a Closure that needs to be evaluated)

### iterate

    public abstract SequenceIterator<T> 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.

### 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<T extends Item>`
  Returns:
    the result of converting the value to a string
  Throws:
    `XPathException` - The method can fail if evaluation of the value has been deferred, and if a failure occurs during the deferred evaluation. It can also occur for values such as function items and maps that have no string value. 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.

  Returns:
    the canonical lexical representation if defined in XML Schema; otherwise, the result of casting to string according to the XPath 2.0 rules

### getItemType

    public ItemType getItemType(TypeHierarchy th)

  Determine the data type of the items in the expression, if possible

  Parameters:
    `th` - The TypeHierarchy. If null is supplied, the resulting item type may be less precise.
  Returns:
    for the default implementation: AnyItemType (not known)

### getCardinality

    public int getCardinality()

  Determine the cardinality

  Returns:
    the cardinality

### itemAt

    public T 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` - if an error occurs (for example if the value is a Closure that needs to be evaluated to find the Nth item)

### getLength

    public int getLength()
                  throws XPathException

  Get the length of the sequence

  Returns:
    the number of items in the sequence
  Throws:
    `XPathException` - if an error occurs (for example if the value is a closure that needs to be read to determine its length)

### 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` - if an error occurs (for example if the value is a closure that needs to be evaluated)

### 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<T extends Item>`
  Returns:
    the result of converting the value to a string
  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 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

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

  Overrides:
    `equals` in class `Object`
  Throws:
    `UnsupportedOperationException` - (always)

### hashCode

    public int hashCode()

  Overrides:
    `hashCode` in class `Object`

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

  Function items are not identical to anything except themselves

  Parameters:
    `v` - the other value to be compared with this one
  Returns:
    true if the two values are identical, false otherwise.

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

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

  Returns:
    the value in simplified form
  Throws:
    `XPathException` - if an error occurs

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

  Parameters:
    `item` - the item to be converted
  Returns:
    the value after conversion
  Throws:
    `XPathException` - if an error occurs: for example, if the XPath value is an integer and is too big to fit in a Java long

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (c) 2004-2011 Saxonica Limited. All rights reserved.