Class 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 of CArrayFacade use its CPointer.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 to BlenderFile and BlockTable.

    Author:
    homac
    • 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 (see Charset.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 (see Charset.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 (see Charset). 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