{{fbdoc item="title" value="Arrays"}}----
Multi-dimensional container types.

{{fbdoc item="section" value="Overview"}}
	//Arrays// are special kinds of [[ProPgVariables variables]] which act as containers for a number of values, or //elements//. An array can store elements of any type, and all of its elements share the same type. For example, an array can store ##[[KeyPgInteger Integer]]## elements or ##[[KeyPgSingle Single]]## elements, but not both. These elements are accessed--read from or written to--through an ##[[KeyPgInteger Integer]]## value representing their //position// in the array. Arrays have lengths, or //sizes//, which are equal to the number of elements they are storing at any given time. //Fixed-length// arrays have constant sizes throughout their lifetimes, while the sizes of //variable-length// arrays can change dynamically.

{{fbdoc item="section" value="Elements and positions"}}
	The values that an array stores are its elements. Each element of an array has a corresponding position, which is an ##[[KeyPgInteger Integer]]## value ranging from the array's //lower bound// to its //upper bound//, inclusive. These positions are used to access individual elements in the array using ##[[KeyPgOpArrayIndex operator ()]]##, which takes a position and returns a reference to the element at that position. A valid position in an array is greater than or equal to its lower bound, and less than or equal to its upper bound.

{{fbdoc item="filename" value="examples/manual/proguide/arrays/array1.bas"}}%%(freebasic)
' Create an array of 3 elements all having the value zero (0.0f).
dim array(1 to 3) as single

' Assign a value to the first element.
array(1) = 1.2

' Output the values of all the elements ("1.2 0 0").
for position as integer = 1 to 3
	print array(position)
next
%%

{{fbdoc item="section" value="Sizes and bounds"}}
	The size of an array is equal to the number of elements it stores at any given time. An array can have a size of zero (0), meaning it's not storing any values at the moment--it's //empty//. If an array's size is greater than zero, that many elements are being stored. An array's size is equal to one more than the difference between its upper and lower bounds, or ##[[KeyPgUbound ubound]](//array//) - [[KeyPgLbound lbound]](//array//) + 1##.

	The lower and upper bounds not only determine the size of an array, but also the valid positions of individual elements. For example, an array with lower and upper bounds of zero (0) and four (4) stores five (5) elements, the first element being at position 0, the last at position 5. These bounds may be specified when the array is declared, or, for some arrays, changed by resizing the array. An array's lower and upper bounds can be retrieved using ##[[KeyPgLbound Lbound]]## and ##[[KeyPgUbound Ubound]]##, respectively.

	When creating or resizing an array, if a lower bound is not specified it defaults to zero (0).

{{fbdoc item="filename" value="examples/manual/proguide/arrays/array2.bas"}}%%(freebasic)
' Declares and initializes an array of four integer elements.
dim array(3) as integer = { 10, 20, 30, 40 }

' Outputs all of the element values (" 10 20 30 40").
for position as integer = lbound(array) to ubound(array)
	print array(position) ;
next
%%

{{fbdoc item="section" value="Fixed-length and variable-length"}}
	There are two fundamental kinds of arrays: //[[ProPgFixLenArrays fixed-length]]// and //[[ProPgVarLenArrays variable-length]]//. The primary difference between the two is that the bounds of fixed-length arrays can never change, that is, they always store the same number of elements in the same positions. Variable-length array bounds can be changed, affecting the number of elements stored and/or the positions of the elements.

	Since fixed-length arrays never change size, the compiler chooses to make room for--or, //allocate//--the memory for the array elements either in static storage or on the program stack, depending on the array's [[ProPgStorageClasses storage class]]. This can be an advantage, since the cost of creating these kinds of arrays doesn't include any adverse run-time penalty. Fixed-length arrays are declared using ##[[KeyPgExtern Extern]]##, ##[[KeyPgStatic Static]]## and ##[[KeyPgDim Dim]]##. At least an upper bound must be specified, and all bounds must be compile-time constant values, such as numeric literals, ##[[KeyPgConst Const]]## variables or ##[[KeyPgEnum Enum]]## enumerators.

	Variable-length arrays can change in size, so the compiler chooses to allocate the memory for the array elements at run-time, in the free store. The advantage here of course is being able to dynamically resize the arrays, however, run-time performance could vary when they are created, resized or destroyed. Variable-length arrays are declared using ##[[KeyPgExtern Extern]]##, ##[[KeyPgStatic Static]]##, ##[[KeyPgDim Dim]]## and ##[[KeyPgRedim Redim]]##. When using ##[[KeyPgExtern Extern]]##, ##[[KeyPgStatic Static]]## or ##[[KeyPgDim Dim]]##, the lower and upper bounds can be left unspecified--resulting in an empty array--or either one must have a variable value, such as an ##[[KeyPgInteger Integer]]## variable or ##[[KeyPgFunction Function]]## result. ##[[KeyPgRedim Redim]]## can be used to resize an existing variable-length array, by giving it different lower and/or upper bounds.

{{fbdoc item="filename" value="examples/manual/proguide/arrays/array3.bas"}}%%(freebasic)
' Creates a fixed-length array that holds 5 single elements.
const totalSingles = 5
dim flarray(1 to totalSingles) as single

' Creates an empty variable-length array that holds integer values.
dim vlarray() as integer

' Resizes the array to 10 elements.
redim vlarray(1 to 10) as integer
%%

{{fbdoc item="section" value="Multi-dimensional arrays"}}
	The arrays discussed so far have been one-dimensional, that is, the elements are accessed through a single position. One-dimensional arrays can be thought of as a simple row of elements. Arrays can also have more than one dimension; an individual element of the array is accessed using two or more positions. Two-dimensional arrays use two positions--a row and a column position--to refer to individual elements, like a grid or table. Three-dimensional arrays use three positions--a row, column and perhaps depth position--to refer to individual elements, like a cube. Four-dimensional arrays can be thought of as one or more three-dimensional arrays, and so on. Multi-dimensional arrays are declared just like one-dimensional arrays, except that more than one lower and upper bound range is specified.

{{fbdoc item="filename" value="examples/manual/proguide/arrays/array4.bas"}}%%(freebasic)
' Take Care while initializing multi-dimensional array
Dim as integer multidim(1 to 2,1 to 5) = {{0,0,0,0,0},{0,0,0,0,0}}
%%

{{fbdoc item="see"}}
	- [[ProPgFixLenArrays Fixed-length Arrays]]
	- [[ProPgVarLenArrays Variable-length Arrays]]
	- [[ProPgVariableScope Variable Scope]]

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