XStringSequence (Talon 3.16.63 API)

java.lang.Object
- com.neeve.lang.XStringSequence

All Implemented Interfaces:

XIterator<String>, XStringIterator, com.neeve.quark.QuarkStringIterator, Iterator<String>
```
public final class XStringSequence
extends Object
implements com.neeve.quark.QuarkStringIterator
```
Wraps a set of bytes representing a serialized sequence of strings.
An XStringSequence stores a set of bytes in native memory. Its views the stored bytes as a sequence of strings and provides methods to read and modify these values.

To use an instance of this class, the user first needs to initialize the instance by wrapping it around a memory region containing the serialized string sequence. This is done using one of the wrap() or setFrom() methods. Once the instance has been initialized, the user can use the data accessor and modification methods to access and/or modify the the sequence managed by this class.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static XStringSequence`	`create()` Create a new string sequence reader
`int`	`getTo(byte[] val, int offset)` Copy the serialized string sequence to a byte array object
`int`	`getTo(long addr, int offset)` Copy the serialized string sequence to a native memory region
`int`	`getTo(com.neeve.quark.QuarkBuffer val, int offset)` Copy the serialized string sequence to a `QuarkBuffer`
`boolean`	`hasNext()` Implementation of `Iterator.hasNext()`
`boolean`	`isInitialized()` Get if the sequence has been initialized or nor
`boolean`	`isOwned()` Get if the sequence was initialized by copying or wrapping
`com.neeve.quark.QuarkStringIterator`	`iterator()` Get an iterator to iterate over a string sequence values
`String`	`next()` Implementation of `Iterator.next()`
`short`	`nextInto(long addr, int offset)` Implementation of `QuarkStringIterator.nextInto(long, int)`
`short`	`nextInto(com.neeve.quark.QuarkString to)` Implementation of `QuarkStringIterator.nextInto(QuarkString)`
`void`	`nextInto(XString to)` Implementation of `XStringIterator.nextInto(XString)`
`int`	`nextLength()` Implementation of `QuarkStringIterator.nextLength(boolean)`
`int`	`nextLength(boolean advance)` Implementation of `QuarkStringIterator.nextLength(boolean)`
`void`	`remove()` Implementation of `Iterator.remove()`
`XStringSequence`	`reset()` Reset a string sequence
`int`	`serializedLength()` Get the serialized length of a string sequence
`XStringSequence`	`setFrom(long addr, int offset, int len)` Initialize a sequence by copying a string sequence serialized in a native memory region to a private backing store
`XStringSequence`	`setFrom(com.neeve.quark.QuarkBuffer buffer, int offset, int len)` Initialize a sequence by copying a string sequence serialized in a `QuarkBuffer`
`XStringSequence`	`setFrom(XStringIterator iterator)` Initialize a sequence by copying a string sequence using a `XStringIterator`
`XStringSequence`	`setFrom(XStringSequence sequence)` Initialize a sequence by copying a string sequence from a `XStringSequence`
`com.neeve.quark.QuarkStringIterator`	`toFirst()` Implementation of `XIterator.toFirst()`
`XStringSequence`	`wrap(long addr, int offset, int len)` Initialize a sequence by wrapping it around a string sequence serialized in a native memory region
`XStringSequence`	`wrap(com.neeve.quark.QuarkBuffer buffer, int offset, int len)` Initialize a sequence by wrapping it around a string sequence serialized in a `QuarkBuffer`

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

Methods inherited from interface java.util.Iterator
forEachRemaining

- Method Detail
  - create
```
public static final XStringSequence create()
```
    Create a new string sequence reader
  - isInitialized
```
public final boolean isInitialized()
```
    Get if the sequence has been initialized or nor
    
    Returns:
    
    true if sequence has been initialized and false if not
  - isOwned
```
public final boolean isOwned()
```
    Get if the sequence was initialized by copying or wrapping
    
    Returns:
    
    true if sequence was initialized by copying (setFrom() method) and false if initialized by wrapping (wrap() method)
  - toFirst
```
public com.neeve.quark.QuarkStringIterator toFirst()
```
    Implementation of XIterator.toFirst()
    
    Specified by:
    
    toFirst in interface XIterator<String>
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - hasNext
```
public final boolean hasNext()
```
    Implementation of Iterator.hasNext()
    
    Specified by:
    
    hasNext in interface Iterator<String>
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - next
```
public final String next()
```
    Implementation of Iterator.next()
    
    Specified by:
    
    next in interface Iterator<String>
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - remove
```
public final void remove()
```
    Implementation of Iterator.remove()
    
    Specified by:
    
    remove in interface Iterator<String>
  - nextLength
```
public final int nextLength(boolean advance)
```
    Implementation of QuarkStringIterator.nextLength(boolean)
    
    Specified by:
    
    nextLength in interface com.neeve.quark.QuarkStringIterator
    
    Returns:
    
    Returns the length of the next field
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - nextLength
```
public final int nextLength()
```
    Implementation of QuarkStringIterator.nextLength(boolean)
    
    Specified by:
    
    nextLength in interface com.neeve.quark.QuarkStringIterator
    
    Returns:
    
    Returns the length of the next field
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - nextInto
```
public final void nextInto(XString to)
```
    Implementation of XStringIterator.nextInto(XString)
    
    Specified by:
    
    nextInto in interface XStringIterator
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - nextInto
```
public final short nextInto(com.neeve.quark.QuarkString to)
```
    Implementation of QuarkStringIterator.nextInto(QuarkString)
    
    Specified by:
    
    nextInto in interface com.neeve.quark.QuarkStringIterator
    
    Returns:
    
    Returns the number of bytes copied
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - nextInto
```
public final short nextInto(long addr,
                            int offset)
```
    Implementation of QuarkStringIterator.nextInto(long, int)
    
    Specified by:
    
    nextInto in interface com.neeve.quark.QuarkStringIterator
    
    Returns:
    
    Returns the number of bytes copied
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - wrap
```
public final XStringSequence wrap(long addr,
                                  int offset,
                                  int len)
```
    Initialize a sequence by wrapping it around a string sequence serialized in a native memory region
    
    Parameters:
    
    addr - The address of the memory region containing the serialized string sequence
    
    offset - The offset from the start of the memory region where the serialized sequence is stored
    
    len - The length of the serialized string sequence
    
    Returns:
    
    Returns this for invocation chaining
    This method initializes a sequence's backing data pointers to a native memory region containing the serialized string sequence. This method does not make a copy of the serialized sequence. Therefore, the user must ensure that the source is not modified or freed as long as the sequence is in active use or reset() is invoked.
    
    This method can be invoked repeatedly with different backing stores. Each invocation resets all internal markers.
    
    This method implictly invokes reset() as part of its processing
  - wrap
```
public final XStringSequence wrap(com.neeve.quark.QuarkBuffer buffer,
                                  int offset,
                                  int len)
```
    Initialize a sequence by wrapping it around a string sequence serialized in a QuarkBuffer
    
    Parameters:
    
    buffer - The buffer containing the serialized string sequence
    
    offset - The offset into the buffer where the serialized string sequence is stored
    
    len - The length of the serialized string sequence
    
    Returns:
    
    Returns this for invocation chaining
    This method initializes a sequence's backing data pointers to the section of a QuarkBuffer containing the serialized string sequence. This method does not make a copy of the serialized sequence. Therefore, the user must ensure that the source is not modified or freed as long as the sequence is in active use or reset() is invoked.
    
    This method can be invoked repeatedly with different backing stores. Each invocation resets all internal markers.
    
    This method implictly invokes reset() as part of its processing
  - setFrom
```
public final XStringSequence setFrom(long addr,
                                     int offset,
                                     int len)
```
    Initialize a sequence by copying a string sequence serialized in a native memory region to a private backing store
    
    Parameters:
    
    addr - The address of the memory region containing the serialized string sequence
    
    offset - The offset from the start of the memory region where the serialized sequence is stored
    
    len - The length of the serialized string sequence
    
    Returns:
    
    Returns this for invocation chaining
    This method initializes a sequence by copying a string sequence serialized in a native memory region to a backing store that is private to the sequence object. Once done with using the sequence instance, the user must invoke reset() to release the resources held by the backing store or release the sequence object to the garbage collector in which case the backing store resources will be released when the object is collected by the garbage collector.
    
    This method can be invoked repeatedly with different backing stores. Each invocation invokes reset() and performs a fresh initialization of the backing store.
  - setFrom
```
public final XStringSequence setFrom(com.neeve.quark.QuarkBuffer buffer,
                                     int offset,
                                     int len)
```
    Initialize a sequence by copying a string sequence serialized in a QuarkBuffer
    
    Parameters:
    
    buffer - The buffer containing the serialized string sequence
    
    offset - The offset into the buffer where the serialized string sequence is stored
    
    len - The length of the serialized string sequence
    
    Returns:
    
    Returns this for invocation chaining
    This method initializes a sequence by copying a string sequence serialized in a QuarkBuffer to a backing store that is private to the sequence object. Once done with using the sequence instance, the user must invoke reset() to release the resources held by the backing store or release the sequence object to the garbage collector in which case the backing store resources will be released when the object is collected by the garbage collector.
    
    This method can be invoked repeatedly with different backing stores. Each invocation invokes reset() and performs a fresh initialization of the backing store.
  - setFrom
```
public final XStringSequence setFrom(XStringSequence sequence)
```
    Initialize a sequence by copying a string sequence from a XStringSequence
    
    Parameters:
    
    iterator - The source sequence
    
    Returns:
    
    Returns this for invocation chaining
    This method initializes a sequence by copying a string sequence from a XStringSequence to a backing store that is private to the sequence object. Once done with using the sequence instance, the user must invoke reset() to release the resources held by the backing store or release the sequence object to the garbage collector in which case the backing store resources will be released when the object is collected by the garbage collector.
    
    This method can be invoked repeatedly with different backing stores. Each invocation invokes reset() and performs a fresh initialization of the backing store.
  - setFrom
```
public final XStringSequence setFrom(XStringIterator iterator)
```
    Initialize a sequence by copying a string sequence using a XStringIterator
    
    Parameters:
    
    iterator - The iterator to use to access the sequence
    
    Returns:
    
    Returns this for invocation chaining
    This method initializes a sequence by copying a string sequence using a XStringIterator to a backing store that is private to the sequence object. Once done with using the sequence instance, the user must invoke reset() to release the resources held by the backing store or release the sequence object to the garbage collector in which case the backing store resources will be released when the object is collected by the garbage collector.
    
    This method can be invoked repeatedly with different backing stores. Each invocation invokes reset() and performs a fresh initialization of the backing store.
  - serializedLength
```
public final int serializedLength()
```
    Get the serialized length of a string sequence
    
    Returns:
    
    The serialized length of the sequence
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - getTo
```
public final int getTo(byte[] val,
                       int offset)
```
    Copy the serialized string sequence to a byte array object
    
    Parameters:
    
    val - The destination array object to copy to
    
    offset - The offset into the destination array to copy to
    
    Returns:
    
    The number of bytes copied
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - getTo
```
public final int getTo(long addr,
                       int offset)
```
    Copy the serialized string sequence to a native memory region
    
    Parameters:
    
    addr - The destination memory region to copy to
    
    offset - The offset into memory region to copy to
    
    Returns:
    
    The number of bytes copied
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - getTo
```
public final int getTo(com.neeve.quark.QuarkBuffer val,
                       int offset)
```
    Copy the serialized string sequence to a QuarkBuffer
    
    Parameters:
    
    val - The destination buffer to copy to
    
    offset - The offset into buffer to copy to
    
    Returns:
    
    The number of bytes copied
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - iterator
```
public final com.neeve.quark.QuarkStringIterator iterator()
```
    Get an iterator to iterate over a string sequence values
    
    Returns:
    
    The returned iterator
    
    Throws:
    
    IllegalStateException - Thrown if the sequence has not been initialized via a wrap() or setFrom method
  - reset
```
public final XStringSequence reset()
```
    Reset a string sequence
    
    Returns:
    
    Returns this for invocation chaining
    This method resets a string sequence. It releases all resources used by the sequence's private backing store

Class XStringSequence

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Iterator

Method Detail

create

isInitialized

isOwned

toFirst

hasNext

next

remove

nextLength

nextLength

nextInto

nextInto

nextInto

wrap

wrap

setFrom

setFrom

setFrom

setFrom

serializedLength

getTo

getTo

getTo

iterator

reset