net.sf.saxon.value

Class StringValue

Implemented Interfaces:
ConversionResult, GroundedValue, Item, PullEvent, Serializable, SequenceIterable, Serializable, ValueRepresentation
Known Direct Subclasses:
AnyURIValue, UntypedAtomicValue

public class StringValue
extends AtomicValue

An atomic value of type xs:string

Nested Class Summary

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

static StringValue
EMPTY_STRING
static StringValue
FALSE
static StringValue
SINGLE_SPACE
static StringValue
TRUE
protected int
length
protected CharSequence
value

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

typeLabel

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

EMPTY_CLASS_ARRAY, INDETERMINATE_ORDERING

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

EMPTY_VALUE_ARRAY

Constructor Summary

StringValue()
Protected constructor for use by subtypes
StringValue(CharSequence value)
Constructor.

Method Summary

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 CharSequence
contract(int[] codes, int used)
Contract an array of integers containing Unicode codepoints into a Java string
ConversionResult
convertPrimitive(BuiltInAtomicType requiredType, boolean validate, XPathContext context)
Convert a value to another primitive data type, with control over how validation is handled.
static ConversionResult
convertStringToAtomicType(CharSequence value, AtomicType targetType, NameChecker checker)
Convert the value to a given type.
static ConversionResult
convertStringToBuiltInType(CharSequence value, BuiltInAtomicType requiredType, NameChecker checker)
Convert a string value to another built-in data type, with control over how validation is handled.
Object
convertToJava(Class target, XPathContext context)
Convert to Java object (for passing to external functions)
AtomicValue
copyAsSubType(AtomicType typeLabel)
Create a copy of this atomic value, with a different type label
static String
diagnosticDisplay(String s)
Produce a diagnostic representation of the contents of the string
boolean
effectiveBooleanValue()
Get the effective boolean value of a string
boolean
equals(Object other)
Determine if two AtomicValues are equal, according to XPath rules.
int[]
expand()
Expand a string containing surrogate pairs into an array of 32-bit characters
static int[]
expand(CharSequence s)
Expand a string containing surrogate pairs into an array of 32-bit characters
BuiltInAtomicType
getPrimitiveType()
Determine the primitive type of the value.
Comparable
getSchemaComparable()
Get a Comparable value that implements the XML Schema comparison semantics for this value.
int
getStringLength()
Get the length of this string, as defined in XPath.
static int
getStringLength(CharSequence s)
Get the length of a string, as defined in XPath.
String
getStringValue()
Get the string value as a String
CharSequence
getStringValueCS()
Get the value of the item as a CharSequence.
Object
getXPathComparable(boolean ordered, StringCollator collator, XPathContext context)
Get an object value that implements the XPath equality and ordering comparison semantics for this value.
boolean
isZeroLength()
Determine whether the string is a zero-length string.
UnfailingIterator
iterateCharacters()
Iterate over a string, returning a sequence of integers representing the Unicode code-point values
static ConversionResult
makeRestrictedString(CharSequence value, BuiltInAtomicType typeLabel, NameChecker checker)
Factory method to create a string value belonging to a built-in type derived from string
static StringValue
makeStringValue(CharSequence value)
Factory method.
void
setStringValueCS(CharSequence value)
Set the value of the item as a CharSequence.
String
toString()
Get string value.
static ValidationFailure
validate(BuiltInAtomicType typeLabel, CharSequence val, NameChecker checker)
Validate that the string conforms to the rules for a built-in subtype of xs:string

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

asAtomic, checkPermittedContents, convert, convert, convertPrimitive, copyAsSubType, effectiveBooleanValue, equals, getCardinality, getComponent, getItemType, getLength, getPrimitiveType, getSchemaComparable, getStringValue, getStringValueCS, getTypeLabel, getTypedValue, getXPathComparable, isNaN, itemAt, iterate, process, setTypeLabel, subsequence, toString

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

asItem, asItem, asIterator, asValue, checkPermittedContents, convertJavaObjectToXPath, convertToJava, convertToJava, effectiveBooleanValue, equals, fromItem, getCanonicalLexicalRepresentation, getCardinality, getItemType, getIterator, getLength, getSchemaComparable, getStringValue, getStringValueCS, itemAt, iterate, iterate, makeQNameValue, process, reduce, stringToNumber, toString

Field Details

EMPTY_STRING

public static final StringValue EMPTY_STRING

FALSE

public static final StringValue FALSE

SINGLE_SPACE

public static final StringValue SINGLE_SPACE

TRUE

public static final StringValue TRUE

length

protected int length

value

protected CharSequence value

Constructor Details

StringValue

protected StringValue()
Protected constructor for use by subtypes

StringValue

public StringValue(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 Details

codepointEquals

public boolean codepointEquals(StringValue other)
Test whether this StringValue is equal to another under the rules of the codepoint collation
Parameters:
other - the value to be compared with this value
Returns:
true if the strings are equal on a codepoint-by-codepoint basis

containsSurrogatePairs

public boolean containsSurrogatePairs()
Determine whether the string contains surrogate pairs
Returns:
true if the string contains any non-BMP characters

contract

public static CharSequence contract(int[] codes,
                                    int used)
Contract an array of integers containing Unicode codepoints into a Java string
Parameters:
codes - an array of integers representing the Unicode code points
used - the number of items in the array that are actually used
Returns:
the constructed string

convertPrimitive

public ConversionResult convertPrimitive(BuiltInAtomicType requiredType,
                                         boolean validate,
                                         XPathContext context)
Convert a value to another primitive data type, with control over how validation is handled.
Overrides:
convertPrimitive in interface 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 - XPath dynamic context. Used only where the target type is one such as NCName whose definition is context-sensitive
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.

convertStringToAtomicType

public static ConversionResult convertStringToAtomicType(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. It does not handle namespace-sensitive types (QName, NOTATION, and derivatives).
Parameters:
value - the value to be converted
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. Note that a non-null NameChecker acts as a signal that validation is required, even when the value to be checked is not a name.
Returns:
the value after conversion if successful; or a ValidationFailure if conversion failed. The caller must check for this condition. Validation may fail even if validation was not requested.

convertStringToBuiltInType

public static ConversionResult convertStringToBuiltInType(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 ValidationFailure. The caller must check for this condition. No exception is thrown, instead the exception will be encapsulated within the ValidationFailure.

convertToJava

public Object convertToJava(Class target,
                            XPathContext context)
            throws XPathException
Convert to Java object (for passing to external functions)
Overrides:
convertToJava in interface Value

copyAsSubType

public AtomicValue copyAsSubType(AtomicType typeLabel)
Create a copy of this atomic value, with a different type label
Overrides:
copyAsSubType in interface AtomicValue
Parameters:
typeLabel - the type label of the new copy. The caller is responsible for checking that the value actually conforms to this type.

diagnosticDisplay

public static String diagnosticDisplay(String s)
Produce a diagnostic representation of the contents of the string
Parameters:
s - the string
Returns:
a string in which non-Ascii-printable characters are replaced by \ uXXXX escapes

effectiveBooleanValue

public boolean effectiveBooleanValue()
Get the effective boolean value of a string
Overrides:
effectiveBooleanValue in interface AtomicValue
Returns:
true if the string has length greater than zero

equals

public boolean equals(Object other)
Determine if two AtomicValues are equal, according to XPath rules. (This method is not used for string comparisons, which are always under the control of a collation. If we get here, it's because there's a type error in the comparison.)
Overrides:
equals in interface AtomicValue

expand

public int[] expand()
Expand a string containing surrogate pairs into an array of 32-bit characters
Returns:
an array of integers representing the Unicode code points

expand

public static int[] expand(CharSequence s)
Expand a string containing surrogate pairs into an array of 32-bit characters
Parameters:
s - the string to be expanded
Returns:
an array of integers representing the Unicode code points

getPrimitiveType

public BuiltInAtomicType getPrimitiveType()
Determine the primitive type of the value. This delivers the same answer as getItemType().getPrimitiveItemType(). The primitive types are the 19 primitive types of XML Schema, plus xs:integer, xs:dayTimeDuration and xs:yearMonthDuration, and xs:untypedAtomic. For external objects, the result is AnyAtomicType.
Overrides:
getPrimitiveType in interface AtomicValue

getSchemaComparable

public Comparable getSchemaComparable()
Get a Comparable value that implements the XML Schema comparison semantics for this value. Returns null if the value is not comparable according to XML Schema rules. This implementation returns the underlying Java string, which works because strings will only be compared for equality, not for ordering, and the equality rules for strings in XML schema are the same as in Java.
Overrides:
getSchemaComparable in interface AtomicValue

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
Returns:
the length of the string in Unicode code points

getStringLength

public static int getStringLength(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
Returns:
the length of the string in Unicode code points

getStringValue

public final String getStringValue()
Get the string value as a String
Specified by:
getStringValue in interface Item
getStringValue in interface ValueRepresentation
Overrides:
getStringValue in interface AtomicValue

getStringValueCS

public final 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
getStringValueCS in interface ValueRepresentation
Overrides:
getStringValueCS in interface AtomicValue

getXPathComparable

public Object getXPathComparable(boolean ordered,
                                 StringCollator collator,
                                 XPathContext context)
Get an object value that implements the XPath equality and ordering comparison semantics for this value. If the ordered parameter is set to true, the result will be a Comparable and will support a compareTo() method with the semantics of the XPath lt/gt operator, provided that the other operand is also obtained using the getXPathComparable() method. In all cases the result will support equals() and hashCode() methods that support the semantics of the XPath eq operator, again provided that the other operand is also obtained using the getXPathComparable() method. A context argument is supplied for use in cases where the comparison semantics are context-sensitive, for example where they depend on the implicit timezone or the default collation.
Overrides:
getXPathComparable in interface AtomicValue
Parameters:
ordered - true if an ordered comparison is required. In this case the result is null if the type is unordered; in other cases the returned value will be a Comparable.
collator - Collation to be used for comparing strings
context - the XPath dynamic evaluation context, used in cases where the comparison is context sensitive
Returns:
an Object whose equals() and hashCode() methods implement the XPath comparison semantics with respect to this atomic value. If ordered is specified, the result will either be null if no ordering is defined, or will be a Comparable

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
Returns:
true if the string is zero length

iterateCharacters

public UnfailingIterator iterateCharacters()
Iterate over a string, returning a sequence of integers representing the Unicode code-point values
Returns:
an iterator over the characters (Unicode code points) in the string

makeRestrictedString

public static ConversionResult makeRestrictedString(CharSequence value,
                                                    BuiltInAtomicType typeLabel,
                                                    NameChecker checker)
Factory method to create a string value belonging to a built-in type derived from string
Parameters:
value - the String value. Null is taken as equivalent to "".
typeLabel - the required type, must be a built in type derived from xs:string
checker - a NameChecker if validation is required, null if the caller already knows that the value is valid
Returns:
either the required StringValue if the value is valid, or a ValidationFailure encapsulating the error message if not.

makeStringValue

public static StringValue makeStringValue(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

setStringValueCS

public final void setStringValueCS(CharSequence value)
Set the value of the item as a CharSequence.

For system use only. In principle, a StringValue is immutable. However, in special circumstances, if it is newly constructed, the content can be changed to reflect the effect of the whiteSpace facet.

Parameters:
value - the value of the string

toString

public String toString()
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 interface AtomicValue

validate

public static ValidationFailure validate(BuiltInAtomicType typeLabel,
                                         CharSequence val,
                                         NameChecker checker)
Validate that the string conforms to the rules for a built-in subtype of xs:string
Parameters:
typeLabel - the built-in atomic type against which the string should be validated
val - the string to be validated
checker - object that checks names against the XML 1.0 or XML 1.1 rules as appropriate
Returns:
null if the value is OK, otherwise a ValidationException containing details of the failure