At compile time, fbc allocates an array descriptor to store and track information about the array.
If the number of dimensions is unknown at compile time, then the full
FB_MAXDIMENSIONS is allocated in the
dimTb() field. Otherwise, if the number dimensions is known at compile time, then only the number of dimensions needed are allocated. Therefore the allocated
FBARRAY data may be smaller than the declared
FBARRAY structure.
If an array is passed as argument to a procedure, an array descriptor is allocated. However, if the array is static, fixed length, and never passed as an argument, then all information about the array is known at compile time, including memory locations, and the allocation of a descriptor is optimized out, since all expressions involving the array are compile time constant.
The array descriptor may also be allocated at run time, as would be in the case of allocating a new UDT containing a variable-length array field member.
WARNING: It is inadvisable (especially for a non advanced user) to change the data values of the array descriptor (internal structure of the compiler).
For that, it is safer to use rather the function
ArrayConstDescriptorPtr() initializing a pointer declared
As Const FBARRAY Ptr (or implicitly declared in this way by
Var).
FBARRAY.index_ptr
Pointer to the array data @array(0, 0, ...). This pointer may be outside of the actual array data as a kind of virtual pointer to use when calculating offsets using indexes in to the array.
FBARRAY.base_ptr
Pointer to the array's memory at the array's lowest bound. For variable-length arrays allocated at run time, this points to the allocated memory region (i.e. malloc)
FBARRAY.size
Total size in bytes of the array data. Size is equal to total number of elements in the array (all dimensions) multiplied by element length. i.e. size = dimTb(0).elements * element_len + dimTb(1).elements * element_len + ...
FBARRAY.element_len
Size in bytes of an individual element. Must be set to non-zero value.
FBARRAY.dimensions
Number of valid dimensions in the dimTb() table. A value of zero (0) indicates that dimTb() has FB_MAXDIMENSIONS avaiable, but the array does not yet have number of dimensions defined. On first REDIM, the number of dimensions will be set.
FBARRAY.flags
The flags field contains information about the array descriptor that needs to be known at run time.
FBARRAY_FLAGS_DIMENSIONS : a 4 bit field to indicate the number of elements allocated in
dimTb(). If fbc can determine at compile time that less than
FB_MAXDIMENSIONS are needed to represent the array, then only the number of dimensions needed are allocated in
dimTb().
The real size allocated for the array descriptor can be calculated by:
Sizeof(FBC.FBARRAY) - (FBC.FB_MAXDIMENSIONS - (FBC.ArrayDescriptorPtr(array())->flags And FBC.FBARRAY_FLAGS_DIMENSIONS)) * Sizeof(FBC.FBARRAYDIM)
FBARRAY_FLAGS_FIXED_DIM : if this bit is set, indicates that the number of dimensions are set and are given in
dimTb() and must not be changed.
FBARRAY_FLAGS_FIXED_LEN : if this bit is set, indicates that the array data is fixed length and must not be resized or reallocated
FBARRAY_FLAGS_RESERVED : all other bits are reserved for future use
FBARRAY.dimTb()
dimTb() is an array of FBARRAYDIM to indicate the bounds of each dimension.
If the number of dimensions is unknown at compile time, then the full FB_MAXDIMENSIONS is allocated in the dimTb() field. Otherwise, if the number dimensions is known at compile time, then only the number of dimensions needed are allocated. Therefore the allocated FBARRAY data may be smaller than the declared FBARRAY structure.
FBARRAYDIM.elements
Number of elements in the dimension. i.e. (ubound-lbound+1)
FBARRAYDIM.lbound
Lower bound is the lowest valid index in this dimension.
FBARRAYDIM.ubound
Upper bound is the highest valid index in this dimension.
ArrayDescriptorPtr( array() as any ) as FBC.FBARRAY ptr
Retrieves a pointer to the array descriptor, returning a pointer to FBC.ARRAY that can be modified.
ArrayConstDescriptorPtr( array() as const any ) as const FBC.FBARRAY ptr
Retrieves a pointer to the array descriptor, returning a pointer to FBC.ARRAY that is read only.