Class CArrayFacade<T>
- java.lang.Object
-
- org.cakelab.blender.nio.CFacade
-
- org.cakelab.blender.nio.CPointer<T>
-
- org.cakelab.blender.nio.CArrayFacade<T>
-
- Type Parameters:
T
- Component type of the array.
- All Implemented Interfaces:
java.lang.Iterable<T>
public class CArrayFacade<T> extends CPointer<T> implements java.lang.Iterable<T>
This is the facade class for fixed length arrays.Arrays provide common array functionality and conversion between underlying data and corresponding Java arrays (see various toArray and fromArray methods).
Since arrays in C are interchangeable with pointers, the class inherits the capabilities of
CPointer
. This way, an array can always be assigned to a pointer variable. To turn a pointer in an instance ofCArrayFacade
use itsCPointer.toCArrayFacade(int)
.Array Types
Arrays have a component type and an elementary type. This is important when dealing with multi-dimensional arrays. The elementary type is the most basic type contained in the array. If the array is an array of arrays of int (i.e. CArrayFacade<CArrayFacade<int>>), then the elementary type is 'int' but it's component type is CArrayFacade<int>. In case the array has just one dimension, the component type and the elementary type are the same.
Arrays need runtime information about their component type. If the component type is an array or a pointer then the array needs the information about those contained types, too. Thus, arrays are instantiated with a list of types as type specification, where each element in the type list corresponds to a component type of the component type.
Detailed Example:
The following code snippet denotes an array of arrays of pointers on integers.CArrayFacade<CArrayFacade<CPointer<Integer>>> array;
To instantiate such an array, we need to specify the list of types for each component.Class[] typeList = new Class[]{ CArrayFacade.class, CArrayFacade.class, CPointer.class, Integer.class };
You will note, that we just read out the template parameters and put them in an array. The array also needs to know the length of each dimension beforehand. Thus, we create another array which holds the length for each dimension. Let's say we want an array which corresponds to the C type declaration
int* array[2][8]
.int[] dimensions = new int[]{2,8};
Finally we can create an instance of that array (given that we have an open blender file and a blockTable and the address of that array).
array = new CArrayFacade<CArrayFacade<CPointer<Integer>>>( address, typeList, dimensions, blockTable );
Remember, that arrays are just facades and the actual data is stored in a block of the blender file. Thus, the address (first parameter of the constructor) is either received from
CFacade.__io__addressof(long[])
or from a pointer or by allocating a new block.To allocate a block for an entirely new array, refer to the block allocation methods in either
BlenderFactoryBase
or the derived class BlenderFactory in the generated code or even directly toBlenderFile
andBlockTable
.- Author:
- homac
-
-
Field Summary
Fields Modifier and Type Field Description protected long
componentSize
Component size is the size in bytes of one element of this array.protected int[]
dimensions
This list contains the length of each dimension of the array.protected java.lang.Class<?>[]
targetTypeList
-
Fields inherited from class org.cakelab.blender.nio.CPointer
targetSize
-
Fields inherited from class org.cakelab.blender.nio.CFacade
__io__address, __io__arch_index, __io__block, __io__blockTable, __io__pointersize
-
-
Constructor Summary
Constructors Constructor Description CArrayFacade(long baseAddress, java.lang.Class<?>[] targetTypeList, int[] dimensions, Block block, BlockTable __blockTable)
This is the constructor to attach an array facade to existing data in a block of a blender file.CArrayFacade(CArrayFacade<T> other)
Copy constructor.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description protected void
__io__generic__copy(CFacade sourceArray)
This method does a highlevel copy of the given source to this object.static long
__io__sizeof(java.lang.Class<?> elementaryType, int[] dimensions, Encoding encoding)
Calculates the total size of an array based on the given parameters.java.lang.String
asString()
Converts the array into a string.void
fromArray(T[] data)
Copyies all elements of the given array to this array.void
fromByteArray(byte[] data)
Copies all values of the given Java array to this array.void
fromString(java.lang.String str)
Fills the underlying buffer with a null-terminated string from the given string using the default charset (seeCharset.defaultCharset()
).void
fromString(java.lang.String str, boolean addNullTermination)
Fills the underlying buffer with the bytes of the given string str using the default charset (seeCharset.defaultCharset()
).void
fromString(java.lang.String str, java.nio.charset.Charset charset, boolean addNullTermination)
Fills the underlying buffer with the bytes of the given string str using the given charset (seeCharset
).T
get(int index)
Returns the element with the given 'index'.java.util.Iterator<T>
iterator()
For convienient iteration over this array's elements.int
length()
void
set(int index, T value)
Set the value of the array element with given 'index'.long
sizeof()
Delivers the native size of this array considering its architecture specific encoding.T[]
toArray()
Converts the underlying data into a Java array with component type T.byte[]
toByteArray()
Converts the underlying data into an array of the given native type.double[]
toDoubleArray()
Converts the underlying data into an array of the given native type.float[]
toFloatArray()
Converts the underlying data into an array of the given native type.long[]
toInt64Array()
Converts the underlying data into an array of the given native type.int[]
toIntArray()
Converts the underlying data into an array of the given native type.long[]
toLongArray()
Converts the underlying data into an array of the given native type.short[]
toShortArray()
Converts the underlying data into an array of the given native type.-
Methods inherited from class org.cakelab.blender.nio.CPointer
__get, __set, cast, cast, cast, equals, fromArray, fromArray, fromArray, fromArray, fromArray, fromArray, fromArray, fromArray, fromArray, fromArray, fromArray, fromArray, fromInt64Array, fromInt64Array, get, getAddress, getCFacade, getScalar, isNull, isPrimitive, isValid, mutable, plus, set, setScalar, toArray, toArray, toArray, toArray, toArray, toArray, toArray, toArrayInt64, toByteArray, toCArrayFacade, toDoubleArray, toFloatArray, toInt64Array, toIntArray, toLongArray, toShortArray
-
Methods inherited from class org.cakelab.blender.nio.CFacade
__io__addressof, __io__addressof, __io__equals, __io__generic__copy, __io__instanceof, __io__native__copy, __io__newInstance, __io__same__encoding, __io__sizeof, __io__sizeof, __io__subclassof, hashCode
-
-
-
-
Field Detail
-
targetTypeList
protected java.lang.Class<?>[] targetTypeList
-
dimensions
protected int[] dimensions
This list contains the length of each dimension of the array.
-
componentSize
protected long componentSize
Component size is the size in bytes of one element of this array. This considers, that an element can be an array as well and accounts the length of that (those) array(s). Thus, elementSize is exactly the size of one step from one element to the next.
-
-
Constructor Detail
-
CArrayFacade
public CArrayFacade(CArrayFacade<T> other)
Copy constructor.- Parameters:
other
-
-
CArrayFacade
public CArrayFacade(long baseAddress, java.lang.Class<?>[] targetTypeList, int[] dimensions, Block block, BlockTable __blockTable)
This is the constructor to attach an array facade to existing data in a block of a blender file.To allocate a block for an entirely new array, refer to the block allocation methods in either
BlenderFactoryBase
or the derived class BlenderFactory in the generated code.- Parameters:
baseAddress
- virtual start address of the array (file specific).targetTypeList
- Type specification of the component type (see class documentation).dimensions
- Length of each dimension (see class documentation)__blockTable
- Block table of the associated blender file.
-
-
Method Detail
-
length
public int length()
- Returns:
- Length of the array (number of elements).
-
sizeof
public long sizeof()
Delivers the native size of this array considering its architecture specific encoding.- Returns:
- size of this array in bytes
-
get
public T get(int index) throws java.io.IOException
Returns the element with the given 'index'.- Parameters:
index
-- Returns:
- array[index]
- Throws:
java.io.IOException
-
set
public void set(int index, T value) throws java.io.IOException
Set the value of the array element with given 'index'. I.e.array[index] = value;
- Parameters:
index
- index of the array element.value
- New value for that element.- Throws:
java.io.IOException
-
toArray
public T[] toArray() throws java.io.IOException
Converts the underlying data into a Java array with component type T.- Throws:
java.io.IOException
-
fromArray
public void fromArray(T[] data) throws java.io.IOException
Copyies all elements of the given array to this array.- Throws:
java.io.IOException
-
asString
public java.lang.String asString() throws java.io.IOException
Converts the array into a string. Warning: This method assumes, that the string is null terminated.- Throws:
java.io.IOException
-
fromString
public void fromString(java.lang.String str) throws java.io.IOException
Fills the underlying buffer with a null-terminated string from the given string using the default charset (seeCharset.defaultCharset()
).- Parameters:
str
- string to write into the array.- Throws:
java.io.IOException
-
fromString
public void fromString(java.lang.String str, boolean addNullTermination) throws java.io.IOException
Fills the underlying buffer with the bytes of the given string str using the default charset (seeCharset.defaultCharset()
). The parameter addNullTermination controls, whether the method adds a 0 to terminate the string or not.- Parameters:
str
- string to write into the array.addNullTermination
- Adds a '\0' if true.- Throws:
java.io.IOException
-
fromString
public void fromString(java.lang.String str, java.nio.charset.Charset charset, boolean addNullTermination) throws java.io.IOException
Fills the underlying buffer with the bytes of the given string str using the given charset (seeCharset
). The parameter addNullTermination controls, whether the method adds a 0 to terminate the string or not.- Parameters:
str
- string to write into the array.charset
- Charset to use when converting into a byte array.addNullTermination
- Adds a '\0' if true.- Throws:
java.io.IOException
-
toByteArray
public byte[] toByteArray() throws java.io.IOException
Converts the underlying data into an array of the given native type. The created array has the same length as this array.- Returns:
- New Java array with a copy of the elements of this array.
- Throws:
java.io.IOException
-
fromByteArray
public void fromByteArray(byte[] data) throws java.io.IOException
Copies all values of the given Java array to this array.Preconditions
- Source array 'data' and this array must have equivalent component types.
Equivalent types means, that the component type of the CArrayFacade has the corresponding class type of the native component type of the array 'data'. So, if 'data' is of type short[] than this array must have component type Short.- Parameters:
data
- Array of data to be copied to this array.- Throws:
java.io.IOException
-
toShortArray
public short[] toShortArray() throws java.io.IOException
Converts the underlying data into an array of the given native type. The created array has the same length as this array.- Returns:
- New Java array with a copy of the elements of this array.
- Throws:
java.io.IOException
-
toIntArray
public int[] toIntArray() throws java.io.IOException
Converts the underlying data into an array of the given native type. The created array has the same length as this array.- Returns:
- New Java array with a copy of the elements of this array.
- Throws:
java.io.IOException
-
toLongArray
public long[] toLongArray() throws java.io.IOException
Converts the underlying data into an array of the given native type. The created array has the same length as this array.- Returns:
- New Java array with a copy of the elements of this array.
- Throws:
java.io.IOException
-
toInt64Array
public long[] toInt64Array() throws java.io.IOException
Converts the underlying data into an array of the given native type. The created array has the same length as this array.- Returns:
- New Java array with a copy of the elements of this array.
- Throws:
java.io.IOException
-
toFloatArray
public float[] toFloatArray() throws java.io.IOException
Converts the underlying data into an array of the given native type. The created array has the same length as this array.- Returns:
- New Java array with a copy of the elements of this array.
- Throws:
java.io.IOException
-
toDoubleArray
public double[] toDoubleArray() throws java.io.IOException
Converts the underlying data into an array of the given native type. The created array has the same length as this array.- Returns:
- New Java array with a copy of the elements of this array.
- Throws:
java.io.IOException
-
__io__sizeof
public static long __io__sizeof(java.lang.Class<?> elementaryType, int[] dimensions, Encoding encoding)
Calculates the total size of an array based on the given parameters. Considers multi-dimensional arrays.- Parameters:
elementaryType
- The elementary type, i.e. the scalar type.dimensions
-encoding
-
-
__io__generic__copy
protected void __io__generic__copy(CFacade sourceArray) throws java.io.IOException
This method does a highlevel copy of the given source to this object.The method is used in case a lowlevel copy (see
CFacade.__io__native__copy(Block, long, CFacade)
) is not possible due to different encodings of the underlying blocks (seeCFacade.__io__same__encoding(CFacade, CFacade)
.Mandatory Preconditions
- This object and the source object are of exactly the same type.
- The source is not a CPointer.
The method is overridden by CArrayFacade.
This is for arrays only. Behaviour is unspecified if the given parameter source is not an array!- Overrides:
__io__generic__copy
in classCFacade
- Parameters:
sourceArray
-- Throws:
java.io.IOException
-
-