org.ObjectLayout

Class StructuredArray<T>

java.lang.Object

org.ObjectLayout.StructuredArray<T>

Type Parameters:

T - The class of the array elements

All Implemented Interfaces:

java.lang.Iterable<T>

public class StructuredArray<T>
extends java.lang.Object
implements java.lang.Iterable<T>

An array of non-replaceable objects.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	StructuredArray.ElementIterator Specialised Iterator with the ability to be StructuredArray.ElementIterator.reset() enabling reuse.

Method Summary

Modifier and Type	Method and Description
static <S extends StructuredArray<T>,T> S	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> S	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> S	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> S	copyInstance(S source) Copy a given array of elements to a newly created array.
static <S extends StructuredArray<T>,T> S	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> S	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> S	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> S	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> S	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> S	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> S	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> S	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> S	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> S	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> S	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> S	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> S	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> void	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> void	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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

newInstance

public 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. Using the elementClass's default constructor.

Type Parameters:

T - The class of the array elements

Parameters:

elementClass - of each element in the array

length - of the array to create

Returns:

The newly created array

newInstance

public 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. Using the elementClass's default constructor.

Type Parameters:

T - The class of the array elements

Parameters:

lookup - The lookup object to use when resolving constructors

elementClass - of each element in the array

length - of the array to create

Returns:

The newly created array

newInstance

public static <S extends StructuredArray<T>,T> S newInstance(java.lang.Class<S> arrayClass,
                                                             java.lang.Class<T> elementClass,
                                                             long length)

Create an arrayClass array of length elements of type elementClass. Using the elementClass's default constructor.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

arrayClass - of the array to create

elementClass - of each element in the array

length - of the array to create

Returns:

The newly created array

newInstance

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

Create an arrayClass array of length elements of type elementClass. Using the elementClass's default constructor.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

lookup - The lookup object to use when resolving constructors

arrayClass - of the array to create

elementClass - of each element in the array

length - of the array to create

Returns:

The newly created array

newInstance

public static <S extends StructuredArray<T>,T> S newInstance(CtorAndArgs<S> arrayCtorAndArgs,
                                                             java.lang.Class<T> elementClass,
                                                             long length)

Create an arrayCtorAndArgs.getConstructor().getDeclaringClass() array of length elements of type elementClass. Use elementClass's default constructor.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

arrayCtorAndArgs - for creating the array

elementClass - of each element in the array

length - of the array to create

Returns:

The newly created array

newInstance

public static <S extends StructuredArray<T>,T> S 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. Use elementClass's default constructor.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

lookup - The lookup object to use when resolving constructors

arrayCtorAndArgs - for creating the array

elementClass - of each element in the array

length - of the array to create

Returns:

The newly created array

newInstance

public static <S extends StructuredArray<T>,T> S newInstance(CtorAndArgs<S> arrayCtorAndArgs,
                                                             CtorAndArgs<T> elementCtorAndArgs,
                                                             long length)

Create an arrayCtorAndArgs.getConstructor().getDeclaringClass() array of length elements of type elementClass. Use elementClass's default constructor.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

arrayCtorAndArgs - for creating the array

elementCtorAndArgs - of each element in the array

length - of the array to create

Returns:

The newly created array

newInstance

public static <T> StructuredArray<T> newInstance(java.lang.Class<T> elementClass,
                                                 CtorAndArgsProvider<T> ctorAndArgsProvider,
                                                 long length)

Create an 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.

Type Parameters:

T - The class of the array elements

Parameters:

elementClass - of each element in the array

ctorAndArgsProvider - produces element constructors [potentially] on a per element basis

length - of the array to create

Returns:

The newly created array

newInstance

public static <S extends StructuredArray<T>,T> S 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. Use constructor and arguments supplied (on a potentially per element index basis) by the specified ctorAndArgsProvider to construct and initialize each element.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

arrayClass - of the array to create.

elementClass - of each element in the array

length - of the array to create

ctorAndArgsProvider - produces element constructors [potentially] on a per element basis

Returns:

The newly created array

newInstance

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

Create an 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.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

lookup - The lookup object to use when resolving constructors

arrayClass - of the array to create.

elementClass - of each element in the array

length - of the array to create

ctorAndArgsProvider - produces element constructors [potentially] on a per element basis

Returns:

The newly created array

newInstance

public static <S extends StructuredArray<T>,T> S 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. Use constructor and arguments supplied (on a potentially per element index basis) by the specified ctorAndArgsProvider to construct and initialize each element.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

arrayCtorAndArgs - of the array to create

elementClass - of each element in the array

length - of the array to create

ctorAndArgsProvider - produces element constructors [potentially] on a per element basis

Returns:

The newly created array

newInstance

public static <S extends StructuredArray<T>,T> S 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.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

arrayClass - of the array to create.

elementClass - of each element in the array

sourceCollection - provides details for building the array

Returns:

The newly created array

newInstance

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

Create a <S extends StructuredArray<T>> array instance with elements copied from a source collection.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

lookup - The lookup object to use when resolving constructors

arrayClass - of the array to create.

elementClass - of each element in the array

sourceCollection - provides details for building the array

Returns:

The newly created array

newInstance

public static <S extends StructuredArray<T>,T> S newInstance(StructuredArrayBuilder<S,T> arrayBuilder)

Create a <S extends StructuredArray<T>> array instance according to the details provided in the arrayBuilder.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

arrayBuilder - provides details for building the array

Returns:

The newly created array

copyInstance

public static <S extends StructuredArray<T>,T> S copyInstance(S source)

Copy a given array of elements to a newly created array. Copying of individual elements is done by using the elementClass copy constructor to construct the individual member elements of the new array based on the corresponding elements of the source array.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

source - The array to duplicate

Returns:

The newly created array

copyInstance

public static <S extends StructuredArray<T>,T> S copyInstance(java.lang.invoke.MethodHandles.Lookup lookup,
                                                              S source)

Copy a given array of elements to a newly created array. Copying of individual elements is done by using the elementClass copy constructor to construct the individual member elements of the new array based on the corresponding elements of the source array.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

lookup - The lookup object to use when resolving constructors

source - The array to duplicate

Returns:

The newly created array

copyInstance

public static <S extends StructuredArray<T>,T> S copyInstance(S source,
                                                              long sourceOffset,
                                                              long count)

Copy a range from an array of elements to a newly created array. Copying of individual elements is done by using the elementClass copy constructor to construct the individual member elements of the new array based on the corresponding elements of the source array.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

source - The array to copy from

sourceOffset - offset index, indicating where the source region to be copied begins

count - the number of elements to copy

Returns:

The newly created array

copyInstance

public static <S extends StructuredArray<T>,T> S 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. Copying of individual elements is done by using the elementClass copy constructor to construct the individual member elements of the new array based on the corresponding elements of the source array.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

lookup - The lookup object to use when resolving constructors

source - The array to copy from

sourceOffset - offset index, indicating where the source region to be copied begins

count - the number of elements to copy

Returns:

The newly created array

copyInstance

public static <S extends StructuredArray<T>,T> S copyInstance(S source,
                                                              long[] sourceOffsets,
                                                              long[] counts)

Copy a range from an array of elements to a newly created array. Copying of individual elements is done by using the 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.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

source - The array to copy from

sourceOffsets - offset indexes, indicating where the source region to be copied begins at each StructuredArray nesting depth

counts - the number of elements to copy at each StructuredArray nesting depth

Returns:

The newly created array

copyInstance

public static <S extends StructuredArray<T>,T> S 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. Copying of individual elements is done by using the 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.

Type Parameters:

S - The class of the array to be created

T - The class of the array elements

Parameters:

lookup - The lookup object to use when resolving constructors

source - The array to copy from

sourceOffsets - offset indexes, indicating where the source region to be copied begins at each StructuredArray nesting depth

counts - the number of elements to copy at each StructuredArray nesting depth

Returns:

The newly created array

getLength

public long getLength()

Get the length (number of elements) of the array.

Returns:

the number of elements in the array.

getElementClass

public java.lang.Class<T> getElementClass()

Get the Class of elements stored in the array.

Returns:

the Class of elements stored in the array.

getArrayModel

public StructuredArrayModel<? extends StructuredArray<T>,T> getArrayModel()

Get the array model

Returns:

a model of this array

get

public T get(long index)
      throws java.lang.IllegalArgumentException

Get a reference to an element in a single dimensional array, using a long index.

Parameters:

index - of the element to retrieve.

Returns:

a reference to the indexed element.

Throws:

java.lang.IllegalArgumentException

get

public T get(int index)
      throws java.lang.IllegalArgumentException

Get a reference to an element in a single dimensional array, using an int index.

Parameters:

index - of the element to retrieve.

Returns:

a reference to the indexed element.

Throws:

java.lang.IllegalArgumentException

iterator

public StructuredArray.ElementIterator iterator()

Specified by:

iterator in interface java.lang.Iterable<T>

shallowCopy

public static <S extends StructuredArray<T>,T> void 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.

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.

Type Parameters:

S - The class of the arrays

T - The class of the array elements

Parameters:

src - array to copy

srcOffset - offset index in src where the region begins

dst - array into which the copy should occur

dstOffset - offset index in the dst where the region begins

count - of structure elements to copy

Throws:

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.

shallowCopy

public static <S extends StructuredArray<T>,T> void 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.

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.

Type Parameters:

S - The class of the arrays

T - The class of the array elements

Parameters:

src - array to copy

srcOffset - offset index in src where the region begins

dst - array into which the copy should occur

dstOffset - offset index in the dst where the region begins

count - of structure elements to copy.

allowFinalFieldOverwrite - allow final fields to be overwritten during a copy operation.

Throws:

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.