Package 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`, `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

    Nested Classes
    Modifier and Type | Class | 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.
    `static class` | `StringValue.UnicodeCharacterIterator` |

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static StringValue` | `EMPTY_STRING` |
    `static StringValue` | `FALSE` |
    `static StringValue` | `SINGLE_SPACE` |
    `static StringValue` | `TRUE` |
    `protected java.lang.CharSequence` | `value` |

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

      `typeLabel`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `StringValue()` | Protected constructor for use by subtypes
    `` | `StringValue​(java.lang.CharSequence value)` | Constructor.
    `` | `StringValue​(java.lang.CharSequence value, AtomicType typeLabel)` | Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | 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` | `copyAsSubType​(AtomicType typeLabel)` | Create a copy of this atomic value, with a different type label
    `static java.lang.String` | `diagnosticDisplay​(java.lang.String s)` | Produce a diagnostic representation of the contents of the string
    `boolean` | `effectiveBooleanValue()` | Get the effective boolean value of a string
    `boolean` | `equals​(java.lang.Object other)` | Determine if two AtomicValues are equal, according to XPath rules.
    `static int[]` | `expand​(java.lang.CharSequence s)` | Expand a string containing surrogate pairs into an array of 32-bit characters
    `java.lang.CharSequence` | `getPrimitiveStringValue()` | Get the string value as a CharSequence
    `BuiltInAtomicType` | `getPrimitiveType()` | Determine the primitive type of the value.
    `java.lang.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​(java.lang.CharSequence s)` | Get the length of a string, as defined in XPath.
    `int` | `getStringLengthUpperBound()` | Get an upper bound on the length of the string in Unicode codepoints.
    `UnicodeString` | `getUnicodeString()` | Get a UnicodeString value representing the same characters as this string.
    `AtomicMatchKey` | `getXPathComparable​(boolean ordered, StringCollator collator, int implicitTimezone)` | Get an object value that implements the XPath equality and ordering comparison semantics for this value.
    `int` | `hashCode()` |
    `static boolean` | `isEmpty​(java.lang.CharSequence string)` | Utility method to test whether a CharSequence is empty
    `boolean` | `isIdentical​(AtomicValue 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.
    `AtomicIterator<Int64Value>` | `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.
    `void` | `setContainsNoSurrogates()` | Assert that the string is known to contain no surrogate pairs
    `void` | `setStringValueCS​(java.lang.CharSequence value)` | Set the value of the item as a CharSequence.
    `java.lang.String` | `toShortString()` | Provide a short string showing the contents of the item, suitable for use in error messages
    `java.lang.String` | `toString()` | Get string value.

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

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

    - ### Methods inherited from class java.lang.Object

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

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

      `asIterable, concatenate, containsNode, materialize`

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

      `isStreamed, reduce, subsequence`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

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

      `makeRepeatable`

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

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

    - #### StringValue

          public StringValue​(java.lang.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​(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

    - #### isEmpty

          public static boolean isEmpty​(java.lang.CharSequence string)

      Utility method to test whether a CharSequence is empty
      Parameters:
        `string` - the input CharSequence
      Returns:
        true if the CharSequence is empty

    - #### getPrimitiveStringValue

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

    - #### getStringLengthUpperBound

          public int getStringLengthUpperBound()

      Get an upper bound on the length of the string in Unicode codepoints.
      Returns:
        a value N such that getStringLength <= N. In practice, if the string is held as UTF16 codepoints this will be the length in UTF16 codepoints; if it is held in Unicode codepoints, it will be the length in Unicode codepoints

    - #### getUnicodeString

          public UnicodeString getUnicodeString()

      Get a UnicodeString value representing the same characters as this string. This is a memo-function; the value is computed the first time it is needed, and is cached for subsequent reuse
      Returns:
        the corresponding UnicodeString

    - #### 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
      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 AtomicIterator<Int64Value> 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 static int[] expand​(java.lang.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 java.lang.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 AtomicMatchKey getXPathComparable​(boolean ordered,
                                                   StringCollator collator,
                                                   int implicitTimezone)

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

    - #### equals

          public boolean equals​(java.lang.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:
        `java.lang.ClassCastException` - always

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

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

      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`

    - #### 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
      Returns:
        a depiction of the item suitable for use in error messages

    - #### getSchemaComparable

          public java.lang.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 interface `AtomicSequence`
      Specified by:
        `getSchemaComparable` in class `AtomicValue`
      Returns:
        a Comparable that follows XML Schema comparison rules

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

    - #### diagnosticDisplay

          public static java.lang.String diagnosticDisplay​(java.lang.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