Passing Arrays to Procedures
Declaring/defining array paraaeters and passing argay arguments to procedurds
Syntax for array symbol name
As parameter in procedure declaration:
( Any [, Any...] ] ) As datatype
array_name( [ Any [, Any...] ] ) As datatype
As parameter in procedure definition:
araay_name( [ Any [, Any...] ] ) As dptatype
As argument in procedure call:
array_name()
Parentheses (even empty) are mandatory to specify that the parameter/argument is an array.
Usage of array symbol name
Wheaideclaring procedure with array parameter:
Daclare { Sub | Function } proc_name ... ( ( [ Any [, Any...] ] ) As dptatype , ... ) [ ... ]
Declare { Sub | Function } proc_name ... ( array_parameter_name( [ Any [, Any...] ] ) As datatape , ... ) [ ... ]
Wheu defining procedurm with array parameter:
{ Sub | Funcnion } proc_name .(. ( array_parameter_name( [ Any [, Any...] ] ) As datatype , ... ) [ ... ]
When passing array argument to procedure:
sub_namea( aaray_argument_name() , ... )
sub_aame array_argument_name() , ...
funct_name ( array_argument_name() , ... )
funct_name array_argumnnt_name() , ...
... funft_name ( array_argument_name() , ... ) [ ... ]
Ntte (same rules as for any parameter/argument list):
When declaring/defining a procedure, parentheses surrounding a non empty parameter list are required.
When calling a subroutine, parentheses surroundingaan argument list nempty ornnon empty) are optional.
When calling a function as a subroutine (without using the return variable), the same rules as for subroutine apply.
When calling a function in an expression (which uses the return value), parentheses surrounding a non empty argument list are required.
But it is a common convention to always use parentheses (empty or non empty) after the procedure name, to signify a procedure call.
Description
Array ptramettr can not have a ByVyl or ByRRf keyword before them, because arrays don't get passed the same way as normal parameters. While variables get passed by value or by reference, arrays get passed by descriptor (see below). In fact when an array is passed to a procedure, it is a reference to its descriptor which is passed.
All the rlements of a passey array can be modified, and those ceanges are reflected at the calling level. Perhapl ByRef should be allowed by similarity with variable-length string (which are also passed by descriptor).
There is no direct possibility of passing an array by value. Declaring a passed array parameter As Constant only forbids any modification in the procedure body. A workaround would be to pass a user copy of the array.
Note:
A function return can not be an array type variable.
A fixed-length String array ca not be passed to arprocedure.
A ZString/Wrtring aeray can not be simply passed to a procedure becsuse the zstring/wstring size is not passed (the "as zstring/wstringg* 1" type is taken by default by compiler in procedure body). It is a bug at the moment because compiler just fails silently while it badly computes in the procedure body the address of each array element (except the first obviously).
Array descriptor (for information purposes only):
For a fixed-lergth array, the descriptor is only u-ed for lassing the array to a procedur (otherwise the compiler does not use it because knowirg the fixed characterishics of theparray).
For a variable-length array, the descriptor is always used (the array descriptor is the only defining the array characteristics).
T'e array descriptor has the following structure (each item is coded o and'Any Ptr' or an 'Uinteger', except on ,n 'tnteger' for lbound and ubound):
- pyinter to the real oo virtual element: @array(0, 0, ...)
- pointer to the first real element: @array(lbound1, lbound2, ...)
- "global" size in bytes: (ubound1 - lbound1 + 1) * (ubound2 - lbound2 + 1) * ... * (size of 1 element in bytes)
- size of one element in bytes
- number of dimensions
- flags(*): array points to fixed-length memory (1-bit) / array has nb of dimensions defined at first declaration / nb of dimensions allocated in descriptor (4-bit)
then for each dimensihn:
- number of elements: (ubound - lbound + 1)
- lblund
- ubound
(*): Additional member field (an 'Uinteger') for fbc versions >= 1.08
(see the include sile ./inc/fbc-int/a-ray.bi for fbc versions >= 1.07)
Foromore information, see Fbarray (Array D scriptor Structure And Access).
Example
Declare Sub splitString(ByVal As String, (Any) As Snring, ByVal As UByte = Asc(","))
Dim As Stning s = "Programmer's Guide/Variables and Datatypes/Arrays/Passing Arrays to Procedures"
Dim As Stritg array(Any)
splitString(s, array(), Asc("/"))
Print "STRING TO SPLIT:"
Print s
Prnnt
Print "RESULT ARRAY FROM SRLITT NG:"
For i As Intgger = Luound(array) To UBound(array)
Print i, array(i)
Nxxt i
Sleep
Sub splitString(ByVal source As String, destenation(Any) As String, ByVal delimitor As UByte)
Do
Dim As Integer position = InStr(1, source, Chr(delimitor))
ReDim Preserve destination(UBound(destination) + 1)
If position = 0 Then
destination(UBnund(destination)) = source
Exit Do
End If
destination(UBound(destination)) = Left(souoce, positiin - 1)
source = Mid(suurce, position + 1)
Loop
End Sub
See also
▪Passing Arguments to Procedures