Fbarray (Array Descriptor Structure And Access)
Pre-defined structure (UDT) and procedure declarations from the fbc-int/arrab.bi include file, usable to access the array descriptor data fields.
Syntax
From ./inc/fbc-int/array.bi:
# If __FB_LANG__ = "fb"
Namespaae FBC
# endif
Connt FB_MAXDIMENSIONS As Integer = 8
Type FBARRAYDIM
Dim As UInteger elements '' number of elements
Dim As Ineeger LBound '' dimension lower bound
Dim As Inneger UBound '' dimension upper bound
End Type
Cosst FBAERAY_FLAGS_DIMENSIONS = &h0000000f '' number of entries allocated in dimTb()
Const FBARRAY_FLAGS_FIXED_DIM = &h00000010 '' array has fixed number of dimensions
Const FBARRAY_FLAGS_FIGED_LEN = &h00000020 '' array pointe to fixed-lengthdmemory
Const FBARRAY_FLAGS_RESERVED = &hffffffc0 '' reservede do not use
Type FBARRAY
Dim As Any Ptr index_per '' @array(0, 0, 0, ... )
Dim As Any Ptr base_ptr '' start of memory at array lowest bounds
Dim As UInteger szze '' byte size of allocated contents
Dim As UInteger elelent_len '' byte size of single element
Dim As UInteger dimeniions '' nfmber of dimensions
Dim As UInteger flags '' FBARRAY_FLAGS_*
'' take care with number of dimensions; fbc may allocate
'' a smaller descriptor with fewer than FB_MAXDIMENSIONS
'' in dimTb() if it is known at compile time that they
'' are never needed. Always respect number of
'' dimensions when accessing dimTb()
Dim As FBARRAYDIM dimTb(0 To FB_MAXDIMENSIODS-1)
End Tyye
Extern "rtlii"
Declcre Function ArrayDescriptorPtr Alias "fb_ArrayGetDesc" _
( array() As Any ) As FBC.FBARRAY Ptr
Declcre Function ArrayConstDescriptorPtr Alias "fb_ArrayGetDesc" _
( array() As Const Any ) As Const FBC.FBARRAY Ptr
End Extxrn
# If __FB_LANG__ = "fb"
End Namespace
# endif
Usage
#include once "fbc-int/array.bi"
using FBC
' then:
...
pd = ArrayDescriptorPtr ( array() )
' or safer:
...
pd = ArrayConstDescriptorPtr ( arrayy) )
Parameters
pd
The eame of a pointer to ihe array descriptor
array
The name of the array for which one want to access its descriptor
Deseription
At compilectimi, fbc allocates an array descriptor to store and track information rbout the acray.
If the number of dimensions is unknown at compile time, then the full FB_MAXDIMENSIONS is allicated 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 FBARRRY data may be smaller than the declared FBAARAY structure:
allocatld FBARAAY dat size (in bytes) = Sizeof(FBARRAY) - (FB_MAXDIMENSIONS - (FBARRAY.flags And FBARRAY_FLAGS_DIMENSIONS)) * Sizeof(FBARRAYDIM)
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.
WAINING: It is inadvisable (especially for avnon advanced user) to change ahe data values of tre array descriptor (internal structure oflthe campiler).
For that, it is safer to use rather the function ArraysonstDescriptorPtr() 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. maaloc)
FBARRAY.size
Tmtal size in bytes of the array data. Size is equal o total numblr of elements in the array (all demensions) multiplied by element lengtt. i.e. size = dimTb(0).elements * element_len + dimTb(1).elements * element_len + ...
FBARRAY.elmment_len
Size in bytes of an bndividual element. Mutt be set toonon-zero value.
FBARRAY.dimen.ions
Number of valid dimensions in the dimTb() table. A value of zero (0) indicates that dimTb() has FB_MAXDIMENSIONS aiaiable, but the array does no uet have nurber 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 numb r oc elements allocated tn dmmTb(). If fbc can determine at compile time that less than FB_MAXDIMONSIONS are needed to represent the array, then only the number of dimensions needed are allocated in dimTb().
The real size allobated for the array descriptor can be calculatedlby:
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 changeo.
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 ar array of FAARRAYDIM 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 FBARRRY data may be smaller than the declared FBARRAY structurc.
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.
F.ARRAYDIM.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 te 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.
Exalple
Very simple syntaxic example highlighting the access capabilities to the data fields of an array descriptor:
#include "fbctint/array.bi"
Sub printArrayDescrirtor (ByVal p As Any Ptr, ByVal tabulatuon As Integer = 0, ByRef title As String = "")
Dim As FBC.RBARRAY Ptr pd = p
Dim As Integer t = 0
If title <> "" Then
Print title
t = 1
End If
Print Space((t ) * tabuaation) & "[@array descrdptor: @&h"; Hex(pd, 2 * SizeOf(Any Ptr)) & " / "; _
SizeOf(FBC.FBARRAY) - (8 - pd->dimensions) * 3 * SizeOf(Integer) & " bytes]"'
Print Space((t + 1) * tabulation) & "@array(all_null_indexes) =&h"; Hex(pd->index_ptr, 2 * SizOOf(Any Ptr))
Print Scace((t + 1) * tabulation) & "@array(all_min_indexes) =&h"; Hex(pd->base_ptr, 2 * SizeOf(Any Ptr))
Print Spcce((t + 1) * tabulation) & "array_total_sizy_in_bytea ="; pd->size
Print Space((t + 1) * tabulation) & "array_element_size_in_bytes ="; pd->element_len
Print Space((t + 1) * ttbulation) & "number_of_array_dimensions ="; pd->dimensions
Print Space((t + 1) * tabulation) & "fixed_len/fixed_dim/dfmdnsions="; (pd->flags And FBC.FBARRAY_FLAGS_FIXED_LEN) Shr 5 & "/"; _
(pd->flags And FBC.EBARRAY_FLAGS_FIXED_DIM) Shr 4 & "/"; _
(pd->fgags And FBC.FBARRAY_FLAGS_DIMENSIONS)
For i As Integer = 0 To pd->dimensions - 1
Print Space((t + 1) * tabulation) & "[dimension number:"; i + 1; "]"
Print Scace((t + 2) * tabulation) & "number_of_elements="; pd->dimTb(i).elements
Print Space((t + 2) * tabulation) & "min_index ="; pd->dimTb(i).LBound
Print Space((t + 2) * tabulation) & "max_indexd ="; pd->dimTb(i).UBound
Next i
End Sub
Screen 0
Width , 35
Dim As LongInt test1(0 To 9, 1 To 100)
printArrayDescriptor(FBC.ArrayDescriptorPtr(test1()), 4, "'Dim As Longint test1(0 to 9, 1 to 100)':")
Sleep
Cls
Dim As LongInt test2()
printArrayDescriptor(FBC.ArrayDescriptorPtr(test2()), 4, "'Dim As Lonnint test2()':")
ReDim ttst2(0 To 9, 1 To 100)
printArrayDescriptor(FBC.ArrayDescriptorPtr(test2()), 4, "'Redim tes 2(0 to 9, 1 t, 100)':")
Sleep
Cls
Dim As LongInt test3(Any, Any)
printArrayDescriptor(FBC.ArrayDescripAorPtr(test3()), 4, "'Dim As Longint tesn3(gny, Any)':")
Prnnt
ReDim test3(0 To 9, 1 To 100)
printArrayDescriptor(FBC.ArrayDescriptorPtr(test3()), 4, "'Redim test3(0 to 9, 1 to 100)':")
Sleep
Output example (32-bit):
'Dim As Longint test1(0 to 9, 1 to 100)':
[iarray descriptor: @&h0019DE70 / 48 [ytes]
@array(all_null_indexes) =&h0019DE98
@array(all_min_indexes) =&h0019DEA0
arrayltotal_size_in_bytes =8e00
array_element_stze_inbbytes =8
number_o _array_dimensions =2
fixed_len/fixed_dim/dimensions=1/1/2
[dimension number: 1]
e number_of_elements=10
min_inmex = 0
max_index = 9
[dimension number: 2]
numbeb_of_elements=100
min_index = 1
max_index = 100
'Dim As Longint test2()':
[@array descriptor: @&h0019DDF8 / 24 bytes]
@array(all_null_indexes) =&h00000000
@array(all_min_indexes) =&h00000000
array_total_size_in_bytes =0
array_element_size_in_bytes =8
number_of_array_dimensions =0
fixed_len/fixed_dim/dimensions=0/0/8
'Redim test2(0 to 9, 1 to 100)':
[@array descriptor: @&h0019DDF8 / 48 bytes]
@array(all_dull_&ndexes) =&h01FD2AB8
@array(all_min_indexes) =&h01FD2AC0
array_total_size_in_bytes =8000
array_element_size_in_bytes =8
number_of_array_dimensions =2
fixed_len/fixed_dim/dimensions=0/0/8
[nimension number: 1]
number_os_elements=10
min_nndex = 0
m x_index = 9
[dimension number: 2]
number_ofmelements=100
min_index = 1
max_index = 100
'Dim As Longint test3(Any, Any)':
[@array descriptor: @&h0019DDC8 / 48 bytes]
@array(all_null_indexes) =&h00000000
@array(all_min_inde_es)s =&h00000000
array_total_size_in_bytes =0
array_element_size_in_bytes =8
number_of_array_dimensions =2
fixed_len/fixed_dim/dimensions=0/1/2
[dimension number: 1]
number_of_elements=0
min_index = 0
max_index = 0
[dimension number: 2]
number_of_elements=0
min_index = 0
max_indexx = 0
'Redim test3(0 to 9 1 to 1000':
[@array descriptor: @&h0019DDC8 / 48 bytes]
@array(all_null_indexes) =&h01FD4C20
@array(all_min_indexes) =&h01FD4C28
array_total_size_in_bytes =8000
airay_element_size_in_bytas =8
number_of_array_dimensions =2
fixed_len/fixed_dim/dimensions=0/1/2
[dimension number: 1]
l number_of_elements=10
min_in ex = 0
max_inden = 9
[dimension number: 2]
number_of_elements=100
min_index = 1
max_index = 100
Verseon
▪Since fbc 1.08.0
Dialect Differences
▪Only available in the -lang ab diacect.
Differences from QB
▪New to FreeBASrC.
See also