net.sf.saxon.value

Class StringValue

java.lang.Object

net.sf.saxon.value.Value

net.sf.saxon.value.AtomicValue

net.sf.saxon.value.StringValue

All Implemented Interfaces:

java.io.Serializable, Expression, Item, ValueRepresentation

Direct Known Subclasses:

AnyURIValue, RestrictedStringValue, UntypedAtomicValue

public class StringValue
extends AtomicValue

An atomic value of type xs:string

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	StringValue.CharacterIterator CharacterIterator is used to iterate over the characters in a string, returning them as integers representing the Unicode code-point.

Field Summary

Fields

Modifier and Type	Field and Description
static StringValue	EMPTY_STRING
static StringValue	FALSE
protected int	length
static StringValue	SINGLE_SPACE
static StringValue	TRUE
protected java.lang.CharSequence	value

Fields inherited from class net.sf.saxon.value.Value

EMPTY_CLASS_ARRAY

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

EMPTY_VALUE_ARRAY

Fields inherited from interface net.sf.saxon.expr.Expression

EVALUATE_METHOD, ITERATE_METHOD, PROCESS_METHOD

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	StringValue() Protected constructor for use by subtypes
	StringValue(java.lang.CharSequence value) Constructor.

Method Summary

Modifier and Type	Method and Description
boolean	codepointEquals(StringValue other) Test whether this StringValue is equal to another under the rules of the codepoint collation
boolean	containsSurrogatePairs() Determine whether the string contains surrogate pairs
static java.lang.CharSequence	contract(int[] codes, int used) Contract an array of integers containing Unicode codepoints into a Java string
AtomicValue	convertPrimitive(BuiltInAtomicType requiredType, boolean validate, XPathContext context) Convert a value to another primitive data type, with control over how validation is handled.
static AtomicValue	convertStringToAtomicType(java.lang.CharSequence value, AtomicType targetType, NameChecker checker) Convert the value to a given type.
static AtomicValue	convertStringToBuiltInType(java.lang.CharSequence value, BuiltInAtomicType requiredType, NameChecker checker) Convert a string value to another built-in data type, with control over how validation is handled.
java.lang.Object	convertToJava(java.lang.Class target, XPathContext context) Convert to Java object (for passing to external functions)
boolean	effectiveBooleanValue(XPathContext context) Get the effective boolean value of a string
boolean	equals(java.lang.Object other) Determine if two StringValues are equal, according to XML Schema rules.
int[]	expand() Expand a string containing surrogate pairs into an array of 32-bit characters
static int[]	expand(java.lang.CharSequence s) Expand a string containing surrogate pairs into an array of 32-bit characters
ItemType	getItemType(TypeHierarchy th) Return the type of the expression
int	getStringLength() Get the length of this string, as defined in XPath.
static int	getStringLength(java.lang.CharSequence s) Get the length of a string, as defined in XPath.
java.lang.String	getStringValue() Get the string value as a String
java.lang.CharSequence	getStringValueCS() Get the value of the item as a CharSequence.
int	hashCode() Return a hash code to support the equals() function
boolean	isZeroLength() Determine whether the string is a zero-length string.
SequenceIterator	iterateCharacters() Iterate over a string, returning a sequence of integers representing the Unicode code-point values
static StringValue	makeStringValue(java.lang.CharSequence value) Factory method.
java.lang.String	toString() Get string value.

Methods inherited from class net.sf.saxon.value.AtomicValue

checkPermittedContents, convert, convert, display, evaluateAsString, evaluateItem, getCardinality, getComponent, getImplementationMethod, getLength, getPrimitiveValue, getTypedValue, hasBuiltInType, iterate, process

Methods inherited from class net.sf.saxon.value.Value

asItem, asIterator, asValue, convert, convertJavaObjectToXPath, getDependencies, getIterator, getParentExpression, getSpecialProperties, itemAt, iterateSubExpressions, makeQNameValue, optimize, promote, reduce, simplify, stringToNumber, typeCheck

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY_STRING

public static final StringValue EMPTY_STRING

SINGLE_SPACE

public static final StringValue SINGLE_SPACE

TRUE

public static final StringValue TRUE

FALSE

public static final StringValue FALSE

value

protected java.lang.CharSequence value

length

protected int length

Constructor Detail

StringValue

protected StringValue()

Protected constructor for use by subtypes

StringValue

public StringValue(java.lang.CharSequence value)

Constructor. Note that although a StringValue may wrap any kind of CharSequence (usually a String, but it can also be, for example, a StringBuffer), the caller is responsible for ensuring that the value is immutable.

Parameters:

value - the String value. Null is taken as equivalent to "".

Method Detail

makeStringValue

public static StringValue makeStringValue(java.lang.CharSequence value)

Factory method. Unlike the constructor, this avoids creating a new StringValue in the case of a zero-length string (and potentially other strings, in future)

Parameters:

value - the String value. Null is taken as equivalent to "".

Returns:

the corresponding StringValue

getStringValue

public final java.lang.String getStringValue()

Get the string value as a String

Specified by:

getStringValue in interface Item

Specified by:

getStringValue in interface ValueRepresentation

Specified by:

getStringValue in class AtomicValue

Returns:

the string value of the item

See Also:

Item.getStringValueCS()

getStringValueCS

public final java.lang.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.

Specified by:

getStringValueCS in interface Item

Specified by:

getStringValueCS in interface ValueRepresentation

Overrides:

getStringValueCS in class AtomicValue

Returns:

the string value of the item

See Also:

Item.getStringValue()

convertPrimitive

public AtomicValue convertPrimitive(BuiltInAtomicType requiredType,
                                    boolean validate,
                                    XPathContext context)

Convert a value to another primitive data type, with control over how validation is handled.

Specified by:

convertPrimitive in class AtomicValue

Parameters:

requiredType - type code of the required atomic type

validate - true if validation is required. If set to false, the caller guarantees that the value is valid for the target data type, and that further validation is therefore not required. Note that a validation failure may be reported even if validation was not requested.

context -

Returns:

the result of the conversion, if successful. If unsuccessful, the value returned will be a ValidationErrorValue. The caller must check for this condition. No exception is thrown, instead the exception will be encapsulated within the ErrorValue.

convertStringToBuiltInType

public static AtomicValue convertStringToBuiltInType(java.lang.CharSequence value,
                                                     BuiltInAtomicType requiredType,
                                                     NameChecker checker)

Convert a string value to another built-in data type, with control over how validation is handled.

Parameters:

value - the value to be converted

requiredType - the required atomic type

checker - if validation is required, a NameChecker. If set to null, the caller guarantees that the value is valid for the target data type, and that further validation is therefore not required. Note that a validation failure may be reported even if validation was not requested.

Returns:

the result of the conversion, if successful. If unsuccessful, the value returned will be a ValidationErrorValue. The caller must check for this condition. No exception is thrown, instead the exception will be encapsulated within the ValidationErrorValue.

convertStringToAtomicType

public static AtomicValue convertStringToAtomicType(java.lang.CharSequence value,
                                                    AtomicType targetType,
                                                    NameChecker checker)

Convert the value to a given type. The result of the conversion will be an atomic value of the required type. This method works where the target type is a built-in atomic type and also where it is a user-defined atomic type.

Parameters:

targetType - the type to which the value is to be converted

checker - a NameChecker if validation is required, null if the caller already knows that the value is valid

Returns:

the value after conversion if successful; or a ValidationErrorValue if conversion failed. The caller must check for this condition. Validation may fail even if validation was not requested.

getItemType

public ItemType getItemType(TypeHierarchy th)

Return the type of the expression

Specified by:

getItemType in interface Expression

Overrides:

getItemType in class Value

Parameters:

th -

Returns:

Type.STRING (always)

getStringLength

public int getStringLength()

Get the length of this string, as defined in XPath. This is not the same as the Java length, as a Unicode surrogate pair counts as a single character

getStringLength

public static int getStringLength(java.lang.CharSequence s)

Get the length of a string, as defined in XPath. This is not the same as the Java length, as a Unicode surrogate pair counts as a single character.

Parameters:

s - The string whose length is required

isZeroLength

public boolean isZeroLength()

Determine whether the string is a zero-length string. This may be more efficient than testing whether the length is equal to zero

containsSurrogatePairs

public boolean containsSurrogatePairs()

Determine whether the string contains surrogate pairs

Returns:

true if the string contains any non-BMP characters

iterateCharacters

public SequenceIterator iterateCharacters()

Iterate over a string, returning a sequence of integers representing the Unicode code-point values

expand

public int[] expand()

Expand a string containing surrogate pairs into an array of 32-bit characters

expand

public static int[] expand(java.lang.CharSequence s)

Expand a string containing surrogate pairs into an array of 32-bit characters

contract

public static java.lang.CharSequence contract(int[] codes,
                                              int used)

Contract an array of integers containing Unicode codepoints into a Java string

equals

public boolean equals(java.lang.Object other)

Determine if two StringValues are equal, according to XML Schema rules. (This method is not used for XPath comparisons, which are always under the control of a collation.)

Overrides:

equals in class Value

Throws:

java.lang.ClassCastException - if the values are not comparable

hashCode

public int hashCode()

Description copied from class: Value

Return a hash code to support the equals() function

Overrides:

hashCode in class Value

codepointEquals

public boolean codepointEquals(StringValue other)

Test whether this StringValue is equal to another under the rules of the codepoint collation

effectiveBooleanValue

public boolean effectiveBooleanValue(XPathContext context)

Get the effective boolean value of a string

Specified by:

effectiveBooleanValue in interface Expression

Overrides:

effectiveBooleanValue in class AtomicValue

Parameters:

context - not used

Returns:

true if the string has length greater than zero

convertToJava

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

Convert to Java object (for passing to external functions)

Overrides:

convertToJava in class Value

Throws:

XPathException

toString

public java.lang.String toString()

Description copied from class: AtomicValue

Get string value. In general toString() for an atomic value displays the value as it would be written in XPath: that is, as a literal if available, or as a call on a constructor function otherwise.

Overrides:

toString in class AtomicValue