XString (Rumi 4.0.595 API)

java.lang.Object
- com.neeve.lang.XString

All Implemented Interfaces:

Appendable, CharSequence

Direct Known Subclasses:

XAbstractPooledString, XString.ImmutableExtension
```
public class XString
extends Object
implements Appendable, CharSequence
```
Wraps an encoded set of bytes representing a string. An XString provides the ability to manipulate String values without generating the garbage associated with Java's String implementation.

Immutability of XString
An immutable XString created is immutable from the point that it is initialized. Once initialized via a setter method, an XString is threadsafe.
However, not all XStrings are threadsafe or immutable: platform created XString may not always be immutable. Applications can test for immutability and initialization of an XString via canMutate() and hasValue(). When dealing with XStrings returned by platform classes the documentation of the class should be consulted to determine what thread safety and immutability guarantees are provided. In cases where the platform doesn't guaranteed immutability, applications can make use of getTo(XString) to create an immutable version of the XString if needs be.
Character Encoding
For interoperability an XString implements Appendable and CharSequence. Currently XString only supports ascii encdodable characters when working with these interfaces, or any of the other char based methods it supports. An XString can opaquely wrap and and pass non ascii encodabled XStrings, but for performance reasons direct character manipulation of non ascii text is not supported.
CharSequence view
An XString implements CharSequence. The hashCode() and equals(Object) implementations of this view and those returned by subSequence(int, int) are not guaranteed to be remain stable when an XString is mutable or not yet initialized.
Equality and hashCode
XStrings that are immutable obey the contract for object equality and hashCode. Additionally, an XString will equal another subSequence(int, int) if they have the same value. An XString will not equal another String of the same value.

Threading:

XStrings are mutable; they along with their backing storages are not safe for mutative access by multiple threads.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`XString.ImmutableExtension` Immutable extension of an `XString` This class caches the `String` value of the `XString` to optimize the performance of `getValue` and `getAsString`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`XString`	`append(boolean value)` Appends the given boolean value in string format to the end of an `XString`.
`XString`	`append(byte[] value)` Append the given bytes bytes to the end of this `XString`.
`XString`	`append(byte[] value, int valueOffset, int valueLength)` Append the given bytes bytes to the end of this `XString`.
`XString`	`append(ByteBuffer value)` Appends the contents of the given `ByteBuffer` into this `XString`.
`XString`	`append(ByteBuffer value, int valueOffset, int valueLength)` Appends the contents of the given `ByteBuffer` into this `XString`.
`XString`	`append(char value)` Append the given char to the end of this `XString`.
`XString`	`append(char[] value)` Append the given char [] to the end of this `XString`.
`XString`	`append(char[] value, int valueOffset, int valueLength)` Append the given char [] to the end of this `XString`.
`XString`	`append(CharSequence value)` Append the given `CharSequence` to the end of this `XString`.
`Appendable`	`append(CharSequence value, int start, int end)`
`XString`	`append(long value)` Appends the given long value in String format to the end of this `XString`.
`XString`	`append(XString value)` Appends the contents of the given `XString` into this `XString`.
`boolean`	`canMutate()` Checks if an `XString` can be mutated.
`int`	`capacity()` Returns the capacity of the backing storage
`char`	`charAt(int index)` Returns the character at the given position.
`void`	`clear()` Clear the value of the `XString`.
`void`	`clear(boolean freeMemory)` Clear an `XString`.
`void`	`close()` This method should be invoked when the user is done working with an XString that it owns i.e. one that it has created for its own use or one that has been handed to the user for ownership by the Rumi runtime.
`int`	`compareTo(CharSequence other)` Compares two strings lexicographically.
`void`	`copyFrom(char[] val)` Set the value of the String to the given characters.
`void`	`copyFrom(XString value)` Set the value of an `XString` from an `XString` Equivalent to invoking `setFrom(XString)`
`void`	`copyFromMemory(long addr, int len)` Copy a serialized string from a memory address into an `XString`.
`void`	`copyFromNative(long addr, int len)` Copy a serialized string from a memory address into an `XString`.
`int`	`copyInto(ByteBuffer target, int offset)` Deprecated. Use `getTo(ByteBuffer, int)` instead
`int`	`copyInto(IOBuffer target, int offset)` Deprecated. Use `getTo(IOBuffer, int)` instead
`int`	`copyInto(IOElasticBuffer target, int offset)` Deprecated. Use `getTo(IOElasticBuffer, int)` instead
`int`	`copyInto(XString val)` Deprecated. Use `#getTo(XString`} instead
`static XString`	`create()` Create a mutable, uninitialized `XString`.
`static XString`	`create(boolean mutable, int initialCapacity)` Deprecated. Please use create(int, boolean) instead
`static XString`	`create(int initialCapacity)` Create an `XString`.
`static XString`	`create(int initialCapacity, boolean mutable)` Create an `XString`.
`static XString`	`create(short initialCapacity)` Create an `XString`.
`static XString`	`create(short initialCapacity, boolean mutable)` Create an `XString`.
`static XString`	`create(String value)` Create an immutable `XString` initialized with the given `String` value.
`static XString`	`create(String value, boolean mutable)` Create an `XString` initialized with the given `String` value.
`void`	`ensureCapacity(short val)` Ensure an `XString`s backing storage is large enough to accommodate data
`boolean`	`equals(Object object)` Test if this `XString` is equal to another `XString`.
`long`	`getAsLong()` Get an `XString` as a long value.
`long`	`getAsLong(int radix)` Get an `XString` as a long value.
`long`	`getAsLongDecimal()` Get an `XString` as a long value.
`String`	`getAsString()` Get an `XString` as a `String` value.
`int`	`getSerializedLength()` Deprecated. Use `serializedLength()` instead
`int`	`getTo(byte[] val, int offset)` Copy the serialized bytes of an `XString` into an byte array
`int`	`getTo(ByteBuffer target, int offset)` Copy the serialized bytes of an `XString` to a `ByteBuffer`
`int`	`getTo(IOBuffer target, int offset)` Copy the serialized bytes of an `XString` to an `IOBuffer`
`int`	`getTo(IOElasticBuffer target, int offset)` Copy the serialized bytes of an `XString` to an `IOElasticBuffer`
`int`	`getTo(long addr, int offset)` Copy the serialized bytes of an `XString` to a memory location
`int`	`getTo(XString val)` Copy this `XString` into another `XString`.
`String`	`getValue()` Get an `XString` as a `String` value.
`long`	`getValueAsLong()` Zero garbage method to parses the string as a long value.
`int`	`hashCode()` Return the current hash code of this `XString`.
`boolean`	`hasValue()` Get if an `XString`has a value set
`int`	`indexOf(char c)` Returns the first index of the given character in an `XString`.
`int`	`indexOf(char c, int offset)` Returns the first index of the given character in q `XString` starting from the provided offset.
`int`	`indexOf(CharSequence str)` Returns the first index of the given character sequence in an `XString`
`int`	`indexOf(CharSequence str, int offset)` Returns the first index of the given character sequence in an `XString` starting from the provided offset.
`void`	`initialize(String value)` Initializes an uninitialized `XString` with the given String value.
`void`	`initializeFrom(XString value)` Initialize an uninitialized `XString` with the given value.
`boolean`	`isEmpty()` Checks if an `XString` is empty
`boolean`	`isImmutable()` Test if this `XString` cannot be mutated.
`boolean`	`isInitialized()` Deprecated. Use `hasValue()` instead
`boolean`	`isMutable()` Get if an `XString` was marked as mutable on creation.
`boolean`	`isNull()` Return if the `XString`'s represents a null string.
`int`	`length()` Returns the length in characters of the XString.
`long`	`nativeAddress()` Return an `XString`'s backing store address.
`void`	`reset()` Deprecated. Use `clear()` instead
`int`	`serializedLength()` Return an `XString`'s serialized length.
`void`	`setCharAt(int position, char value)` Replaces the character at the given index in a with the provided value.
`void`	`setFrom(byte[] value)` Set the value of the String to the given bytes.
`void`	`setFrom(byte[] value, int valueOffset, int valueLength)` Set the value of the String to the given bytes.
`void`	`setFrom(ByteBuffer source)` Copy a serialized string from a `ByteBuffer` into an `XString`.
`void`	`setFrom(ByteBuffer source, int offset, int len)` Copy a serialized string from a `ByteBuffer` into an `XString`.
`void`	`setFrom(char[] value)` Set the value of the String to the given characters.
`void`	`setFrom(char[] value, int valueOffset, int valueLength)` Set the value of the String to the given characters.
`void`	`setFrom(CharSequence value)` Set the value of the `XString` to that of the given `CharSequence`
`void`	`setFrom(IOBuffer source, int offset, int len)` Copy a serialized string from an `IOBuffer` into an `XString`.
`void`	`setFrom(IOElasticBuffer source, int offset, int len)` Copy a serialized string from an `IOElasticBuffer` into an `XString`.
`void`	`setFrom(long value)` Set the raw value of the String to the String value of the given long in decimal radix.
`void`	`setFrom(long addr, int offset, int len)` Copy a serialized string from a memory address into an `XString`.
`void`	`setFrom(String val)` Set the value from a `String`.
`void`	`setFrom(XString value)` Set the value of an `XString` from an `XString`
`void`	`setFrom(XStringDeserializer value)` Set the value of an `XString` from an `XStringDeserializer`
`void`	`setValue(byte[] value)` Set the value of the String to the given bytes.
`void`	`setValue(byte[] value, int valueOffset, int valueLength)` Set the value of the String to the given bytes.
`void`	`setValue(ByteBuffer value)` Copy a serialized string from a `ByteBuffer` into an `XString`.
`void`	`setValue(ByteBuffer value, int offset, int len)` Copy a serialized string from a `ByteBuffer` into an `XString`.
`void`	`setValue(char[] value)` Set the value of the String to the given chars.
`void`	`setValue(char[] value, int valueOffset, int valueLength)` Set the value of the String to the given chars.
`void`	`setValue(CharSequence value)` Set the value of the String to the given char sequence.
`void`	`setValue(IOBuffer value, int offset, int len)` Copy a serialized string from an `IOBuffer` into an `XString`.
`void`	`setValue(IOElasticBuffer value, int offset, int len)` Copy a serialized string from an `IOElasticBuffer` into an `XString`.
`void`	`setValue(long value)` Set the raw value of the String to the String value of the given long in decimal radix.
`void`	`setValue(long addr, int offset, int len)` Copy a serialized string from a memory address into an `XString`.
`void`	`setValue(String value)` Set the value of from a `String` Equivalent to invoking `setFrom(String)`
`void`	`setValue(XString value)` Set the value of an `XString` from an `XString` Equivalent to invoking `setFrom(XString)`
`void`	`setValueFromMemory(long addr, int len)` Copy a serialized string from a memory address into an `XString`.
`boolean`	`startsWith(CharSequence prefix)` Tests if this `XString` starts with the characters in the provided sequence.
`boolean`	`startsWith(CharSequence prefix, int offset)` Tests if an `XString` starts with the characters in the provided sequence starting from the provided offset.
`static int`	`stringSize(long val)` Determine the size of a long value in String form.
`CharSequence`	`subSequence(int start, int end)` Implementation of CharSequence#subSequence(int, int).
`String`	`toDiagnosticString()` A diagnostic string.
`String`	`toString()` Return the String value of this `XString` as returned by `getAsString()`

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.CharSequence
chars, codePoints

- Method Detail
  - create
```
public static XString create(short initialCapacity,
                             boolean mutable)
```
    Create an XString.
    
    Parameters:
    
    initialCapacity - Specifies the initial capacity of the string's backing storage. A XStrings does not allocate the backing storage until a value is set in it. Subsequent changes in the XString value will dynamicaly resize the backing storage if need be. The backing storage initial capacity specifies the minimum size of the storage to allocate on the first allocation. This parameter should be provided if the XStrings created by this factory is expected to undergo several value changes of a variety of sizes. In such a case, this property should be set as the upper bound of the set of values expected to be set so the backing storage does not go through excessive resizing
    
    mutable - Specifies whether the constructed XString is mutable. An XString's mutability only comes into play after the first value is set in the XString
  - create
```
public static XString create(short initialCapacity)
```
    Create an XString.
    This method invokes create(initialCapacity, true)
  - create
```
public static XString create(int initialCapacity,
                             boolean mutable)
```
    Create an XString.
    
    Throws:
    
    IllegalArgumentException - thrown if value of initialCapacity is greater than Short.MAX_VALUE
    This method is equivalent to #create(short, boolean} and except that it accepts the initialCapacity as an integer parameter instead of a short. This method is provided for backwards compatibility. It performs a validation check on initialCapacity that the supplied value is less or equal to Short.MAX_VALUE and throws an IllegalArgumentException if it is not.
  - create
```
@Deprecated
public static XString create(boolean mutable,
                                         int initialCapacity)
```
    Deprecated. Please use create(int, boolean) instead
    
    Create an XString.
  - create
```
public static XString create(int initialCapacity)
```
    Create an XString.
    This method invokes create(initialCapacity, true)
  - create
```
public static XString create()
```
    Create a mutable, uninitialized XString.
    
    Returns:
    
    The created XString
  - create
```
public static XString create(String value,
                             boolean mutable)
```
    Create an XString initialized with the given String value.
    
    Parameters:
    
    value - The String value to initialize the XString with
    
    mutable - Whether the created string is mutable
    
    Returns:
    
    The created XString
  - create
```
public static XString create(String value)
```
    Create an immutable XString initialized with the given String value.
    
    Parameters:
    
    value - The String value to initialize the XString with
    
    Returns:
    
    The created XString
  - stringSize
```
public static final int stringSize(long val)
```
    Determine the size of a long value in String form.
    
    Parameters:
    
    val - The long for which to calculate String length
    
    Returns:
    
    The length of the long.
  - ensureCapacity
```
public final void ensureCapacity(short val)
```
    Ensure an XStrings backing storage is large enough to accommodate data
  - startsWith
```
public final boolean startsWith(CharSequence prefix)
```
    Tests if this XString starts with the characters in the provided sequence.
    
    Parameters:
    
    prefix - The prefix
    
    Returns:
    
    True if this XString starts with the characters in the provided sequence. If this string and the provided string are both empty Strings this method will return true. If this string is null or unitialized this method will return false.
    
    Throws:
    
    NullPointerException - if the provided prefix is null;
  - startsWith
```
public final boolean startsWith(CharSequence prefix,
                                int offset)
```
    Tests if an XString starts with the characters in the provided sequence starting from the provided offset.
    
    Parameters:
    
    prefix - The prefix
    
    offset - the offset in this XString.
    
    Returns:
    
    True if this XString starts with the characters in the provided sequence. If this string and the provided string are both empty this method will return true. This method will return false if this string is uninitialized or null, or if the provided prefix is null, an unitialized XString, a string of length longer than this XString, or if the offset is either negative, or greater than the length of this XString.
    
    Throws:
    
    NullPointerException - if the provided prefix is null
  - indexOf
```
public final int indexOf(CharSequence str)
```
    Returns the first index of the given character sequence in an XString
    
    Parameters:
    
    str - The string to search for.
    
    Returns:
    
    The first index of the provided character sequence in this string or -1 if this string is uninitialized, null, does not contain this string or if the provided character sequence is null.
  - indexOf
```
public final int indexOf(CharSequence str,
                         int offset)
```
    Returns the first index of the given character sequence in an XString starting from the provided offset.
    
    Parameters:
    
    str - The string to search for.
    
    Returns:
    
    The first index of the provided character sequence in this string or -1 if this string is uninitialized, null, does not contain this string or if the provided character sequence is null.
  - indexOf
```
public final int indexOf(char c)
```
    Returns the first index of the given character in an XString.
    
    Parameters:
    
    c - The string to search for.
    
    Returns:
    
    The first index of the provided character in this string or -1 if this string is uninitialized, null, does not contain the character.
  - indexOf
```
public final int indexOf(char c,
                         int offset)
```
    Returns the first index of the given character in q XString starting from the provided offset.
    
    Parameters:
    
    c - The string to search for.
    
    Returns:
    
    The first index of the provided character in this string or -1 if this string is uninitialized, null, does not contain the character, or if the offset is less than 0 or greater than the length of this string.
  - compareTo
```
public final int compareTo(CharSequence other)
```
    Compares two strings lexicographically.
    If a XStringis null or uninitialized it will lexigraphically precede another XString that is initialized, otherwise the comparison produces the same results as that for String.compareTo(String).
    
    Parameters:
    
    other - The character sequence to compare against.
    
    Returns:
    
    0 if the the provided char sequences is equal to this char sequence, otherwise the value is the same as that of String.compareTo(String) for this and the CharSequence as Strings
    
    See Also:
    
    String.compareTo(String)
  - isMutable
```
public final boolean isMutable()
```
    Get if an XString was marked as mutable on creation.
    A string marked as immmutable can still have a value set on it. Once set, a string marked as immutable will not permit changing the value. This method only returns if a string marked as mutable. To check if a value can be set on the string, use canMutate()
  - isInitialized
```
@Deprecated
public final boolean isInitialized()
```
    Deprecated. Use hasValue() instead
    
    Get if an XString has been initialized.
  - hasValue
```
public final boolean hasValue()
```
    Get if an XStringhas a value set
  - canMutate
```
public final boolean canMutate()
```
    Checks if an XString can be mutated. A XString is mutable till a value is set after which it becomes immutable if created with the immutability flag. Use isMutable() to check if the XString was created as mutable.
    
    Returns:
    
    true if an XString can be mutated. A return value of true means the string was created as mutable or a value has not yet been set on the string. A value of false means that the string was set as immutable on creation and a value has been set on the string.
  - isImmutable
```
public final boolean isImmutable()
```
    Test if this XString cannot be mutated.
    This method is equivalent to invoking !canMutate()
  - isEmpty
```
public final boolean isEmpty()
```
    Checks if an XString is empty
    
    Returns:
    
    true if the XString either does not have a value (is null) or has length 0.
  - isNull
```
public final boolean isNull()
```
    Return if the XString's represents a null string.
    
    Returns:
    
    true if the XString's represents a null string. Being null is synonymous with not possessing a value i.e. this method returns true if and only if hasValue() returns false
  - clear
```
public final void clear(boolean freeMemory)
                 throws IllegalStateException
```
    Clear an XString.
    
    Parameters:
    
    freeMemory - Indicates whether to free underlying memory or not
    
    Throws:
    
    IllegalStateException - If the XString cannot be mutated
  - clear
```
public final void clear()
                 throws IllegalStateException
```
    Clear the value of the XString.
    
    Throws:
    
    IllegalStateException - If the XString cannot be mutated
    This method executes clear(Config.conserveMemory()) i.e. the XString is cleared but the backing stored is freed only if the system is configured to optimize memory usage. Freeing and reallocating memory on demand for the backing store can be expensive for ultra low latency applications. Such applications should carefully consider this and use this method or clear(boolean) accordingly.
  - reset
```
@Deprecated
public final void reset()
                             throws IllegalStateException
```
    Deprecated. Use clear() instead
    
    Reset the value of the XString.
    
    Throws:
    
    IllegalStateException
  - setCharAt
```
public final void setCharAt(int position,
                            char value)
```
    Replaces the character at the given index in a with the provided value.
    
    Parameters:
    
    position - The position of the character to overwrite (0 based).
    
    value - The value to overwrite the character with.
    
    Throws:
    
    IndexOutOfBoundsException - if the position is negative or greater than the length of this string.
    
    IllegalStateException - if the string cannot be mutated.
    
    IllegalArgumentException - If the value is not a us-ascii character.
  - initialize
```
public final void initialize(String value)
```
    Initializes an uninitialized XString with the given String value.
    
    Parameters:
    
    value - The value with which to initialize the XString
    
    Throws:
    
    IllegalStateException - if the XString already has a value.
  - initializeFrom
```
public final void initializeFrom(XString value)
```
    Initialize an uninitialized XString with the given value.
    
    Parameters:
    
    value - The value with which to initialize the XString
    
    Throws:
    
    IllegalStateException - if the XString already has a value.
  - setFrom
```
public final void setFrom(long value)
```
    Set the raw value of the String to the String value of the given long in decimal radix.
    
    Parameters:
    
    value - the value to convert to a String
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
  - setFrom
```
public final void setFrom(byte[] value)
```
    Set the value of the String to the given bytes.
    
    Parameters:
    
    value - The String value.
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
  - setFrom
```
public final void setFrom(byte[] value,
                          int valueOffset,
                          int valueLength)
```
    Set the value of the String to the given bytes.
    If the value is null, the value of the string is cleared.
    
    Parameters:
    
    value - The String value.
    
    valueOffset - The offset into the provided value from which to copy (0 based, inclusive).
    
    valueLength - The number of of bytes from the valueOffset to copy.
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
    
    IllegalArgumentException - If any of the source character's can't be encoded in ascii.
    
    IllegalArgumentException - if the valueOffset or valueLength is outside the bounds of the provided array.
  - setFrom
```
public void setFrom(char[] value)
```
    Set the value of the String to the given characters.
    
    Parameters:
    
    value - The String value.
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
    
    IllegalArgumentException - If any of the source character's can't be encoded in ascii.
  - setFrom
```
public void setFrom(char[] value,
                    int valueOffset,
                    int valueLength)
```
    Set the value of the String to the given characters.
    If the value is null, the value of the string is cleared.
    
    Parameters:
    
    value - The String value.
    
    valueOffset - The offset into the provided value from which to copy (0 based, inclusive).
    
    valueLength - The number of of bytes from the valueOffset to copy.
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
    
    IllegalArgumentException - If any of the source character's can't be encoded in ascii.
    
    IllegalArgumentException - if the valueOffset or valueLength is outside the bounds of the provided array.
  - setFrom
```
public void setFrom(CharSequence value)
```
    Set the value of the XString to that of the given CharSequence
    
    Parameters:
    
    value - The CharSequence value.
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
  - setFrom
```
public final void setFrom(String val)
```
    Set the value from a String.
    
    Parameters:
    
    val - The value to set.
    
    Throws:
    
    IllegalStateException - if the XString cannot be mutated.
  - setFrom
```
public final void setFrom(XString value)
```
    Set the value of an XString from an XString
    
    Parameters:
    
    value - The XString value
    
    Throws:
    
    IllegalStateException - if the XString cannot be mutated.
  - setFrom
```
public final void setFrom(XStringDeserializer value)
```
    Set the value of an XString from an XStringDeserializer
    
    Parameters:
    
    value - The XStringDeserializer value
    
    Throws:
    
    IllegalStateException - if the XString cannot be mutated.
  - setFrom
```
public final void setFrom(long addr,
                          int offset,
                          int len)
```
    Copy a serialized string from a memory address into an XString.
    The source bytes are expected to be UTF-8 encoded characters.
    
    Parameters:
    
    addr - The source address from which to set.
    
    len - The number of bytes to set.
    
    Throws:
    
    IllegalStateException - if the XString cannot be mutated.
  - setFrom
```
public final void setFrom(ByteBuffer source,
                          int offset,
                          int len)
```
    Copy a serialized string from a ByteBuffer into an XString.
    The source bytes are expected to be UTF-8 encoded characters.
    
    Parameters:
    
    source - The buffer
    
    offset - The offset into the buffer
    
    len - The length of the serialized string
    
    Throws:
    
    IllegalStateException - if the value is not mutable.
  - setFrom
```
public final void setFrom(ByteBuffer source)
```
    Copy a serialized string from a ByteBuffer into an XString.
    The data is copied from the buffer's current position to the buffer's limit. The buffer's position and limit markers are left unchanged after the copy.
    The source bytes are expected to be UTF-8 encoded characters.
    
    Parameters:
    
    source - The buffer
    
    Throws:
    
    IllegalStateException - if the value is not mutable.
  - setFrom
```
public final void setFrom(IOBuffer source,
                          int offset,
                          int len)
```
    Copy a serialized string from an IOBuffer into an XString.
    The source bytes are expected to be UTF-8 encoded characters.
    
    Parameters:
    
    source - The buffer
    
    offset - The offset into the buffer
    
    len - The length of the serialized string
    
    Throws:
    
    IllegalStateException - if the value is not mutable.
  - setFrom
```
public final void setFrom(IOElasticBuffer source,
                          int offset,
                          int len)
```
    Copy a serialized string from an IOElasticBuffer into an XString.
    The source bytes are expected to be UTF-8 encoded characters.
    
    Parameters:
    
    source - The buffer
    
    offset - The offset into the buffer
    
    len - The length of the serialized string
    
    Throws:
    
    IllegalStateException - if the value is not mutable.
  - setValue
```
public final void setValue(long value)
```
    Set the raw value of the String to the String value of the given long in decimal radix.
    Equivalent to invoking setFrom(long)
  - setValue
```
public final void setValue(byte[] value)
```
    Set the value of the String to the given bytes.
    Equivalent to invoking setFrom(byte[])
  - setValue
```
public final void setValue(byte[] value,
                           int valueOffset,
                           int valueLength)
```
    Set the value of the String to the given bytes.
    Equivalent to invoking setFrom(byte[], int, int)
  - setValue
```
public final void setValue(char[] value)
```
    Set the value of the String to the given chars.
    Equivalent to invoking setFrom(char[])
  - setValue
```
public final void setValue(char[] value,
                           int valueOffset,
                           int valueLength)
```
    Set the value of the String to the given chars.
    Equivalent to invoking setFrom(char[], int, int)
  - setValue
```
public final void setValue(CharSequence value)
```
    Set the value of the String to the given char sequence.
    Equivalent to invoking setFrom(CharSequence)
  - setValue
```
public final void setValue(String value)
```
    Set the value of from a String
    Equivalent to invoking setFrom(String)
  - setValue
```
public final void setValue(XString value)
```
    Set the value of an XString from an XString
    Equivalent to invoking setFrom(XString)
  - setValue
```
public final void setValue(ByteBuffer value,
                           int offset,
                           int len)
```
    Copy a serialized string from a ByteBuffer into an XString.
    Equivalent to invoking setFrom(ByteBuffer, int, int)
  - setValue
```
public final void setValue(ByteBuffer value)
```
    Copy a serialized string from a ByteBuffer into an XString.
    Equivalent to invoking setFrom(ByteBuffer)
  - setValue
```
public final void setValue(IOBuffer value,
                           int offset,
                           int len)
```
    Copy a serialized string from an IOBuffer into an XString.
    Equivalent to invoking setFrom(IOBuffer, int, int)
  - setValue
```
public final void setValue(IOElasticBuffer value,
                           int offset,
                           int len)
```
    Copy a serialized string from an IOElasticBuffer into an XString.
    Equivalent to invoking setFrom(IOElasticBuffer, int, int)
  - setValue
```
public final void setValue(long addr,
                           int offset,
                           int len)
```
    Copy a serialized string from a memory address into an XString.
    Equivalent to invoking setFrom(long, int, int)instead
  - setValueFromMemory
```
public final void setValueFromMemory(long addr,
                                     int len)
```
    Copy a serialized string from a memory address into an XString.
    Equivalent to invoking setFrom(long, int, int)instead
  - copyFrom
```
public final void copyFrom(char[] val)
```
    Set the value of the String to the given characters.
    Equivalent to invoking setFrom(char[])instead.
  - copyFrom
```
public final void copyFrom(XString value)
```
    Set the value of an XString from an XString
    Equivalent to invoking setFrom(XString)
  - copyFromNative
```
public final void copyFromNative(long addr,
                                 int len)
```
    Copy a serialized string from a memory address into an XString.
    Equivalent to invoking setFrom(long, int, int)instead
  - copyFromMemory
```
public final void copyFromMemory(long addr,
                                 int len)
```
    Copy a serialized string from a memory address into an XString.
    Equivalent to invoking setFrom(long, int, int)instead
  - append
```
public final XString append(boolean value)
```
    Appends the given boolean value in string format to the end of an XString.
    
    Parameters:
    
    value - The boolean to append.
    
    Returns:
    
    The XString for invocation chaining
    
    Throws:
    
    IllegalStateException - if this string cannot be mutated.
  - append
```
public final XString append(char value)
                     throws IllegalArgumentException
```
    Append the given char to the end of this XString.
    
    Specified by:
    
    append in interface Appendable
    
    Parameters:
    
    value - The character to append.
    
    Returns:
    
    The XString for invocation chaining
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
    
    IllegalArgumentException - If the character is not a us-ascii character.
  - append
```
public final XString append(long value)
```
    Appends the given long value in String format to the end of this XString.
    
    Parameters:
    
    value - The value to append.
    
    Returns:
    
    The XString for invocation chaining
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
    
    IllegalArgumentException - If the character is not a us-ascii character.
  - append
```
public final XString append(byte[] value)
```
    Append the given bytes bytes to the end of this XString.
    This method is equivalent to calling append(char[], int, int) with values of 0 and value.length respectively ... see javadoc for additional details.
    
    Parameters:
    
    value - The ByteBuffer value.
    
    Returns:
    
    The XString for invocation chaining
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
  - append
```
public final XString append(byte[] value,
                            int valueOffset,
                            int valueLength)
```
    Append the given bytes bytes to the end of this XString.
    Calling this method with a null value has no effect other than throwing an IllegalStateException if this XString cannot be mutated.
    
    Parameters:
    
    value - The ByteBuffer value.
    
    valueOffset - The offset into the provided value from which to append (0 based, inclusive).
    
    valueLength - The number of of bytes from the valueOffset to append.
    
    Returns:
    
    The XString for invocation chaining
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
    
    IllegalArgumentException - if the valueOffset or valueLength is outside the bounds of the provided array.
  - append
```
public final XString append(char[] value)
                     throws IllegalArgumentException
```
    Append the given char [] to the end of this XString.
    This method is equivalent to calling append(char[], int, int) with values of 0 and value.length respectively ... see javadoc for additional details.
    
    Parameters:
    
    value - The characters to append.
    
    Returns:
    
    The XString for invocation chaining
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
    
    IllegalArgumentException - If any of the characters is not a us-ascii character.
  - append
```
public final XString append(char[] value,
                            int valueOffset,
                            int valueLength)
                     throws IllegalArgumentException
```
    Append the given char [] to the end of this XString.
    
    Parameters:
    
    value - The characters to append.
    
    valueOffset - The offset into the provided value from which to append (0 based, inclusive).
    
    valueLength - The number of of bytes from the valueOffset to append.
    
    Returns:
    
    The XString for invocation chaining
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
    
    IllegalArgumentException - If any of the characters is not a us-ascii character.
    
    IllegalArgumentException - if the valueOffset or valueLength is outside the bounds of the provided array.
  - append
```
public final XString append(CharSequence value)
                     throws IllegalArgumentException
```
    Append the given CharSequence to the end of this XString.
    
    Specified by:
    
    append in interface Appendable
    
    Parameters:
    
    value - The characters to append.
    
    Returns:
    
    The XString for invocation chaining
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
    
    IllegalArgumentException - If any of the characters is not a us-ascii character.
  - append
```
public final Appendable append(CharSequence value,
                               int start,
                               int end)
                        throws IllegalArgumentException
```
    Specified by:
    
    append in interface Appendable
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
    
    IllegalArgumentException - If any of the characters is not a us-ascii character.
  - append
```
public final XString append(XString value)
```
    Appends the contents of the given XString into this XString.
    If the source XString is null then this XString is left unchanged.
    
    Parameters:
    
    source - The XString to append to this XString
    
    Returns:
    
    The XString for invocation chaining
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
  - append
```
public final XString append(ByteBuffer value,
                            int valueOffset,
                            int valueLength)
```
    Appends the contents of the given ByteBuffer into this XString.
    If the source ByteBuffer is null, then this XString is left unchanged.
    
    Parameters:
    
    value - The source buffer
    
    valueOffset - The offset into the buffer to append fron
    
    valueLength - The length to append
    
    Returns:
    
    The XString for invocation chaining
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
  - append
```
public final XString append(ByteBuffer value)
```
    Appends the contents of the given ByteBuffer into this XString.
    This method appends the remaining bytes in the source ByteBuffer
    If the source ByteBuffer is null, then this XString is left unchanged.
    
    Parameters:
    
    value - The source buffer
    
    Returns:
    
    The XString for invocation chaining
    
    Throws:
    
    IllegalStateException - if the string cannot be mutated.
  - getAsString
```
public String getAsString()
```
    Get an XString as a String value.
    This method is not garbage free since it allocates the returned String object
  - getAsLong
```
public final long getAsLong()
                     throws NumberFormatException
```
    Get an XString as a long value.
    
    Returns:
    
    The XString as a long value.
    
    Throws:
    
    NumberFormatException - If the XString can't be parsed as a long.
  - getAsLongDecimal
```
public final long getAsLongDecimal()
```
    Get an XString as a long value.
    
    Returns:
    
    The XString as a long value.
    Unlike getAsLong(int) this method does not perform number format checking and is more efficient.
  - getAsLong
```
public final long getAsLong(int radix)
                     throws NumberFormatException
```
    Get an XString as a long value.
    
    Parameters:
    
    radix - The radix to use when parsing the long value. Valid values are between 2 and 36 both inclusive
    
    Returns:
    
    The XString as a long value.
    
    Throws:
    
    NumberFormatException - If the XString can't be parsed as a long.
  - getTo
```
public final int getTo(XString val)
```
    Copy this XString into another XString.
    
    Parameters:
    
    val - The XString into which the XString is to be copied. The target must be mutable.
    
    Returns:
    
    Returns the number of characters (bytes) copied. A value of 0 will be returned if the source string is empty or null. Use isNull() to differentiate between these two scenarios
  - getTo
```
public final int getTo(byte[] val,
                       int offset)
```
    Copy the serialized bytes of an XString into an byte array
    
    Parameters:
    
    val - The array into which the bytes are to be copied.
    
    offset - The offset into the array to copy to
    
    Returns:
    
    Returns the number of characters (bytes) copied. A value of 0 will be returned if the source string is empty or null. Use isNull() to differentiate between these two scenarios
  - getTo
```
public final int getTo(long addr,
                       int offset)
```
    Copy the serialized bytes of an XString to a memory location
    
    Parameters:
    
    addr - The base memory location into which the bytes are to be copied.
    
    offset - The offset to the memory location to copy to
    
    Returns:
    
    Returns the number of characters (bytes) copied. A value of 0 will be returned if the source string is empty or null. Use isNull() to differentiate between these two scenarios
  - getTo
```
public final int getTo(ByteBuffer target,
                       int offset)
```
    Copy the serialized bytes of an XString to a ByteBuffer
    
    Parameters:
    
    buffer - The buffer to copy the bytes to
    
    offset - The offset into the buffer to copy to
    
    Returns:
    
    Returns the number of characters (bytes) copied. A value of 0 will be returned if the source string is empty or null. Use isNull() to differentiate between these two scenarios
  - getTo
```
public final int getTo(IOElasticBuffer target,
                       int offset)
```
    Copy the serialized bytes of an XString to an IOElasticBuffer
    
    Parameters:
    
    buffer - The buffer to copy the bytes to
    
    offset - The offset into the buffer to copy to
    
    Returns:
    
    Returns the number of characters (bytes) copied. A value of 0 will be returned if the source string is empty or null. Use isNull() to differentiate between these two scenarios
  - getValue
```
public final String getValue()
```
    Get an XString as a String value.
    Equivalent to getAsString()
  - getValueAsLong
```
public final long getValueAsLong()
                          throws NumberFormatException
```
    Zero garbage method to parses the string as a long value.
    
    Returns:
    
    The String value as a long.
    Equivalent to getAsLong()
    
    Throws:
    
    NumberFormatException
  - copyInto
```
@Deprecated
public final int copyInto(XString val)
```
    Deprecated. Use #getTo(XString} instead
    
    Copy this XString into another XString.
  - copyInto
```
@Deprecated
public final int copyInto(ByteBuffer target,
                                      int offset)
```
    Deprecated. Use getTo(ByteBuffer, int) instead
    
    Copy the serialized bytes of an XString to an ByteBuffer
  - getTo
```
public final int getTo(IOBuffer target,
                       int offset)
```
    Copy the serialized bytes of an XString to an IOBuffer
    
    Parameters:
    
    buffer - The buffer to copy the bytes to
    
    offset - The offset into the buffer to copy to
    
    Returns:
    
    Returns the number of characters (bytes) copied. A value of 0 will be returned if the source string is empty or null. Use isNull() to differentiate between these two scenarios
  - copyInto
```
@Deprecated
public final int copyInto(IOBuffer target,
                                      int offset)
```
    Deprecated. Use getTo(IOBuffer, int) instead
    
    Copy the serialized bytes of an XString to an IOBuffer
  - copyInto
```
@Deprecated
public final int copyInto(IOElasticBuffer target,
                                      int offset)
```
    Deprecated. Use getTo(IOElasticBuffer, int) instead
    
    Copy the serialized bytes of an XString to an IOElasticBuffer
  - length
```
public final int length()
```
    Returns the length in characters of the XString.
    
    Specified by:
    
    length in interface CharSequence
    
    Returns:
    
    The length of the XString.
  - capacity
```
public final int capacity()
```
    Returns the capacity of the backing storage
    
    Returns:
    
    The capacity.
  - serializedLength
```
public final int serializedLength()
```
    Return an XString's serialized length.
    Given it's character encoding, this may be different than it's length().
    
    Returns:
    
    The serialized length
  - nativeAddress
```
public final long nativeAddress()
```
    Return an XString's backing store address.
    
    Returns:
    
    The backing store address
  - getSerializedLength
```
@Deprecated
public final int getSerializedLength()
```
    Deprecated. Use serializedLength() instead
    
    Return an XString's serialized length.
  - charAt
```
public final char charAt(int index)
                  throws IndexOutOfBoundsException
```
    Returns the character at the given position.
    
    Specified by:
    
    charAt in interface CharSequence
    
    Parameters:
    
    index - The character position.
    
    Returns:
    
    the character at the given position
    
    Throws:
    
    IndexOutOfBoundsException - If the position is greater than or equal to this XString's length()
  - subSequence
```
public final CharSequence subSequence(int start,
                                      int end)
```
    Implementation of CharSequence#subSequence(int, int). This is not a zero garbage operation
    
    Specified by:
    
    subSequence in interface CharSequence
    
    Returns:
    
    a subsequence view of this XString
    
    See Also:
    
    CharSequence.subSequence(int, int)
  - toString
```
public String toString()
```
    Return the String value of this XString as returned by getAsString()
    
    Specified by:
    
    toString in interface CharSequence
    
    Overrides:
    
    toString in class Object
  - toDiagnosticString
```
public final String toDiagnosticString()
```
    A diagnostic string.
    
    Returns:
    
    A diagnostic string.
  - equals
```
public boolean equals(Object object)
```
    Test if this XString is equal to another XString. Two XStrings that are initialized are equal if their backing byte representations are the equivalent.
    an XString will also equal a CharSequence that is a subsequence of another XString if they have the same characters, but equality will not hold true for CharSequences that are not XString char sequences. This limitation is necessary because it isn't possible to guarantee that symmetric equality with other CharSequence implementations. For example a String will only equal another String CharSequence.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    object - The object against which to compare
    
    Returns:
    
    true if This XString equals the provided object
  - hashCode
```
public int hashCode()
```
    Return the current hash code of this XString.
    The hash code of an XString is based on the backing byte representation The hashcode of a mutable XString will change if the underlying String or bytes are modified.
    Because mutable XString hash codes are content-dependent, it is inadvisable to use mutable unitialized immutable XStrings as keys in hash maps or similar data structures unless it is known that their contents will not change.
    
    XString Hash Algorithm The hashing algorithm for an XString is as follows:
```
  if (isNull()) {
      return 0;
  }
  if (length == 0) {
      return 0;
  }
  int h = 1;
  for (int p = 0; p < length; p++) {
      h = 31 * h + IOBuffer.getByte(addr, p);
  }
  return h;
 
```
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    The current hash code of this XString
  - close
```
public final void close()
```
    This method should be invoked when the user is done working with an XString that it owns i.e. one that it has created for its own use or one that has been handed to the user for ownership by the Rumi runtime. The method will clear off-heap memory resources used by the XString. Failure to invoke this method prior to handing over this object to the garbage collector will result in a memory leak.

Class XString

Immutability of XString

Character Encoding

CharSequence view

Equality and hashCode

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.CharSequence

Method Detail

create

create

create

create

create

create

create

create

stringSize

ensureCapacity

startsWith

startsWith

indexOf

indexOf

indexOf

indexOf

compareTo

isMutable

isInitialized

hasValue

canMutate

isImmutable

isEmpty

isNull

clear

clear

reset

setCharAt

initialize

initializeFrom

setFrom

setFrom

setFrom

setFrom

setFrom

setFrom

setFrom

setFrom

setFrom

setFrom

setFrom

setFrom

setFrom

setFrom

setValue

setValue

setValue

setValue

setValue

setValue

setValue

setValue

setValue

setValue

setValue

setValue

setValue

setValueFromMemory

copyFrom

copyFrom

copyFromNative

copyFromMemory

append

append

append

append

append

append

append

append

Immutability of `XString`