Package 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
An atomic value of type xs:string
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionfinal class
CharacterIterator is used to iterate over the characters in a string, returning them as integers representing the Unicode code-point. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringValue
static final StringValue
protected int
static final StringValue
static final StringValue
protected CharSequence
Fields inherited from class net.sf.saxon.value.AtomicValue
typeLabel
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
ConstructorsModifierConstructorDescriptionprotected
Protected constructor for use by subtypesStringValue
(CharSequence value) Constructor. -
Method Summary
Modifier and TypeMethodDescriptionboolean
codepointEquals
(StringValue other) Test whether this StringValue is equal to another under the rules of the codepoint collationboolean
Determine whether the string contains surrogate pairsstatic CharSequence
contract
(int[] codes, int used) Contract an array of integers containing Unicode codepoints into a Java stringconvertPrimitive
(BuiltInAtomicType requiredType, boolean validate, XPathContext context) Convert a value to another primitive data type, with control over how validation is handled.static ConversionResult
convertStringToAtomicType
(CharSequence value, AtomicType targetType, NameChecker checker) Convert the value to a given type.static ConversionResult
convertStringToBuiltInType
(CharSequence value, BuiltInAtomicType requiredType, NameChecker checker) Convert a string value to another built-in data type, with control over how validation is handled.copyAsSubType
(AtomicType typeLabel) Create a copy of this atomic value, with a different type labelstatic String
Produce a diagnostic representation of the contents of the stringboolean
Get the effective boolean value of a stringboolean
Determine if two AtomicValues are equal, according to XPath rules.int[]
expand()
Expand a string containing surrogate pairs into an array of 32-bit charactersstatic int[]
Expand a string containing surrogate pairs into an array of 32-bit charactersDetermine the primitive type of the value.Get a Comparable value that implements the XML Schema comparison semantics for this value.int
Get the length of this string, as defined in XPath.static int
Get the length of a string, as defined in XPath.final String
Get the string value as a Stringfinal CharSequence
Get the value of the item as a CharSequence.getXPathComparable
(boolean ordered, StringCollator collator, XPathContext context) Get an object value that implements the XPath equality and ordering comparison semantics for this value.boolean
Determine whether the string is a zero-length string.Iterate over a string, returning a sequence of integers representing the Unicode code-point valuesstatic ConversionResult
makeRestrictedString
(CharSequence value, BuiltInAtomicType typeLabel, NameChecker checker) Factory method to create a string value belonging to a built-in type derived from stringstatic StringValue
makeStringValue
(CharSequence value) Factory method.final void
setStringValueCS
(CharSequence value) Set the value of the item as a CharSequence.toString()
Convert to Java object (for passing to external functions)static ValidationFailure
validate
(BuiltInAtomicType typeLabel, CharSequence val, NameChecker checker) Validate that the string conforms to the rules for a built-in subtype of xs:stringMethods inherited from class net.sf.saxon.value.AtomicValue
asAtomic, checkPermittedContents, convert, convert, getCardinality, getComponent, getItemType, getLength, 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, makeQNameValue, reduce, stringToNumber
-
Field Details
-
EMPTY_STRING
-
SINGLE_SPACE
-
TRUE
-
FALSE
-
value
-
length
protected int length
-
-
Constructor Details
-
StringValue
protected StringValue()Protected constructor for use by subtypes -
StringValue
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 Details
-
copyAsSubType
Create a copy of this atomic value, with a different type label- Specified by:
copyAsSubType
in classAtomicValue
- 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
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 classAtomicValue
- Returns:
- the primitive type
-
makeStringValue
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
Get the string value as a String- Specified by:
getStringValue
in interfaceItem
- Specified by:
getStringValue
in interfaceValueRepresentation
- Specified by:
getStringValue
in classAtomicValue
- Returns:
- the string value of the item
- See Also:
-
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 interfaceItem
- Specified by:
getStringValueCS
in interfaceValueRepresentation
- Overrides:
getStringValueCS
in classAtomicValue
- Returns:
- the string value of the item
- See Also:
-
setStringValueCS
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, XPathContext context) Convert a value to another primitive data type, with control over how validation is handled.- Specified by:
convertPrimitive
in classAtomicValue
- Parameters:
requiredType
- type code of the required atomic typevalidate
- 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
- XPath dynamic context. Used only where the target type is one such as NCName whose definition is context-sensitive- 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, 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 convertedrequiredType
- the required atomic typechecker
- 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
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, 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:
value
- the value to be convertedtargetType
- the type to which the value is to be convertedchecker
- 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
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
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
-
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
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
Contract an array of integers containing Unicode codepoints into a Java string- Parameters:
codes
- an array of integers representing the Unicode code pointsused
- the number of items in the array that are actually used- Returns:
- the constructed string
-
getXPathComparable
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 classAtomicValue
- 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 stringscontext
- 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
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 classAtomicValue
- 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
-
codepointEquals
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 classAtomicValue
- Returns:
- true if the string has length greater than zero
-
toString
Convert to Java object (for passing to external functions)- Overrides:
toString
in classAtomicValue
-
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:stringchecker
- 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 validatedval
- the string to be validatedchecker
- 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
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 classAtomicValue
- Returns:
- a Comparable that follows XML Schema comparison rules
-
diagnosticDisplay
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
-