{{fbdoc item="title" value="Variable-length Arrays"}}----
Resizable homogeneous data structures. Also known as "dynamic arrays".

{{fbdoc item="section" value="Overview"}}
	Variable-length arrays are [[ProPgArrays|arrays]] that can, during program execution, either be resized to hold more or less elements, or have their dimension[s] use a different subscript range. The memory used by a variable-length array to store its elements is allocated at runtime in the heap, as opposed to fixed-length arrays whose data is either allocated on the program stack or in the ##.BSS## or ##.DATA## sections of the executable, depending on whether they were defined with ##[[KeyPgStatic|Static]]## (or ##[[KeyPgShared|Shared]]##).
	
	Variable-length arrays may also be used as data members inside [[ProPgUDTs|user-defined types]]. As opposed to fixed-length arrays though, the array is not allocated as part of the user-defined type structure, because user-defined types cannot be variable-length. Instead, the user-defined type only contains the array descriptor that is used to hold and access the variable-length array behind the scenes, and the array is still allocated on the heap, as with variable-length array variables.
	
	Variable-length arrays are often called "dynamic arrays" because their size can change dynamically at runtime, instead of being fixed-size.

{{fbdoc item="section" value="Declaration"}}
	A variable-length array is declared with either the ##[[KeyPgDim|Dim]]## or ##[[KeyPgRedim|Redim]]## keywords, followed by a variable identifier, a parenthesized list of boundaries and an element [[CatPgStdDataTypes|data type]]. For an array to be declared variable-length, it must be declared with unknown boundaries, or with variable (non-constant) boundaries. ##[[KeyPgRedim|Redim]]## always defines variable-length arrays, whether the specified boundaries are constant or not.

{{fbdoc item="filename" value="examples/manual/proguide/arrays/varlen_decl.bas"}}%%(freebasic)
'' Declares a one-dimensional variable-length array of integers, with initially 2 elements (0 and 1)
redim a(0 to 1) as integer

'' Declares a 1-dimensional variable-length array without initial bounds.
'' It must be resized using Redim before it can be used for the first time.
dim b(any) as integer

'' Same, but 2-dimensional
dim c(any, any) as integer

dim myLowerBound as integer = -5
dim myUpperBound as integer = 10

'' Declares a 1-dimensional variable-length array by specifying variable (non-constant) boundaries.
'' The array will have myUpperBound - myLowerBound + 1 elements.
dim d(myLowerBound to myUpperBound) as integer

'' Declares a variable-length array whose amount of dimensions will be determined
'' by the first Redim or array access found. The array has no initial bounds and must
'' be resized using Redim before it can be used for the first time.
dim e() as integer
%%

{{fbdoc item="section" value="Resizing"}}
	Resizing a variable-length array refers to "redefining" the array with different boundaries, allowing the array to grow or shrink. Elements outside the new subscript range[s] are erased; object elements will be destroyed. If the array is resized to a larger size, new elements are added initialized with a zero or //null// value; object elements are default-constructed. Variable-length arrays are resized using the ##[[KeyPgRedim|Redim]]## keyword following the same form as definition. In this case the element data type may be omitted from the ##[[KeyPgRedim|Redim]]## statement.

{{fbdoc item="filename" value="examples/manual/proguide/arrays/varlen_redim.bas"}}%%(freebasic)
'' Define an empty 1-dimensional variable-length array of SINGLE elements...
dim array(any) as single

'' Resize the array to hold 10 SINGLE elements...
redim array(0 to 9) as single

'' The data type may be omitted when resizing:
redim array(10 to 19)
%%
	
	Resizing an array cannot change its amount of dimensions, but only the boundaries of each dimension.
	
	By default, element values of a variable-length array are lost when resized. To retain the previous element values during a resize, use the ##[[KeyPgPreserve|Preserve]]## keyword.

{{fbdoc item="see"}}
	- [[ProPgFixLenArrays|Fixed-length Arrays]]
	- [[ProPgPassingArguments|Passing Arguments to Procedures]]
	- [[ProPgPassingArrays|Passing Arrays to Procedures]]
	- [[KeyPgDots|... (Ellipsis)]]

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