## 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:
  Serializable, PullEvent, SequenceIterable, GroundedValue, Item, ValueRepresentation, 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.

See Also:
  Serialized Form

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.

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, ConversionRules rules)` Convert a value to another primitive data type, with control over how validation is handled.
`static ConversionResult` `convertStringToAtomicType(CharSequence value, AtomicType targetType, ConversionRules rules)` Convert the value to a given type.
`static ConversionResult` `convertStringToBuiltInType(CharSequence value, BuiltInAtomicType requiredType, ConversionRules rules)` Convert a string value to another built-in data type, with control over how validation is handled.
`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
`String` `getPrimitiveStringValue()` Get the string value as a String
`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 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` `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.
`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, convert, 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, iterate, 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 "".

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 String getPrimitiveStringValue()

  Get the string value as a String

  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

### convertPrimitive

    public ConversionResult convertPrimitive(BuiltInAtomicType requiredType,
                                             boolean validate,
                                             ConversionRules rules)

  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. This must not be a namespace-sensitive 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.
    `rules` - The conversion rules to be applied
  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 ConversionResult convertStringToBuiltInType(CharSequence value,
                                                              BuiltInAtomicType requiredType,
                                                              ConversionRules rules)

  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. This must not be a namespace-sensitive type.
    `rules` -
  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.

### convertStringToAtomicType

    public static ConversionResult convertStringToAtomicType(CharSequence value,
                                                             AtomicType targetType,
                                                             ConversionRules rules)

  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. This must not be a namespace-sensitive type.
    `rules` - The conversion rules to be applied
  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.

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

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

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

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

### 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-2010 Saxonica Limited. All rights reserved.