com.neeve.lang
Class XString

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

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 XStrings which does not support pooling or preallocation.

Method Summary

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

isNull

public final boolean isNull()

Return 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()

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.

Overrides:

hashCode in class Object

Returns:

The current hash code of this XString