Package net.sf.saxon.str

Class UnicodeString

java.lang.Object
net.sf.saxon.str.UnicodeString
All Implemented Interfaces:
Comparable<UnicodeString>, AtomicMatchKey
Direct Known Subclasses:
BMPString, EmptyUnicodeString, Slice16, Slice24, Slice8, StringView, Twine16, Twine24, Twine8, UnicodeChar, WhitespaceString, ZenoString
public abstract class UnicodeString extends Object implements AtomicMatchKey, Comparable<UnicodeString>
A UnicodeString is a sequence of Unicode codepoints that supports codepoint addressing.

The interface is future-proofed to support code points in the range 0 to 2^31, and string lengths of up to 2^63 characters. Implementations may (and do) impose lower limits.

  • Constructor Summary

    Constructors
    Constructor
    Description
    UnicodeString()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    AtomicValue
    asAtomic()
    Get an atomic value that encapsulates this match key.
    protected void
    checkSubstringBounds(long start, long end)
     
    abstract int
    codePointAt(long index)
    Get the code point at a given position in the string
    abstract IntIterator
    codePoints()
    Get an iterator over the code points present in the string.
    int
    compareTo(UnicodeString other)
    Compare this string to another using codepoint comparison
    UnicodeString
    concat(UnicodeString other)
    Concatenate with another string, returning a new string
    UnicodeString
    economize()
     
    boolean
    equals(Object obj)
     
    long
    estimatedLength()
    Get the estimated length of the string, suitable for space allocation.
    abstract int
    getWidth()
    Get the number of bits needed to hold all the characters in this string
    int
    hashCode()
    Compute a hashCode.
    boolean
    hasSubstring(UnicodeString other, long offset)
    Ask whether this string has another string as its content starting at a given offset
    long
    indexOf(int codePoint)
    Get the position of the first occurrence of the specified codepoint, starting the search at the beginning
    abstract long
    indexOf(int codePoint, long from)
    Get the position of the first occurrence of the specified codepoint, starting the search at a given position in the string
    long
    indexOf(UnicodeString other, long from)
    Get the first position, at or beyond from, where another string appears as a substring of this string, comparing codepoints.
    abstract long
    indexWhere(IntPredicate predicate, long from)
    Get the position of the first occurrence of a codepoint that matches a supplied predicate, starting the search at a given position in the string
    boolean
    isEmpty()
    Ask whether the string is empty
    abstract long
    length()
    Get the length of the string
    int
    length32()
    Get the length of the string, provided it is less than 2^31 characters
    UnicodeString
    prefix(long end)
    Get a substring of this string, starting at position 0, with a given end position
    static int
    requireInt(long value)
    Utility method for use where strings longer than 2^31 characters cannot yet be handled.
    static int
    requireNonNegativeInt(long value)
    Utility method for use where strings longer than 2^31 characters cannot yet be handled; and where negative offsets are to be treated as zero
    UnicodeString
    substring(long start)
    Get a substring of this codepoint sequence, with a given start position, finishing at the end of the string
    abstract UnicodeString
    substring(long start, long end)
    Get a substring of this string, with a given start and end position
    UnicodeString
    tidy()
    Ensure that the implementation is capable of counting codepoints in the string.
    void
    verifyCharacters()
    Diagnostic method: verify that all the characters in the string are valid XML codepoints

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • UnicodeString

      public UnicodeString()

  • Method Details

    • tidy

      public UnicodeString tidy()
      Ensure that the implementation is capable of counting codepoints in the string. This is normally a null operation, but it may cause internal reorganisation.
      Returns:
      this UnicodeString, or another that represents the same sequence of characters.

    • economize

      public UnicodeString economize()

    • length

      public abstract long length()
      Get the length of the string
      Returns:
      the number of code points in the string

    • length32

      public int length32()
      Get the length of the string, provided it is less than 2^31 characters
      Returns:
      the length of the string if it fits within a Java int
      Throws:
      UnsupportedOperationException - if the string is longer than 2^31 characters

    • estimatedLength

      public long estimatedLength()
      Get the estimated length of the string, suitable for space allocation.
      Returns:
      for a UnicodeString, the actual length of the string in codepoints

    • isEmpty

      public boolean isEmpty()
      Ask whether the string is empty
      Returns:
      true if the length of the string is zero

    • getWidth

      public abstract int getWidth()
      Get the number of bits needed to hold all the characters in this string
      Returns:
      7 for ascii characters (not used??), 8 for latin-1, 16 for BMP, 24 for general Unicode.

    • indexOf

      public long indexOf(int codePoint)
      Get the position of the first occurrence of the specified codepoint, starting the search at the beginning
      Parameters:
      codePoint - the sought codePoint
      Returns:
      the position (0-based) of the first occurrence found, or -1 if not found, counting codePoints rather than UTF16 chars.
      Throws:
      UnsupportedOperationException - if the UnicodeString has not been prepared for codePoint access

    • indexOf

      public abstract long indexOf(int codePoint, long from)
      Get the position of the first occurrence of the specified codepoint, starting the search at a given position in the string
      Parameters:
      codePoint - the sought codePoint
      from - the position from which the search should start (0-based). A negative value is treated as zero. A position beyond the end of the string results in a return value of -1 (meaning not found).
      Returns:
      the position (0-based) of the first occurrence found, or -1 if not found
      Throws:
      UnsupportedOperationException - if the UnicodeString has not been prepared for codePoint access

    • indexWhere

      public abstract long indexWhere(IntPredicate predicate, long from)
      Get the position of the first occurrence of a codepoint that matches a supplied predicate, starting the search at a given position in the string
      Parameters:
      predicate - condition that the codepoint must satisfy
      from - the position from which the search should start (0-based). A negative value is treated as zero. A position beyond the end of the string results in a return value of -1 (meaning not found).
      Returns:
      the position (0-based) of the first codepoint to match the predicate, or -1 if not found

    • indexOf

      public long indexOf(UnicodeString other, long from)
      Get the first position, at or beyond from, where another string appears as a substring of this string, comparing codepoints.
      Parameters:
      other - the other (sought) string
      from - the position from which the search should start (0-based). A negative value is treated as zero. A position beyond the end of the string results in a return value of -1 (meaning not found).
      Returns:
      the first position where the substring is found, or -1 if it is not found. Also returns -1 if from is negative, or beyond the length of the string.

    • hasSubstring

      public boolean hasSubstring(UnicodeString other, long offset)
      Ask whether this string has another string as its content starting at a given offset
      Parameters:
      other - the other string
      offset - the starting position in this string (counting in codepoints)
      Returns:
      true if the other string appears as a substring of this string starting at the given position.
      Throws:
      IndexOutOfBoundsException - if offset is less than zero or greater than the length of this string. Note that there is no exception if offset + other.length() exceeds this.length() - instead this results in a return value of false.

    • codePoints

      public abstract IntIterator codePoints()
      Get an iterator over the code points present in the string.
      Returns:
      an iterator that delivers the individual code points

    • codePointAt

      public abstract int codePointAt(long index)
      Get the code point at a given position in the string
      Parameters:
      index - the given position (0-based)
      Returns:
      the code point at the given position
      Throws:
      IndexOutOfBoundsException - if the index is out of range

    • substring

      public UnicodeString substring(long start)
      Get a substring of this codepoint sequence, with a given start position, finishing at the end of the string
      Parameters:
      start - the start position (0-based): that is, the position of the first code point to be included
      Returns:
      the requested substring
      Throws:
      IndexOutOfBoundsException - if the start position is out of range

    • substring

      public abstract UnicodeString substring(long start, long end)
      Get a substring of this string, with a given start and end position
      Parameters:
      start - the start position (0-based): that is, the position of the first code point to be included
      end - the end position (0-based): specifically, the position of the first code point not to be included
      Returns:
      the requested substring
      Throws:
      IndexOutOfBoundsException - if the start/end positions are out of range (the conditions are the same as for String.substring())

    • prefix

      public UnicodeString prefix(long end)
      Get a substring of this string, starting at position 0, with a given end position
      Parameters:
      end - the end position (0-based): specifically, the position of the first code point not to be included
      Returns:
      the requested substring
      Throws:
      IndexOutOfBoundsException - if the end position is out of range

    • concat

      public UnicodeString concat(UnicodeString other)
      Concatenate with another string, returning a new string
      Parameters:
      other - the string to be appended
      Returns:
      the result of concatenating this string followed by the other

    • checkSubstringBounds

      protected void checkSubstringBounds(long start, long end)

    • verifyCharacters

      public void verifyCharacters()
      Diagnostic method: verify that all the characters in the string are valid XML codepoints
      Throws:
      IllegalStateException - if the contents are invalid

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Compute a hashCode. All implementations of UnicodeString use compatible hash codes and the hashing algorithm is therefore identical to that for java.lang.String. This means that for strings containing Astral characters, the hash code needs to be computed by decomposing an Astral character into a surrogate pair.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code

    • compareTo

      public int compareTo(UnicodeString other)
      Compare this string to another using codepoint comparison
      Specified by:
      compareTo in interface Comparable<UnicodeString>
      Parameters:
      other - the other string
      Returns:
      -1 if this string comes first, 0 if they are equal, +1 if the other string comes first

    • asAtomic

      public AtomicValue asAtomic()
      Get an atomic value that encapsulates this match key. Needed to support the collation-key() function.
      Specified by:
      asAtomic in interface AtomicMatchKey
      Returns:
      an atomic value that encapsulates this match key

    • requireInt

      public static int requireInt(long value)
      Utility method for use where strings longer than 2^31 characters cannot yet be handled.
      Parameters:
      value - the actual value of a character position within a string, or the length of a string
      Returns:
      the value as an integer if it is within range
      Throws:
      UnsupportedOperationException - if the supplied value exceeds Integer.MAX_VALUE

    • requireNonNegativeInt

      public static int requireNonNegativeInt(long value)
      Utility method for use where strings longer than 2^31 characters cannot yet be handled; and where negative offsets are to be treated as zero
      Parameters:
      value - the actual value of a character position within a string, or the length of a string
      Returns:
      the value as an integer if it is within range
      Throws:
      UnsupportedOperationException - if the supplied value exceeds Integer.MAX_VALUE