net.sf.saxon.value

Class StringValue

java.lang.Object

net.sf.saxon.value.AtomicValue

net.sf.saxon.value.StringValue

All Implemented Interfaces:

java.lang.Iterable<AtomicValue>, AtomicSequence, GroundedValue, IdentityComparable, Item, Sequence, ConversionResult

Direct Known Subclasses:

AnyURIValue

public class StringValue
extends AtomicValue

An atomic value of type xs:string. This class is also used for types derived from xs:string. Subclasses of StringValue are used for xs:untypedAtomic and xs:anyURI values.

Internally the value is held as a wrapper around a UnicodeString, which allows a variety of implementations

The equals and compareTo methods support ordering in codepoint collation sequence.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	StringValue.Builder
static 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
protected UnicodeString	content
static StringValue	EMPTY_STRING
static StringValue	FALSE
static StringValue	SINGLE_SPACE
static StringValue	TRUE
static StringValue	ZERO_LENGTH_UNTYPED

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

typeLabel

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	StringValue() Protected constructor for use by subtypes
	StringValue(java.lang.String value) Constructor from String.
	StringValue(java.lang.String value, AtomicType typeLabel) Constructor from String.
	StringValue(UnicodeString content) Construct an instance that wraps a supplied UnicodeString, with the default type xs:string
	StringValue(UnicodeString content, AtomicType type) Construct an instance that wraps a supplied UnicodeString, with a supplied atomic type

Method Summary

Modifier and Type	Method and Description
static StringValue	bmp(java.lang.String content) Construct a StringValue whose content is known to consist entirely of BMP characters (codepoints less than 65536, with no surrogate pairs)
IntIterator	codePoints() Get an iterator over the Unicode codepoints in the value.
StringValue	copyAsSubType(AtomicType typeLabel) Create a copy of this atomic value, with a different type label
boolean	effectiveBooleanValue() Get the effective boolean value of a string
boolean	equals(java.lang.Object o) Test whether this StringValue is equal to another under the rules of the codepoint collation.
Base64BinaryValue	getCodepointCollationKey() Get an atomic value that encapsulates this match key.
UnicodeString	getContent() Get the content of this StringItem
UnicodeString	getPrimitiveStringValue() Convert the value to a string, using the serialization rules for the primitive type.
BuiltInAtomicType	getPrimitiveType() Determine the primitive type of the value.
UnicodeString	getUnicodeStringValue() Get the value of the item as a UnicodeString.
XPathComparable	getXPathComparable(StringCollator collator, int implicitTimezone) Get an object value that implements the XPath equality and ordering comparison semantics for this value.
AtomicMatchKey	getXPathMatchKey(StringCollator collator, int implicitTimezone) Get an object value that implements the XPath equality and ordering comparison semantics for this value.
int	hashCode() Returns a hash code value for the object.
boolean	isEmpty() Determine whether the string is a zero-length string.
boolean	isIdentical(AtomicValue v) Determine whether two atomic values are identical, as determined by XML Schema rules.
AtomicIterator	iterateCharacters() Iterate over a string, returning a sequence of integers representing the Unicode code-point values
long	length() Get the length of this string, in code points
int	length32() Get the length of this string, in code points
static StringValue	makeStringValue(java.lang.CharSequence value) Factory method.
static StringValue	makeUntypedAtomic(UnicodeString value) Factory method for untyped atomic values
static StringValue	makeUStringValue(UnicodeString value)
java.lang.String	toShortString() Provide a short string showing the contents of the item, suitable for use in error messages
java.lang.String	toString() Display as a string.

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

asAtomic, asMapKey, atomize, checkPermittedContents, checkValidInJavascript, getCanonicalLexicalRepresentation, getCardinality, getComponent, getGenre, getItemType, getLength, getUType, head, identityHashCode, isIdentical, isNaN, isUntypedAtomic, itemAt, iterate, iterator, setTypeLabel, show

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.saxon.om.Item

getStringValue, isStreamed, reduce, subsequence

Methods inherited from interface net.sf.saxon.om.GroundedValue

asIterable, concatenate, containsNode, materialize

Methods inherited from interface net.sf.saxon.om.Sequence

makeRepeatable

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

content

protected UnicodeString content

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

ZERO_LENGTH_UNTYPED

public static final StringValue ZERO_LENGTH_UNTYPED

Constructor Detail

StringValue

protected StringValue()

Protected constructor for use by subtypes

StringValue

public StringValue(UnicodeString content)

Construct an instance that wraps a supplied UnicodeString, with the default type xs:string

Parameters:

content - the UnicodeString to wrap

StringValue

public StringValue(UnicodeString content,
                   AtomicType type)

Construct an instance that wraps a supplied UnicodeString, with a supplied atomic type

Parameters:

content - the UnicodeString to wrap

type - the requested atomic type

StringValue

public StringValue(java.lang.String value)

Constructor from String. Creates an instance of xs:string.

Parameters:

value - the String value.

StringValue

public StringValue(java.lang.String value,
                   AtomicType typeLabel)

Constructor from String. 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.

typeLabel - the type of the value to be created. The caller must ensure that this is a type derived from xs:string and that the string is valid against this type.

Method Detail

makeUntypedAtomic

public static StringValue makeUntypedAtomic(UnicodeString value)

Factory method for untyped atomic values

Parameters:

value - the string value

Returns:

a new untyped atomic value around this string

copyAsSubType

public StringValue copyAsSubType(AtomicType typeLabel)

Create a copy of this atomic value, with a different type label

Specified by:

copyAsSubType in class AtomicValue

Parameters:

typeLabel - the type label of the new copy. The caller is responsible for checking that the value actually conforms to this type.

Returns:

the copied value

bmp

public static StringValue bmp(java.lang.String content)

Construct a StringValue whose content is known to consist entirely of BMP characters (codepoints less than 65536, with no surrogate pairs)

Parameters:

content - the content of the string, which the caller guarantees to contain no surrogate pairs

Returns:

the corresponding StringItem

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.

Specified by:

getPrimitiveType in class AtomicValue

Returns:

the primitive type

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

makeUStringValue

public static StringValue makeUStringValue(UnicodeString value)

getPrimitiveStringValue

public UnicodeString getPrimitiveStringValue()

Description copied from class: AtomicValue

Convert the value to a string, using the serialization rules for the primitive type. This is the result of conversion to a string except that postprocessing defined by the saxon:preprocess facet is not (yet) applied.

Specified by:

getPrimitiveStringValue in class AtomicValue

Returns:

the value converted to a string according to the rules for the primitive type

getContent

public UnicodeString getContent()

Get the content of this StringItem

Returns:

the content

length

public long length()

Get the length of this string, in code points

Returns:

the length of the string in Unicode code points

length32

public int length32()

Get the length of this string, in code points

Returns:

the length of the string in Unicode code points, provided that it is less than 2^31

Throws:

java.lang.UnsupportedOperationException - if the string contains more than 2^31 code points

isEmpty

public boolean isEmpty()

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

getXPathMatchKey

public AtomicMatchKey getXPathMatchKey(StringCollator collator,
                                       int implicitTimezone)

Get an object value that implements the XPath equality and ordering comparison semantics for this value. 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.

Specified by:

getXPathMatchKey in class AtomicValue

Parameters:

collator - Collation to be used for comparing strings

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

getCodepointCollationKey

public Base64BinaryValue getCodepointCollationKey()

Get an atomic value that encapsulates this match key. Needed to support the collation-key() function.

Returns:

an atomic value that encapsulates this match key

codePoints

public IntIterator codePoints()

Get an iterator over the Unicode codepoints in the value. These will always be full codepoints, never surrogates (surrogate pairs are combined where necessary).

Returns:

a sequence of Unicode codepoints

hashCode

public int hashCode()

Description copied from class: AtomicValue

Returns a hash code value for the object.

Overrides:

hashCode in class AtomicValue

equals

public boolean equals(java.lang.Object o)

Test whether this StringValue is equal to another under the rules of the codepoint collation. The type annotation is ignored.

Overrides:

equals in class AtomicValue

Parameters:

o - the value to be compared with this value

Returns:

true if the strings are equal on a codepoint-by-codepoint basis

effectiveBooleanValue

public boolean effectiveBooleanValue()

Get the effective boolean value of a string

Specified by:

effectiveBooleanValue in interface GroundedValue

Overrides:

effectiveBooleanValue in class AtomicValue

Returns:

true if the string has length greater than zero

toString

public java.lang.String toString()

Display as a string. In general toString() for an atomic value displays the value as it would be written in XPath: so this method returns the string with delimiting quotes.

Overrides:

toString in class AtomicValue

See Also:

getUnicodeStringValue()

getUnicodeStringValue

public UnicodeString getUnicodeStringValue()

Description copied from class: AtomicValue

Get the value of the item as a UnicodeString.

Specified by:

getUnicodeStringValue in interface AtomicSequence

Specified by:

getUnicodeStringValue in interface GroundedValue

Specified by:

getUnicodeStringValue in interface Item

Overrides:

getUnicodeStringValue in class AtomicValue

Returns:

the string value (the result of casting to string using the XPath casting rules)

toShortString

public java.lang.String toShortString()

Description copied from interface: Item

Provide a short string showing the contents of the item, suitable for use in error messages

Specified by:

toShortString in interface GroundedValue

Specified by:

toShortString in interface Item

Overrides:

toShortString in class AtomicValue

Returns:

a depiction of the item suitable for use in error messages

getXPathComparable

public XPathComparable getXPathComparable(StringCollator collator,
                                          int implicitTimezone)
                                   throws NoDynamicContextException

Description copied from class: AtomicValue

Get an object value that implements the XPath equality and ordering comparison semantics for this value. A collation is supplied for comparing strings, and an implicit timezone for comparing date/time values that have no saved timezone. An atomic value may return itself as the result, provided that its ordering rules are independent of the collation and timezone, and provided that it implements the XPathComparable interface: which means that its compareTo, equals, and hashCode methods must be compatible with the rules for XPath value comparisons.

Specified by:

getXPathComparable in class AtomicValue

Parameters:

collator - the collation to be used when comparing strings

implicitTimezone - the implicit timezone in the dynamic context, used when comparing dates/times with and without timezone

Returns:

an Object that implements the XPath value comparison semantics with respect to this atomic value. For an atomic type that is not ordered (according to XPath rules), return null.

Throws:

NoDynamicContextException - if the supplied implicit timezone is "NO_TIMEZONE" (meaning unknown), and the implicit timezone is actually required because the value in question is a date/time value with no timezone. This can cause a failure to evaluate expressions statically (because the implicit timezone is not known statically), and it will then be caught, meaning that the expression has to be evaluated dynamically.

isIdentical

public boolean isIdentical(AtomicValue v)

Determine whether two atomic 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.

NaN is identical to itself.

Overrides:

isIdentical in class AtomicValue

Parameters:

v - the other value to be compared with this one

Returns:

true if the two values are identical, false otherwise.