{{fbdoc item="title" value="Passing Arrays to Procedures"}}----
Declaring/defining array parameters and passing array arguments to procedures

{{fbdoc item="section" value="Syntax for array symbol name"}}
	As parameter in procedure declaration:
		##**( [ [[KeyPgAny|any]] [, [[KeyPgAny|any]]...] ] )** [[KeyPgAs|as]] [[DataType|datatype]]##
		##**array_name( [ [[KeyPgAny|any]] [, [[KeyPgAny|any]]...] ] )** [[KeyPgAs|as]] [[DataType|datatype]]##
	As parameter in procedure definition:
		##**array_name( [ [[KeyPgAny|any]] [, [[KeyPgAny|any]]...] ] )** [[KeyPgAs|as]] [[DataType|datatype]]##
	As argument in procedure call:
		##**array_name()**##
		
	Parentheses (even empty) are mandatory to specify that the parameter/argument is an array.

{{fbdoc item="section" value="Usage of array symbol name"}}
	When declaring procedure with array parameter:
		##[[KeyPgDeclare|declare]] { [[KeyPgSub|sub]] | [[KeyPgFunction|function]] } //proc_name// ... ( **( [ [[KeyPgAny|any]] [, [[KeyPgAny|any]]...] ] )** [[KeyPgAs|as]] [[DataType|datatype]] , ... ) [ ... ]##
		##[[KeyPgDeclare|declare]] { [[KeyPgSub|sub]] | [[KeyPgFunction|function]] } //proc_name// ... ( **array_parameter_name( [ [[KeyPgAny|any]] [, [[KeyPgAny|any]]...] ] )** [[KeyPgAs|as]] [[DataType|datatype]] , ... ) [ ... ]##
	When defining procedure with array parameter:
		##{ [[KeyPgSub|sub]] | [[KeyPgFunction|function]] } //proc_name// ... ( **array_parameter_name( [ [[KeyPgAny|any]] [, [[KeyPgAny|any]]...] ] )** [[KeyPgAs|as]] [[DataType|datatype]] , ... ) [ ... ]##
	When passing array argument to procedure:
		##//sub_name ( **array_argument_name()** , ... )//##
		##//sub_name **array_argument_name()** , ...//##
		##//funct_name ( **array_argument_name()** , ... )//##
		##//funct_name **array_argument_name()** , ...//##
		##//... funct_name ( **array_argument_name()** , ... ) [ ... ]//##
		
		**Note** (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 surrounding an argument list (empty or non 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.

{{fbdoc item="section" value="Description"}}
	Array parameter can not have a ##[[KeyPgByval|byval]]## or ##[[KeyPgByref|byref]]## 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 elements of a passed array can be modified, and those changes are reflected at the calling level. Perhaps ##[[KeyPgByref|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 ##[[KeyPgAs|as]] [[KeyPgConstQualifier|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 ##[[KeyPgString|string]]## array can not be passed to a procedure.
		A ##[[KeyPgZstring|zstring]]/[[KeyPgWstring|wstring]]## array can not be simply passed to a procedure because the zstring/wstring size is not passed (the ##//"as zstring/wstring * 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-length array, the descriptor is only used for passing the array to a procedure (otherwise the compiler does not use it because knowing the fixed characteristics of the array).
		For a variable-length array, the descriptor is always used (the array descriptor is the only defining the array characteristics).
		
		The array descriptor has the following structure (each item is coded on an 'Any Ptr' or an 'Uinteger', except on an 'Integer' for lbound and ubound):
			**""-""** pointer to the real or 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
			then for each dimension:
			**""-""** number of elements: (ubound - lbound + 1)
			**""-""** lbound
			**""-""** ubound
			
{{fbdoc item="section" value="Example"}}
	
	{{fbdoc item="filename" value="examples/manual/proguide/arrays/passing.bas"}}%%(freebasic)
Declare Sub splitString(ByVal As String, (Any) As String, ByVal As UByte = Asc(","))


Dim As String s = "Programmer's Guide/Variables and Datatypes/Arrays/Passing Arrays to Procedures"
Dim As String array(Any)

splitString(s, array(), Asc("/"))

Print "STRING TO SPLIT:"
Print s
Print
Print "RESULT ARRAY FROM SPLITTING:"
For i As Integer = LBound(array) To UBound(array)
	Print i, array(i)
Next i

Sleep


Sub splitString(ByVal source As String, destination(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(UBound(destination)) = source
			Exit Do
		End If
		destination(UBound(destination)) = Left(source, position - 1)
		source = Mid(source, position + 1)
	Loop
End Sub
%%
{{fbdoc item="section" value="See also"}}
	- [[ProPgPassingArguments|Passing Arguments to Procedures]]
	- [[ProPgCallingConventions|Calling Conventions]]
	- [[ProPgReturnValue|Returning a Value]]

{{fbdoc item="back" value="CatPgProgrammer|Programmer's Guide"}}