XString (Talon 3.14.19 API)

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

All Implemented Interfaces:

Appendable, CharSequence

Direct Known Subclasses:

XAbstractPooledString
```
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. An XString is often referred to as a 'RawString' which is a historical moniker that reflects XString raw access to the String underlying serialized byte form.
This class serves the following purposes:
Zero Garbage Preallocation
If a String needs to be maintained in memory for a long period of time as part of an application's state, late allocation of the String would normally produce an object that generational garbage collection would have to promote into tenured memory. For latency sensitive application's promotion of the String to the tenured generation will leads to garbage collection pauses. A XString allows preallocation of memory for such a field up front whereas a String can't be preallocated because it is immutable.
An XString may be preallocated via one of its factory methods or via the factory methods for XString in XFactory. The XString and its backing buffer will be promoted to the tenured generation at the beginning of the application's life cycle allowing the tenuring cost to be paid up front thereby eliminating pauses that would result from minor gc during normal application operation.
When the XString is later assigned from another XString, the backing buffer can be copied from it without any garbage being created. A typical example of this would be where a transport layer reads a field off the wire and passes it off to the application. The networking layer wraps the encoded buffer in a pooled XString and can pass it off to application code that has a preallocated XString that serves as the target. The network buffer is copied into the preallocated target without instantiating the underlying non primitive type meaning that no garbage is created in the course of setting the field.
However even if the underlying value is materialized by application code via a call to getValue(), the cost in garbage can remain low providing the application doesn't keep a reference to the materialized value because because the materialized value needn't be promoted to an eden survivor space or the tenured generation which is the more expensive operation in garbage collection. The application keeps a reference to the XString only and can continue to transiently decode the value and release it as needed.
Zero Copy/Reencode Serializable Field Transfer
In the case where a value needs to be transfered from one serializable object to another, an XString allows the transfer of the field without costly character decoding or reencoding the value. For latency sensitive application this is important for two reasons. Firstly, decoding to a String introduces intermediate garbage in the form of the materialized value returned by getValue(), and secondly the decode/encode operation costs clock cycles, particulary for types like a String where encoding and decoding is an expensive operation.
As alluded to above, for a networking application that reuses its network buffers, a XString can be layered on top of a network buffer and presented to the application which can pass the XString to an outbound network buffer where it can be written without (de)serialization and (re)encoding. When the backing buffer is a direct or native buffer this provides a mechanism for field transfer with zero intermediate copy.
Immutability of XString
An immutable XString created via one of the factory methods of XFactory is immutable from the point that it is initialized. Once initialized via a setter method, a factory created 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 a XString via isImmutable() and isInitialized(). 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 copyInto(XString) to create an immutable version of the XString if needs be.
Character Encoding
For interoperability 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
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 buffers are not safe for mutative access by multiple threads.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static interface`	`XString.Factory<T extends XString>` A factory interface for creating new concrete instances of an XString
`static class`	`XString.XStringFactory` A. factory for `XString`s which does not support pooling or preallocation.

Method Summary

Methods
Modifier and Type	Method and Description
`XString`	`append(boolean value)` Appends the given boolean value in String format to the end of this `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)` Append the given `ByteBuffer`'s remaining bytes to the end of 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 source)` Appends the contents of the given `XString` into this `XString`.
`char`	`charAt(int index)` Returns the character at the given position.
`void`	`clear()` Clears the value of the `XString`.
`int`	`compareTo(CharSequence other)` Compares two strings lexicographically.
`void`	`copyFrom(char[] val)` Deprecated. Use `setValue(char[])` instead.
`void`	`copyFrom(XString val)` Deprecated. Use `setValue(XString)` instead.
`void`	`copyFromMemory(long address, int length)` Deprecated. Use `setValueFromMemory(long, int)` instead
`void`	`copyFromNative(long address, int length)` Deprecated. Use `setValueFromMemory(long, int)` instead
`int`	`copyInto(ByteBuffer target, int position)` Serialize the string into the given buffer at the given position.
`int`	`copyInto(com.neeve.io.IOBuffer target, int offset)` Serialize this `XString` into an `IOBuffer`.
`<T extends com.neeve.io.IOElasticBuffer> T`	`copyInto(T target, int offset)` Serialize this `XString` into an `IOElasticBuffer`.
`XString`	`copyInto(XString target)` Copy this `XString` into another `XString`.
`static XString`	`create()` Create an uninitialized, mutable `XString`.
`static XString`	`create(int bufferSize)` Preallocate a non native, uninitialized, immutable `XString`.
`static XString`	`create(int bufferSize, boolean mutable)` Preallocate a non native uninitialized `XString`.
`static XString`	`create(int bufferSize, boolean mutable, boolean isNative)` Preallocate an uninitialized `XString`.
`static XString`	`create(String value)` Create an immutable XString initialized with a given String value.
`static XString`	`create(String value, boolean bufferbacked)` Create an immutable XString initialized with the given String value.
`static XString`	`create(String value, boolean bufferbacked, boolean isNative)` Create an immutable XString initialized with the given String value.
`boolean`	`equals(Object object)` Test if this `XString` is equal to another `XString`.
`com.neeve.io.IOElasticBuffer`	`getBackingBuffer()` Gets the underlying io buffer backing this XString.
`int`	`getBackingBufferOffset()` Get the underlying io buffer offset for this XString.
`int`	`getSerializedLength()` Return the `XString`'s serialized length.
`String`	`getValue()` Get the String value.
`long`	`getValueAsLong()` Zero garbage method to parses the string as a long value.
`long`	`getValueAsLong(int radix)` Zero garbage method to parses the string as a long value.
`long`	`getValueAsLongDecimal()` Zero garbage method to parses the string as a long value.
`int`	`hashCode()` Return the current hash code of this `XString`.
`int`	`indexOf(char c)` Returns the first index of the given character in this XString.
`int`	`indexOf(char c, int offset)` Returns the first index of the given character in this XString starting from the provided offset.
`int`	`indexOf(CharSequence str)` Returns the first index of the given character sequence in this XString
`int`	`indexOf(CharSequence str, int offset)` Returns the first index of the given character sequence in this XString starting from the provided offset.
`boolean`	`initialize(String value)` Initializes an uninitialized `XString` with the given String value.
`boolean`	`initializeFrom(XString value)` Initialize an uninitialized `XString` with the given value.
`boolean`	`isEmpty()` Returns true if the XString is either null or has length 0.
`boolean`	`isImmutable()` Test if this `XString` is immutable.
`boolean`	`isInitialized()` Test if this `XString` has been initialized.
`boolean`	`isMutable()` Get if a string is mutable
`static boolean`	`isNativeXStringEnabled()` Checks if native XString buffers are enabled.
`boolean`	`isNull()` Return if the `XString`'s represents a null string.
`int`	`length()` Returns the length in characters of the XString.
`void`	`padForNullTerminator()` Pads the backing buffer by an additional byte to accomodate c style null terminator.
`void`	`reset()` Clear the value for this `XString`.
`void`	`setCharAt(int position, char value)` Replaces the character at the given index with the provided value.
`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 source)` Set the value of the `XString` to that of the given `ByteBuffer`.
`void`	`setValue(ByteBuffer source, int position, int length)` Set the value of the `XString` to that of the given `ByteBuffer`.
`void`	`setValue(char[] value)` Set the value of the String to the given characters.
`void`	`setValue(char[] value, int valueOffset, int valueLength)` Set the value of the String to the given characters.
`void`	`setValue(CharSequence value)` Set the value of the `XString` to that of the given `CharSequence`
`void`	`setValue(com.neeve.io.IOBuffer source, int offset, int length, boolean wrap)` Set the raw value of the String using the value in the given buffer.
`void`	`setValue(com.neeve.io.IOElasticBuffer source, int offset, int length)` Set the raw value of the String using the value in the given buffer.
`void`	`setValue(long value)` Set the raw value of the String to the String value of the given long in decimal radix.
`void`	`setValue(String val)` Set the String value.
`void`	`setValue(XString value)` Set the value of the `XString` from that of another `XString`
`void`	`setValueFromMemory(long address, int length)` Copy the content from the provided memory address into this `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 this XString starts with the characters in the provided sequence starting from the provided offset.
`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 `getValue()`

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

- Method Detail
  - create
```
public static XString create()
```
    Create an uninitialized, mutable XString.
    
    Returns:
    The XString
  - create
```
public static XString create(String value)
```
    Create an immutable XString initialized with a given String value.
    
    Parameters:
    value - the String value
    
    Returns:
    The XString
    This method does create or serialize to a backing buffer. This make it possible to use the XString as a pure wrapper for the String in cases where the String never needs to be encoded. If the backing buffer is later requested it will be instantiated. To create a buffer-backed XString use create(String, boolean)
  - create
```
public static XString create(String value,
             boolean bufferbacked)
```
    Create an immutable XString initialized with the given String value.
    
    Parameters:
    value - The String value
    bufferbacked - True if the backing buffer should be allocated.
    
    Returns:
    The XString
  - create
```
public static XString create(String value,
             boolean bufferbacked,
             boolean isNative)
```
    Create an immutable XString initialized with the given String value.
    
    Parameters:
    value - The String value
    bufferbacked - True if the backing buffer should be allocated.
    isNative - Whether or not the backing bufffer should be native.
    
    Returns:
    The XString
  - create
```
public static XString create(int bufferSize)
```
    Preallocate a non native, uninitialized, immutable XString. The XString may be later initialized via one of the returned XString's initialize methods after which it will be deemed immutable.
    
    Parameters:
    bufferSize - The expected size of the serialized string
    
    Returns:
    The preallocated XString;
  - create
```
public static XString create(int bufferSize,
             boolean mutable)
```
    Preallocate a non native uninitialized XString.
    
    Parameters:
    bufferSize - The expected size of the serialized string
    mutable - True if initialized as mutable. If not set to mutable, then once the XString is initialized it will no longer be mutable
    
    Returns:
    The preallocated XString;
  - create
```
public static XString create(int bufferSize,
             boolean mutable,
             boolean isNative)
```
    Preallocate an uninitialized XString.
    
    Parameters:
    bufferSize - The expected size of the serialized string
    mutable - True if initialized as mutable. If not set to mutable, then once the XString is initialized it will no longer be mutable
    isNative - Whether or not the XString is backed by a native (off-heap) buffer.
    
    Returns:
    The preallocated XString;
  - 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 this XString starts with the characters in the provided sequence starting from the provided offset.
    NOTE: Currently this is only reliable for XString composed entirely of ASCII characters.
    
    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 this 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 this 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 this XString.
    NOTE: Currently this is only reliable for XString composed entirely of ASCII characters.
    
    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 this XString starting from the provided offset.
    NOTE: Currently this is only reliable for XString composed entirely of ASCII characters.
    
    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.
    Ifthis XString is 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)
  - isNativeXStringEnabled
```
public static final boolean isNativeXStringEnabled()
```
    Checks if native XString buffers are enabled.
    
    Returns:
    true if native XString buffers are enabled.
  - isMutable
```
public final boolean isMutable()
```
    Get if a string is mutable
  - getValue
```
public final String getValue()
```
    Get the String value. This method may result in the allocation of a String if the XString was initialized from a backing buffer.
  - 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)
  - initialize
```
public final boolean initialize(String value)
```
    Initializes an uninitialized XString with the given String value.
    
    Parameters:
    value - The value with which to initialize the XString
    
    Returns:
    true if the value fit into the XString's backing buffer, false if the buffer had to be grown.
    
    Throws:
    
    IllegalStateException - if the XString is already initialized.
  - initializeFrom
```
public final boolean initializeFrom(XString value)
```
    Initialize an uninitialized XString with the given value.
    
    Parameters:
    value - The value with which to initialize the XString
    
    Returns:
    true if the value fit into the XString's backing buffer, false if the buffer had to be grown.
    
    Throws:
    
    IllegalStateException - if the XString is already initialized.
  - isInitialized
```
public final boolean isInitialized()
```
    Test if this XString has been initialized. A preallocated XString will return false until it has been initialized via copyInto(XString)
    
    Returns:
    true if the XString is initialized.
  - isImmutable
```
public final boolean isImmutable()
```
    Test if this XString is immutable. A XString that is not initialized will not be immutable, but may become immutable after initialization.
    
    Returns:
    true if the XString is immutable.
  - setValue
```
public final void setValue(String val)
```
    Set the String value. Unlike, setValue(CharSequence), this method caches the provided String allowing it to be used as a return value for getValue()
    
    Parameters:
    val - The String value.
    
    Throws:
    
    IllegalStateException - if the value is not mutable.
  - setValue
```
public final void setValue(XString value)
```
    Set the value of the XString from that of another XString
    
    Parameters:
    value - The XString value
    
    Throws:
    
    IllegalStateException - if the XString is already initialized.
  - copyFrom
```
@Deprecated
public final void copyFrom(XString val)
```
    Deprecated. Use setValue(XString) instead.
    
    Copy the value from another XString, a zero garbage operation.
    
    Parameters:
    val - The XString value.
  - copyFromNative
```
@Deprecated
public final void copyFromNative(long address,
                             int length)
```
    Deprecated. Use setValueFromMemory(long, int) instead
    
    Copy the content from the provided memory address into this XString. The source bytes are expected to be UTF-8 encoded characters.
    
    Parameters:
    address - The source address from which to copy.
    length - The number of bytes to copy.
  - copyFromMemory
```
@Deprecated
public final void copyFromMemory(long address,
                             int length)
```
    Deprecated. Use setValueFromMemory(long, int) instead
    
    Copy the content from the provided memory address into this XString. The source bytes are expected to be UTF-8 encoded characters.
    
    Parameters:
    address - The source address from which to copy.
    length - The number of bytes to copy.
  - setValueFromMemory
```
public final void setValueFromMemory(long address,
                      int length)
```
    Copy the content from the provided memory address into this XString. The source bytes are expected to be UTF-8 encoded characters.
    
    Parameters:
    address - The source address from which to copy.
    length - The number of bytes to copy.
  - copyFrom
```
@Deprecated
public final void copyFrom(char[] val)
```
    Deprecated. Use setValue(char[]) instead.
    
    Copy the value from the provided char[].
    
    Parameters:
    val - The XString value.
    
    Throws:
    
    IllegalArgumentException - If any of the source character's can't be encoded in ascii.
  - setValue
```
public void setValue(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 value is not mutable.
  - setValue
```
public void setValue(char[] value)
```
    Set the value of the String to the given characters.
    This method is equivalent to calling setValue(char[], int, int) with values of 0 and value.length respectively ... see javadoc for additional details.
    
    Parameters:
    value - The String value.
    
    Throws:
    
    IllegalStateException - if the value is not mutable.
    
    IllegalArgumentException - If any of the source character's can't be encoded in ascii.
  - setValue
```
public void setValue(char[] value,
            int valueOffset,
            int valueLength)
```
    Set the value of the String to the given characters. An XString implementation may choose not to copy the characters and instead reference the passed in array. Callers should therefore ensure that the provided array is not mutated.
    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 value is not mutable.
    
    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.
  - setValue
```
public final void setValue(byte[] value)
```
    Set the value of the String to the given bytes.
    This method is equivalent to calling setValue(byte[], int, int) with values of 0 and value.length respectively ... see javadoc for additional details.
    
    Parameters:
    value - The String value.
    
    Throws:
    
    IllegalStateException - if the value is not mutable.
  - setValue
```
public final void setValue(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.
    Note, while the XString will store the bytes in its backing buffer for any character encoding, character based operations on this XString only supports ascii encoded bytes being passed in here (e.g. every byte is assumed to be an ascii character)
    
    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 value is not mutable.
    
    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.
  setValue
  
  public void setValue(CharSequence value)
  
  Set the value of the XString to that of the given CharSequence
  
  Parameters:
  value - The CharSequence value.
  
  Throws:
  
  IllegalStateException - if the value is not mutable.
  
  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.
  
  Throws:
  
  NumberFormatException - If the String can't be parsed as a long.
  
  getValueAsLongDecimal
  
  public final long getValueAsLongDecimal()
  
  Zero garbage method to parses the string as a long value.
  Unlike getValueAsLong(int) this method does not perform number format checking and is more efficient.
  
  Returns:
  The String value as a long.
  
  getValueAsLong
  
  public final long getValueAsLong(int radix) throws NumberFormatException
  
  Zero garbage method to parses the string as a long value. This method supports radixes between 2 and 36.
  
  Parameters:
  radix - The radix to use when parsing the long value.
  
  Returns:
  The String value as a long.
  
  Throws:
  
  NumberFormatException - If the String can't be parsed as a long.
  
  setCharAt
  
  public void setCharAt(int position, char value)
  
  Replaces the character at the given index with the provided value.
  NOTE: Currently this is only reliable for XString composed entirely of ASCII characters.
  
  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 value is not mutable.
  
  IllegalArgumentException - If the value is not a us-ascii character.
  
  setValue
  
  public final void setValue(com.neeve.io.IOElasticBuffer source, int offset, int length)
  
  Set the raw value of the String using the value in the given buffer.
  
  Parameters:
  source - The buffer
  offset - The offset into the buffer
  length - The length of the serialized string
  
  Throws:
  
  IllegalStateException - if the value is not mutable.
  
  setValue
  
  public final void setValue(com.neeve.io.IOBuffer source, int offset, int length, boolean wrap)
  
  Set the raw value of the String using the value in the given buffer.
  
  Parameters:
  source - The buffer
  offset - The offset into the buffer
  length - The length of the serialized string
  wrap - Whether to wrap the XString's buffer around the supplied buffer.
  
  Throws:
  
  IllegalStateException - if the value is not mutable.
  
  setValue
  
  public final void setValue(ByteBuffer source, int position, int length)
  
  Set the value of the XString to that of the given ByteBuffer. The value is copied from the specified buffer position. The ByteBuffer's position and limit are left unchanged.
  
  Parameters:
  source - The CharSequence value.
  position - The position in the buffer at which the serialized String's bytes start.
  length - The number of bytes to copy. The caller needs to ensure that the supplied buffer's limit is >= supplied position + length
  
  Throws:
  
  IllegalStateException - if the value is not mutable or if limit is < supplied position + length
  
  setValue
  
  public final void setValue(ByteBuffer source)
  
  Set the value of the XString to that of the given ByteBuffer. The value is copied from the buffers current position to the buffer's limit. The ByteBuffer's position and limit are left unchanged.
  
  Parameters:
  source - The CharSequence value.
  
  Throws:
  
  IllegalStateException - if the value is not mutable.
  
  copyInto
  
  public final XString copyInto(XString target)
  
  Copy this XString into another XString.
  If the target XString is uninitialized or mutable, and its backing buffer is large enough to hold the contents of this XString then it will be used as the target of the copy operation (a zero garbage operation).
  Otherwise a new XString will be allocated and returned.
  
  Parameters:
  target - The target into which the XString was copied which may be different depending on the initialization state and backing buffer size of the target.
  
  Returns:
  The XString into which this XString has been copied.
  
  copyInto
  
  public final <T extends com.neeve.io.IOElasticBuffer> T copyInto(T target, int offset)
  
  Serialize this XString into an IOElasticBuffer.
  
  Parameters:
  offset - The offset into the IOElasticBuffer to copy.
  
  Returns:
  The supplied IOElasticBuffer or null if this wrapped value is unset i.e. no string or buffer
  
  copyInto
  
  public final int copyInto(com.neeve.io.IOBuffer target, int offset)
  
  Serialize this XString into an IOBuffer.
  This method is not intended for use by end users without guidance from Neeve support. In particular it is not generally safe to operate on an IOBuffer wrapped by an IOElasticBuffer; this method should only be be used on an independent IOBuffer. If the IOBuffer is owned by an IOElasticBuffer then the copyInto(IOElasticBufffer, offset) method should be used.
  
  Parameters:
  offset - The offset into the IOBuffer to copy.
  
  Throws:
  
  IllegalArgumentException - If the target buffer doesn't have sufficient capacity to hold this String's content.
  
  copyInto
  
  public final int copyInto(ByteBuffer target, int position)
  
  Serialize the string into the given buffer at the given position. The provided buffer's markers are ignored even if data is copied outside of the buffer's current position and limit. The buffer's position and limit are unchanged by this method - it is left to the caller to update them according to the number of bytes writen as returned by this method.
  
  Parameters:
  target - The buffer into which to serialize the the XString
  position - The position in the buffer to which to serialize.
  
  Returns:
  the number of byte copied into the buffer.
  
  reset
  
  public final void reset()
  
  Clear the value for this XString.
  
  clear
  
  public final void clear() throws IllegalStateException
  
  Clears the value of the XString.
  
  Throws:
  
  IllegalStateException - If the XString is not mutable
  
  isEmpty
  
  public final boolean isEmpty()
  
  Returns true if the XString is either null or has length 0.
  
  Returns:
  true if the XString is either 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.
  
  getSerializedLength
  
  public final int getSerializedLength()
  
  Return the XString's serialized length. Given it's character encoding, this may be different than it's length().
  
  Returns:
  The serialized length of this XString
  
  getBackingBuffer
  
  public final com.neeve.io.IOElasticBuffer getBackingBuffer()
  
  Gets the underlying io buffer backing this XString. This method is not intended for use by application code.
  
  Returns:
  The String's backing buffer.
  
  getBackingBufferOffset
  
  public final int getBackingBufferOffset()
  
  Get the underlying io buffer offset for this XString. This method is not intended for use by application code.
  
  Returns:
  The offset into the string's backing buffer.
  
  append
  
  public final XString append(XString source)
  
  Appends the contents of the given XString into this XString.
  If the source XString is not initialized, empty or 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 value is not mutable.
  
  append
  
  public final XString append(ByteBuffer value)
  
  Append the given ByteBuffer's remaining bytes to the end of this XString.
  The value is copied from the buffers current position to the buffer's limit. The ByteBuffer's position and limit are left unchanged.
  
  Parameters:
  value - The ByteBuffer value.
  
  Returns:
  The XString for invocation chaining
  
  Throws:
  
  IllegalStateException - if the value is not mutable.
  
  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 value is not mutable.
  
  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 is not mutable.
  
  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 value is not mutable.
  
  IllegalArgumentException - if the valueOffset or valueLength is outside the bounds of the provided array.
  
  append
  
  public final XString append(boolean value)
  
  Appends the given boolean value in String format to the end of this XString.
  
  Parameters:
  value - The boolean to append.
  
  Returns:
  The XString for invocation chaining
  
  Throws:
  
  IllegalStateException - if this string is not mutable.
  
  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 value is not mutable.
  
  IllegalArgumentException - If the character is not a us-ascii character.
  
  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 value is not mutable.
  
  IllegalArgumentException - If the character is not a us-ascii character.
  
  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 value is not mutable.
  
  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 value is not mutable.
  
  IllegalArgumentException - If any of the characters is not a us-ascii character.
  
  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 value is not mutable.
  
  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.
  Calling this method with a null value has no effect other than throwing an IllegalStateException if this XString is not mutable.
  
  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 value is not mutable.
  
  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.
  
  length
  
  public final int length()
  
  Returns the length in characters of the XString.
  NOTE: Currently this is only reliable for XStrings composed entirely of ASCII characters, and this call is currently synonymous with getSerializedLength(). It is anticipated that support for non ascii characters will be added in a future release, so it is advisable for applications to code for this eventuality.
  
  Specified by:
  
  length in interface CharSequence
  
  Returns:
  The length of the XString.
  
  charAt
  
  public final char charAt(int index) throws IndexOutOfBoundsException
  
  Returns the character at the given position.
  NOTE: Currently this is only reliable for XString composed entirely of ASCII characters.
  
  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()
  
  padForNullTerminator
  
  public void padForNullTerminator()
  
  Pads the backing buffer by an additional byte to accomodate c style null terminator.
  This method is useful when the XString will be used with native code that may need to suffix the XString's with a null terminator character, it ensure that there is at least one additional byte in the XString's backing buffer.
  
  toString
  
  public String toString()
  
  Return the String value of this XString as returned by getValue()
  
  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 limitations 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 a 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 (!initialized) { return 0; } final int sLength = getSerializedLength(); if (sLength == 0) { return 0; } int h = 1; for (int p = offset; p < sLength; p++) { h = 31 * h + buffer.get(p); } return h;
  
  Overrides:
  
  hashCode in class Object
  
  Returns:
  The current hash code of this XString

Class XString

Zero Garbage Preallocation

Zero Copy/Reencode Serializable Field Transfer

Immutability of XString

Character Encoding

CharSequence view

Equality and hashCode

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

create

create

create

create

create

create

create

startsWith

startsWith

indexOf

indexOf

indexOf

indexOf

compareTo

isNativeXStringEnabled

isMutable

getValue

subSequence

initialize

initializeFrom

isInitialized

isImmutable

setValue

setValue

copyFrom

copyFromNative

copyFromMemory

setValueFromMemory

copyFrom

setValue

setValue

setValue

setValue

setValue

setValue

getValueAsLong

getValueAsLongDecimal

getValueAsLong

setCharAt

setValue

setValue

setValue

setValue

copyInto

copyInto

copyInto

copyInto

reset

clear

isEmpty

isNull

getSerializedLength

getBackingBuffer

getBackingBufferOffset

append

append

append

append

append

append

append

append

append

append

append

length

charAt

padForNullTerminator

toString

Immutability of `XString`