T
- The class of the array elementspublic class StructuredArray<T>
extends java.lang.Object
implements java.lang.Iterable<T>
A structured array contains array element objects of a fixed (at creation time, per array instance) class,
and can support elements of any class that provides accessible constructors. The elements in a StructuredArray
are all allocated and constructed at array creation time, and individual elements cannot be removed or
replaced after array creation. Array elements can be accessed using an index-based accessor methods in
the form of get(long)
() using either int or long indices. Individual element contents
can then be accessed and manipulated using any and all operations supported by the member element's class.
While simple creation of default-constructed elements and fixed constructor parameters are available through
the newInstance factory methods, supporting arbitrary member types requires a wider range of construction
options. The CtorAndArgsProvider
API provides for array creation with arbitrary, user-supplied
constructors and arguments, the selection of which can take the element index and construction context
into account.
StructuredArray is designed with semantics specifically chosen and restricted such that a "flat" memory layout of the implemented data structure would be possible on optimizing JVMs. Doing so provides for the possibility of matching access speed benefits that exist in data structures with similar semantics that are supported in other languages (e.g. an array of structs in C-like languages). While fully functional on all JVM implementation (of Java SE 6 and above), the semantics are such that a JVM may transparently optimise the implementation to provide a compact contiguous layout that facilitates consistent stride based memory access and dead-reckoning (as opposed to de-referenced) access to elements
Modifier and Type | Class and Description |
---|---|
class |
StructuredArray.ElementIterator
Specialised
Iterator with the ability to be StructuredArray.ElementIterator.reset() enabling reuse. |
Modifier and Type | Method and Description |
---|---|
static <S extends StructuredArray<T>,T> |
copyInstance(java.lang.invoke.MethodHandles.Lookup lookup,
S source)
Copy a given array of elements to a newly created array.
|
static <S extends StructuredArray<T>,T> |
copyInstance(java.lang.invoke.MethodHandles.Lookup lookup,
S source,
long[] sourceOffsets,
long[] counts)
Copy a range from an array of elements to a newly created array.
|
static <S extends StructuredArray<T>,T> |
copyInstance(java.lang.invoke.MethodHandles.Lookup lookup,
S source,
long sourceOffset,
long count)
Copy a range from an array of elements to a newly created array.
|
static <S extends StructuredArray<T>,T> |
copyInstance(S source)
Copy a given array of elements to a newly created array.
|
static <S extends StructuredArray<T>,T> |
copyInstance(S source,
long[] sourceOffsets,
long[] counts)
Copy a range from an array of elements to a newly created array.
|
static <S extends StructuredArray<T>,T> |
copyInstance(S source,
long sourceOffset,
long count)
Copy a range from an array of elements to a newly created array.
|
T |
get(int index)
Get a reference to an element in a single dimensional array, using an
int index. |
T |
get(long index)
Get a reference to an element in a single dimensional array, using a
long index. |
StructuredArrayModel<? extends StructuredArray<T>,T> |
getArrayModel()
Get the array model
|
java.lang.Class<T> |
getElementClass()
Get the
Class of elements stored in the array. |
long |
getLength()
Get the length (number of elements) of the array.
|
StructuredArray.ElementIterator |
iterator() |
static <S extends StructuredArray<T>,T> |
newInstance(java.lang.Class<S> arrayClass,
java.lang.Class<T> elementClass,
java.util.Collection<T> sourceCollection)
Create a <S extends StructuredArray<T>> array instance with elements copied from a source
collection.
|
static <S extends StructuredArray<T>,T> |
newInstance(java.lang.Class<S> arrayClass,
java.lang.Class<T> elementClass,
long length)
Create an
arrayClass array of length elements of
type elementClass . |
static <S extends StructuredArray<T>,T> |
newInstance(java.lang.Class<S> arrayClass,
java.lang.Class<T> elementClass,
long length,
CtorAndArgsProvider<T> ctorAndArgsProvider)
Create an
arrayClass array of length elements, each containing an element object of
type elementClass . |
static <T> StructuredArray<T> |
newInstance(java.lang.Class<T> elementClass,
CtorAndArgsProvider<T> ctorAndArgsProvider,
long length)
Create an array of
length elements of type elementClass . |
static <T> StructuredArray<T> |
newInstance(java.lang.Class<T> elementClass,
long length)
Create an array of
length elements, each containing an element object of
type elementClass . |
static <S extends StructuredArray<T>,T> |
newInstance(CtorAndArgs<S> arrayCtorAndArgs,
java.lang.Class<T> elementClass,
long length)
Create an
arrayCtorAndArgs.getConstructor().getDeclaringClass() array of length
elements of type elementClass . |
static <S extends StructuredArray<T>,T> |
newInstance(CtorAndArgs<S> arrayCtorAndArgs,
java.lang.Class<T> elementClass,
long length,
CtorAndArgsProvider<T> ctorAndArgsProvider)
Create an
arrayCtorAndArgs.getConstructor().getDeclaringClass() array of length
elements of type elementClass . |
static <S extends StructuredArray<T>,T> |
newInstance(CtorAndArgs<S> arrayCtorAndArgs,
CtorAndArgs<T> elementCtorAndArgs,
long length)
Create an
arrayCtorAndArgs.getConstructor().getDeclaringClass() array of length
elements of type elementClass . |
static <S extends StructuredArray<T>,T> |
newInstance(java.lang.invoke.MethodHandles.Lookup lookup,
java.lang.Class<S> arrayClass,
java.lang.Class<T> elementClass,
java.util.Collection<T> sourceCollection)
Create a <S extends StructuredArray<T>> array instance with elements copied from a source
collection.
|
static <S extends StructuredArray<T>,T> |
newInstance(java.lang.invoke.MethodHandles.Lookup lookup,
java.lang.Class<S> arrayClass,
java.lang.Class<T> elementClass,
long length)
Create an
arrayClass array of length elements of
type elementClass . |
static <S extends StructuredArray<T>,T> |
newInstance(java.lang.invoke.MethodHandles.Lookup lookup,
java.lang.Class<S> arrayClass,
java.lang.Class<T> elementClass,
long length,
CtorAndArgsProvider<T> ctorAndArgsProvider)
Create an
arrayClass array of length elements, each containing an element object of
type elementClass . |
static <T> StructuredArray<T> |
newInstance(java.lang.invoke.MethodHandles.Lookup lookup,
java.lang.Class<T> elementClass,
long length)
Create an array of
length elements, each containing an element object of
type elementClass . |
static <S extends StructuredArray<T>,T> |
newInstance(java.lang.invoke.MethodHandles.Lookup lookup,
CtorAndArgs<S> arrayCtorAndArgs,
java.lang.Class<T> elementClass,
long length)
Create an
arrayCtorAndArgs.getConstructor().getDeclaringClass() array of length
elements of type elementClass . |
static <S extends StructuredArray<T>,T> |
newInstance(StructuredArrayBuilder<S,T> arrayBuilder)
Create a <S extends StructuredArray<T>> array instance according to the details provided in the
arrayBuilder.
|
static <S extends StructuredArray<T>,T> |
shallowCopy(S src,
long srcOffset,
S dst,
long dstOffset,
long count)
Shallow copy a region of element object contents from one array to the other.
|
static <S extends StructuredArray<T>,T> |
shallowCopy(S src,
long srcOffset,
S dst,
long dstOffset,
long count,
boolean allowFinalFieldOverwrite)
Shallow copy a region of element object contents from one array to the other.
|
public static <T> StructuredArray<T> newInstance(java.lang.Class<T> elementClass, long length)
length
elements, each containing an element object of
type elementClass
. Using the elementClass
's default constructor.T
- The class of the array elementselementClass
- of each element in the arraylength
- of the array to createpublic static <T> StructuredArray<T> newInstance(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class<T> elementClass, long length)
length
elements, each containing an element object of
type elementClass
. Using the elementClass
's default constructor.T
- The class of the array elementslookup
- The lookup object to use when resolving constructorselementClass
- of each element in the arraylength
- of the array to createpublic static <S extends StructuredArray<T>,T> S newInstance(java.lang.Class<S> arrayClass, java.lang.Class<T> elementClass, long length)
arrayClass
array of length
elements of
type elementClass
. Using the elementClass
's default constructor.S
- The class of the array to be createdT
- The class of the array elementsarrayClass
- of the array to createelementClass
- of each element in the arraylength
- of the array to createpublic static <S extends StructuredArray<T>,T> S newInstance(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class<S> arrayClass, java.lang.Class<T> elementClass, long length)
arrayClass
array of length
elements of
type elementClass
. Using the elementClass
's default constructor.S
- The class of the array to be createdT
- The class of the array elementslookup
- The lookup object to use when resolving constructorsarrayClass
- of the array to createelementClass
- of each element in the arraylength
- of the array to createpublic static <S extends StructuredArray<T>,T> S newInstance(CtorAndArgs<S> arrayCtorAndArgs, java.lang.Class<T> elementClass, long length)
arrayCtorAndArgs.getConstructor().getDeclaringClass()
array of length
elements of type elementClass
. Use elementClass
's default constructor.S
- The class of the array to be createdT
- The class of the array elementsarrayCtorAndArgs
- for creating the arrayelementClass
- of each element in the arraylength
- of the array to createpublic static <S extends StructuredArray<T>,T> S newInstance(java.lang.invoke.MethodHandles.Lookup lookup, CtorAndArgs<S> arrayCtorAndArgs, java.lang.Class<T> elementClass, long length)
arrayCtorAndArgs.getConstructor().getDeclaringClass()
array of length
elements of type elementClass
. Use elementClass
's default constructor.S
- The class of the array to be createdT
- The class of the array elementslookup
- The lookup object to use when resolving constructorsarrayCtorAndArgs
- for creating the arrayelementClass
- of each element in the arraylength
- of the array to createpublic static <S extends StructuredArray<T>,T> S newInstance(CtorAndArgs<S> arrayCtorAndArgs, CtorAndArgs<T> elementCtorAndArgs, long length)
arrayCtorAndArgs.getConstructor().getDeclaringClass()
array of length
elements of type elementClass
. Use elementClass
's default constructor.S
- The class of the array to be createdT
- The class of the array elementsarrayCtorAndArgs
- for creating the arrayelementCtorAndArgs
- of each element in the arraylength
- of the array to createpublic static <T> StructuredArray<T> newInstance(java.lang.Class<T> elementClass, CtorAndArgsProvider<T> ctorAndArgsProvider, long length)
length
elements of type elementClass
. Use constructor and
arguments supplied (on a potentially per element index basis) by the specified
ctorAndArgsProvider
to construct and initialize each element.T
- The class of the array elementselementClass
- of each element in the arrayctorAndArgsProvider
- produces element constructors [potentially] on a per element basislength
- of the array to createpublic static <S extends StructuredArray<T>,T> S newInstance(java.lang.Class<S> arrayClass, java.lang.Class<T> elementClass, long length, CtorAndArgsProvider<T> ctorAndArgsProvider)
arrayClass
array of length
elements, each containing an element object of
type elementClass
. Use constructor and arguments supplied (on a potentially
per element index basis) by the specified ctorAndArgsProvider
to construct and initialize
each element.S
- The class of the array to be createdT
- The class of the array elementsarrayClass
- of the array to create.elementClass
- of each element in the arraylength
- of the array to createctorAndArgsProvider
- produces element constructors [potentially] on a per element basispublic static <S extends StructuredArray<T>,T> S newInstance(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class<S> arrayClass, java.lang.Class<T> elementClass, long length, CtorAndArgsProvider<T> ctorAndArgsProvider)
arrayClass
array of length
elements, each containing an element object of
type elementClass
. Use constructor and arguments supplied (on a potentially
per element index basis) by the specified ctorAndArgsProvider
to construct and initialize
each element.S
- The class of the array to be createdT
- The class of the array elementslookup
- The lookup object to use when resolving constructorsarrayClass
- of the array to create.elementClass
- of each element in the arraylength
- of the array to createctorAndArgsProvider
- produces element constructors [potentially] on a per element basispublic static <S extends StructuredArray<T>,T> S newInstance(CtorAndArgs<S> arrayCtorAndArgs, java.lang.Class<T> elementClass, long length, CtorAndArgsProvider<T> ctorAndArgsProvider)
arrayCtorAndArgs.getConstructor().getDeclaringClass()
array of length
elements of type elementClass
. Use constructor and arguments
supplied (on a potentially per element index basis) by the specified ctorAndArgsProvider
to construct and initialize each element.S
- The class of the array to be createdT
- The class of the array elementsarrayCtorAndArgs
- of the array to createelementClass
- of each element in the arraylength
- of the array to createctorAndArgsProvider
- produces element constructors [potentially] on a per element basispublic static <S extends StructuredArray<T>,T> S newInstance(java.lang.Class<S> arrayClass, java.lang.Class<T> elementClass, java.util.Collection<T> sourceCollection)
S
- The class of the array to be createdT
- The class of the array elementsarrayClass
- of the array to create.elementClass
- of each element in the arraysourceCollection
- provides details for building the arraypublic static <S extends StructuredArray<T>,T> S newInstance(java.lang.invoke.MethodHandles.Lookup lookup, java.lang.Class<S> arrayClass, java.lang.Class<T> elementClass, java.util.Collection<T> sourceCollection)
S
- The class of the array to be createdT
- The class of the array elementslookup
- The lookup object to use when resolving constructorsarrayClass
- of the array to create.elementClass
- of each element in the arraysourceCollection
- provides details for building the arraypublic static <S extends StructuredArray<T>,T> S newInstance(StructuredArrayBuilder<S,T> arrayBuilder)
S
- The class of the array to be createdT
- The class of the array elementsarrayBuilder
- provides details for building the arraypublic static <S extends StructuredArray<T>,T> S copyInstance(S source)
elementClass
copy constructor to construct the individual member elements of the new
array based on the corresponding elements of the source
array.S
- The class of the array to be createdT
- The class of the array elementssource
- The array to duplicatepublic static <S extends StructuredArray<T>,T> S copyInstance(java.lang.invoke.MethodHandles.Lookup lookup, S source)
elementClass
copy constructor to construct the individual member elements of the new
array based on the corresponding elements of the source
array.S
- The class of the array to be createdT
- The class of the array elementslookup
- The lookup object to use when resolving constructorssource
- The array to duplicatepublic static <S extends StructuredArray<T>,T> S copyInstance(S source, long sourceOffset, long count)
elementClass
copy constructor to construct the individual member elements of
the new array based on the corresponding elements of the source
array.S
- The class of the array to be createdT
- The class of the array elementssource
- The array to copy fromsourceOffset
- offset index, indicating where the source region to be copied beginscount
- the number of elements to copypublic static <S extends StructuredArray<T>,T> S copyInstance(java.lang.invoke.MethodHandles.Lookup lookup, S source, long sourceOffset, long count)
elementClass
copy constructor to construct the individual member elements of
the new array based on the corresponding elements of the source
array.S
- The class of the array to be createdT
- The class of the array elementslookup
- The lookup object to use when resolving constructorssource
- The array to copy fromsourceOffset
- offset index, indicating where the source region to be copied beginscount
- the number of elements to copypublic static <S extends StructuredArray<T>,T> S copyInstance(S source, long[] sourceOffsets, long[] counts)
elementClass
copy constructor to construct the individual member elements of
the new array based on the corresponding elements of the source
array.
This form is useful [only] for copying partial ranges from nested StructuredArrays.
S
- The class of the array to be createdT
- The class of the array elementssource
- The array to copy fromsourceOffsets
- offset indexes, indicating where the source region to be copied begins at each
StructuredArray nesting depthcounts
- the number of elements to copy at each StructuredArray nesting depthpublic static <S extends StructuredArray<T>,T> S copyInstance(java.lang.invoke.MethodHandles.Lookup lookup, S source, long[] sourceOffsets, long[] counts)
elementClass
copy constructor to construct the individual member elements of
the new array based on the corresponding elements of the source
array.
This form is useful [only] for copying partial ranges from nested StructuredArrays.
S
- The class of the array to be createdT
- The class of the array elementslookup
- The lookup object to use when resolving constructorssource
- The array to copy fromsourceOffsets
- offset indexes, indicating where the source region to be copied begins at each
StructuredArray nesting depthcounts
- the number of elements to copy at each StructuredArray nesting depthpublic long getLength()
public java.lang.Class<T> getElementClass()
Class
of elements stored in the array.Class
of elements stored in the array.public StructuredArrayModel<? extends StructuredArray<T>,T> getArrayModel()
public T get(long index) throws java.lang.IllegalArgumentException
long
index.index
- of the element to retrieve.java.lang.IllegalArgumentException
public T get(int index) throws java.lang.IllegalArgumentException
int
index.index
- of the element to retrieve.java.lang.IllegalArgumentException
public StructuredArray.ElementIterator iterator()
iterator
in interface java.lang.Iterable<T>
public static <S extends StructuredArray<T>,T> void shallowCopy(S src, long srcOffset, S dst, long dstOffset, long count)
shallowCopy will copy all fields from each of the source elements to the corresponding fields in each of the corresponding destination elements. If the same array is both the src and dst then the copy will happen as if a temporary intermediate array was used.
S
- The class of the arraysT
- The class of the array elementssrc
- array to copysrcOffset
- offset index in src where the region beginsdst
- array into which the copy should occurdstOffset
- offset index in the dst where the region beginscount
- of structure elements to copyjava.lang.IllegalArgumentException
- if the source and destination array element types are not identical, or if
the source or destination arrays have nested StructuredArrays within them, or if final fields are discovered
and all allowFinalFieldOverwrite is not true.public static <S extends StructuredArray<T>,T> void shallowCopy(S src, long srcOffset, S dst, long dstOffset, long count, boolean allowFinalFieldOverwrite)
shallowCopy will copy all fields from each of the source elements to the corresponding fields in each
of the corresponding destination elements. If the same array is both the src and dst then the copy will
happen as if a temporary intermediate array was used.
If allowFinalFieldOverwrite
is specified as true
, even final fields will be copied.
S
- The class of the arraysT
- The class of the array elementssrc
- array to copysrcOffset
- offset index in src where the region beginsdst
- array into which the copy should occurdstOffset
- offset index in the dst where the region beginscount
- of structure elements to copy.allowFinalFieldOverwrite
- allow final fields to be overwritten during a copy operation.java.lang.IllegalArgumentException
- if the source and destination array element types are not identical, or if
the source or destination arrays have nested StructuredArrays within them, or if final fields are discovered
and all allowFinalFieldOverwrite is not true.