net.sf.saxon.value
Class StringValue

java.lang.Object
  extended by net.sf.saxon.value.Value<AtomicValue>
      extended by net.sf.saxon.value.AtomicValue
          extended by net.sf.saxon.value.StringValue
All Implemented Interfaces:
PullEvent, GroundedValue<AtomicValue>, Item<AtomicValue>, ValueRepresentation<AtomicValue>, ConversionResult
Direct Known Subclasses:
AnyURIValue, UntypedAtomicValue

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.


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
           
protected  boolean noSurrogates
           
static StringValue SINGLE_SPACE
           
static StringValue TRUE
           
protected  CharSequence value
           
 
Fields inherited from class net.sf.saxon.value.AtomicValue
typeLabel
 
Fields inherited from class net.sf.saxon.value.Value
INDETERMINATE_ORDERING
 
Fields inherited from interface net.sf.saxon.om.ValueRepresentation
EMPTY_VALUE_ARRAY
 
Constructor Summary
protected StringValue()
          Protected constructor for use by subtypes
  StringValue(CharSequence value)
          Constructor.
  StringValue(CharSequence value, AtomicType typeLabel)
          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
 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
 CharSequence getPrimitiveStringValue()
          Get the string value as a CharSequence
 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.
 Object getXPathComparable(boolean ordered, StringCollator collator, XPathContext context)
          Get an object value that implements the XPath equality and ordering comparison semantics for this value.
 int hashCode()
           
 boolean isIdentical(Value v)
          Determine whether two atomic values are identical, as determined by XML Schema rules.
 boolean isKnownToContainNoSurrogates()
          Ask whether the string is known to contain no surrogate pairs.
 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 StringValue makeStringValue(CharSequence value)
          Factory method.
 void setContainsNoSurrogates()
          Assert that the string is known to contain no surrogate pairs
 void setStringValueCS(CharSequence value)
          Set the value of the item as a CharSequence.
 String toString()
          Get string value.
 
Methods inherited from class net.sf.saxon.value.AtomicValue
asAtomic, checkPermittedContents, getCardinality, getComponent, getItemType, getLength, getStringValue, getStringValueCS, getTypedValue, getTypeLabel, isNaN, itemAt, iterate, process, setTypeLabel, subsequence
 
Methods inherited from class net.sf.saxon.value.Value
asItem, asItem, asIterator, asValue, convertToJava, fromItem, getCanonicalLexicalRepresentation, getIterator, getSequenceLength, reduce
 
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 CharSequence value

noSurrogates

protected boolean noSurrogates
Constructor Detail

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

StringValue

public StringValue(CharSequence value,
                   AtomicType typeLabel)
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.
typeLabel - the type of the value to be created. The caller must ensure that this is a type derived from string and that the string is valid against this type.
Method Detail

setContainsNoSurrogates

public void setContainsNoSurrogates()
Assert that the string is known to contain no surrogate pairs


copyAsSubType

public AtomicValue 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

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

getPrimitiveStringValue

public final CharSequence getPrimitiveStringValue()
Get the string value as a CharSequence

Specified by:
getPrimitiveStringValue in class AtomicValue
Returns:
the value converted to a string according to the rules for the primitive type

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

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

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

containsSurrogatePairs

public boolean containsSurrogatePairs()
Determine whether the string contains surrogate pairs

Returns:
true if the string contains any non-BMP characters

isKnownToContainNoSurrogates

public boolean isKnownToContainNoSurrogates()
Ask whether the string is known to contain no surrogate pairs.

Returns:
true if it is known to contain no surrogates, false if the answer is not known

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

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

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

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.

Specified by:
getXPathComparable in class 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

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

Specified by:
equals in class AtomicValue
Parameters:
other - the other value
Returns:
true if the other operand is an atomic value and the two values are equal as defined by the XPath eq operator
Throws:
ClassCastException - always

hashCode

public int hashCode()
Overrides:
hashCode in class Value<AtomicValue>

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

effectiveBooleanValue

public boolean effectiveBooleanValue()
Get the effective boolean value of a string

Overrides:
effectiveBooleanValue in class AtomicValue
Returns:
true if the string has length greater than zero

toString

public 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

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.

Specified by:
getSchemaComparable in class AtomicValue
Returns:
a Comparable that follows XML Schema comparison rules

isIdentical

public boolean isIdentical(Value 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.

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


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