## 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, Comparable, SequenceIterable, Item, ValueRepresentation

Direct Known Subclasses:
  AnyURIValue, UntypedAtomicValue

    public class StringValue

extends AtomicValue

An atomic value of type xs:string

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`
`static StringValue` `SINGLE_SPACE`
`static StringValue` `TRUE`

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(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
`AtomicValue` `convertPrimitive(BuiltInAtomicType requiredType, boolean validate, XPathContext context)` Convert a value to another primitive data type, with control over how validation is handled.
`static AtomicValue` `convertStringToAtomicType(CharSequence value, AtomicType targetType, NameChecker checker)` Convert the value to a given type.
`static AtomicValue` `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` `copy(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(Object other)` Determine if two StringValues are equal, according to XML Schema 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.
`Comparable` `getXPathComparable()` Get a Comparable value that implements the XPath ordering comparison semantics for this value.
`int` `hashCode()` Return a hash code to support the equals() function
`boolean` `isZeroLength()` Determine whether the string is a zero-length string.
`SequenceIterator` `iterateCharacters()` Iterate over a string, returning a sequence of integers representing the Unicode code-point values
`static AtomicValue` `makeRestrictedString(CharSequence value, AtomicType 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.

Methods inherited from class net.sf.saxon.value.AtomicValue
`checkPermittedContents, convert, convert, getCardinality, getComponent, getItemType, getLength, getTypedValue, getTypeLabel, hasBuiltInType, isMultiValued, itemAt, iterate, process, setTypeLabel`

Methods inherited from class net.sf.saxon.value.Value
`asItem, asItem, asIterator, asValue, compareTo, convert, convertJavaObjectToXPath, fromItem, getCanonicalLexicalRepresentation, getIterator, iterate, makeQNameValue, reduce, stringToNumber`

Methods inherited from class java.lang.Object
`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

Constructor Detail

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

### copy

    public AtomicValue copy(AtomicType typeLabel)

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

  Specified by:
    `copy` 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.

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

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

### getStringValue

    public final String getStringValue()

  Get the string value as a String

  Specified by:
    `getStringValue` in interface `Item`
  Specified by:
    `getStringValue` in interface `ValueRepresentation`
  Specified by:
    `getStringValue` in class `AtomicValue`
  Returns:
    the string value of the item
  See Also:
    `Item.getStringValueCS()`

### 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`
  Specified by:
    `getStringValueCS` in interface `ValueRepresentation`
  Overrides:
    `getStringValueCS` in class `AtomicValue`
  Returns:
    the string value of the item
  See Also:
    `Item.getStringValue()`

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

### convertPrimitive

    public AtomicValue convertPrimitive(BuiltInAtomicType requiredType,
                                        boolean validate,
                                        XPathContext context)

  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
    `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` -
  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 AtomicValue 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 `ValidationErrorValue`. The caller must check for this condition. No exception is thrown, instead the exception will be encapsulated within the ValidationErrorValue.

### convertStringToAtomicType

    public static AtomicValue 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:
    `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 `ValidationErrorValue` 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

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

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

### containsSurrogatePairs

    public boolean containsSurrogatePairs()

  Determine whether the string contains surrogate pairs

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

### iterateCharacters

    public SequenceIterator iterateCharacters()

  Iterate over a string, returning a sequence of integers representing the Unicode code-point values

### expand

    public int[] expand()

  Expand a string containing surrogate pairs into an array of 32-bit characters

### expand

    public static int[] expand(CharSequence s)

  Expand a string containing surrogate pairs into an array of 32-bit characters

### contract

    public static CharSequence contract(int[] codes,
                                        int used)

  Contract an array of integers containing Unicode codepoints into a Java string

### getXPathComparable

    public Comparable getXPathComparable()

  Get a Comparable value that implements the XPath ordering comparison semantics for this value. Returns null if the value is not comparable according to XPath rules. The default implementation returns null. This is overridden for types that allow ordered comparisons in XPath: numeric, boolean, string, date, time, dateTime, yearMonthDuration, dayTimeDuration, and anyURI.

  Overrides:
    `getXPathComparable` in class `AtomicValue`

### equals

    public boolean equals(Object other)

  Determine if two StringValues are equal, according to XML Schema rules. (This method is not used for XPath comparisons, which are always under the control of a collation.)

  Overrides:
    `equals` in class `Value`
  Throws:
    `ClassCastException` - if the values are not comparable

### hashCode

    public int hashCode()

  Description copied from class: `Value`
  Return a hash code to support the equals() function

  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

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

### convertToJava

    public Object convertToJava(Class target,
                                XPathContext context)
                         throws XPathException

  Convert to Java object (for passing to external functions)

  Overrides:
    `convertToJava` in class `Value`
  Throws:
    `XPathException`

### 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 AtomicValue makeRestrictedString(CharSequence value,
                                                   AtomicType 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 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 an ErrorValue encapsulating the error message if not.

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

Copyright (C) Michael H. Kay. All rights reserved.