Dynamic Arrays

Hello, this page explains the proper use of dynamic arrays in FreeBASIC. 
While it isn't a very long tutorial, many people have had some troubles 
with this and I felt it was worth putting into the "Getting Started" 
tutorial page.

Arrays are neat; they can be used and resized throughout a program, with 
little difficulties. Firstly, we should discuss both ways a dynamic array 
can be created. In the same code, I will explain how to redimension a 
Dynamic Shared Array within a sub or function. Read the comments within the 
code to understand it better.

   Declare Sub mySub ()

   ' as of 0.17, OPTION DYNAMIC and '$DYNAMIC are unecessary. you must define an array to be dynamic each time
   ' as you can see, both following ways are successful at creating a dynamic array
   Dim Shared myArray1() As UByte
   ReDim Shared myArray2(0) As UByte

   mySub

   ' because we shared the arrays, they are accessable from anywhere within the module
   Print myArray1(5) ' will print 2
   Print myArray2(6) ' will print 3

   Sub mySub ()
      ' do NOT use "redim shared" within a sub or function! even if it is shared, you must omit the word "shared" for it to work
      ReDim myArray1(0 To 9) As UByte
      ReDim myArray2(0 To 9) As UByte
      myArray1(5) = 2
      myArray2(6) = 3
   End Sub

Now, you may be wondering how you can redimension an array while using the 
PRESERVE keyword. Normally, you simply add PRESERVE as the syntax for REDIM 
will state. Yet in fact, this only works if the first array dimension is 
the only one changing! For example, the following program would not work 
properly:

   ' declare the dynamic array the cleaner way
   ReDim Shared myArray(0 To 9, 0 To 9) As UByte
   Dim As UByte x, y, i

   ' fill the array with values
   For y = 0 To 9
      For x = 0 To 9
         i += 1
         myArray(x, y) = i
      Next x
   Next y

   ' proves the values are good originally:
   For y = 0 To 9
      For x = 0 To 9
         Print Using "##,"; myArray(x, y);
      Next x
      Print
   Next y
   Print
   Print "Press a key..."
   Sleep
   Cls

   ' redimension the arrays
   ReDim Preserve myArray(0 To 18, 0 To 12) As UByte

   ' the values have not been preserved properly!
   For y = 0 To 9
      For x = 0 To 9
         Print Using "##,"; myArray(x, y);
      Next x
      Print
   Next y

   Sleep
   End

Try it out! You can see that it does not work properly. This is because 
only the first dimension in an array may change sizes, while the rest 
remain the same size, in order for PRESERVE to work properly.

There is a workaround, which I will post later, after I edit it in order to 
make sense to any program, not just mine, and make some revisions so it 
does not go out of bounds. For the moment, get creative ;)

Last Reviewed by Sancho3 on February 06, 2018