GetFreeCell - Learn To Code - PlayBASIC Documentation

GetFreeCell

Index = GetFreeCell(SourceArray())

Parameters:

SourceArray() = The array you wish to query

Returns:

Index = The Index of this free cell

The GetFreeCell() function searches the passed arrays first dimension looking for a free cell. If no free cell can be found, the array is automatically expanded for you. This can very handy when managing lists of strings or types in an array.

FACTS:

      * GetFreeCell will always return cell indexes of 1 or greater. Index zero is unused.

      * While GetFreeCell works with multi dimensioned arrays, it only searches the first dimension .

      * GetFreeCell considers a free cell to be any cell that is yet to be assigned any data. See FreeCell to free cells.

      * GetFreeCell is for use with Type and String arrays, but can also be used upon Integer, Floating Point arrays.

Mini Tutorial:

This example creates a simple character manager using a typed array. When the type is no longer needed it's destroyed using the FreeCell command.

; Define a type to hold the values for our characters
  Type obj
     status,x,y,angle#,colour
  EndType

; Create the typed ships array to store our objects
  Dim Ships(0) As obj


; start of program main loop
  Do
   ; clear the screen to black
     Cls RGB(0,0,0)
     Print "Press Space To Add Object"


   ; run through out array of objects
     For item=0 To GetArrayElements(ships().obj,1)

      ; check if this object exists or not
        If Ships(item)

         ; move the object
           angle#=ships(item).angle#
           x#=CosNewValue(ships(item).x,angle#,2)
           y#=SinNewValue(ships(item).y,angle#,2)

         ; check if the obejct has left the screen
           If PointInBox(x#,y#,0,0,800,600)=false
            ; if it has, free this cell
              FreeCell Ships().obj,Item
              Continue
           EndIf

         ; object is on screen so draw it
           CircleC x#,y#,10,true,Ships(item).Colour

         ; write the objects new position
           ships(item).x=x#
           ships(item).y=y#

        EndIf
     Next

   ; check  if the Space key is pressed
     If SpaceKey()

      ;if it is, get a free cell within the array
        Item=GetFreeCell(Ships())

      ; assign it it's starting values
        Ships(Item).status=true
        ships(item).x=Rnd(800)
        ships(item).y=Rnd(600)
        ships(item).angle=Rnd(360)
        ships(item).colour=RndRGB()
        FlushKeys
     EndIf

   ; refresh the screen
     Sync

   ; loop back to the do statement to keep program running
  Loop


Related Info:	ClearArray \| ClearArrayCells \| CopyArrayCells \| FreeCell \| GetArrayElements \| Null :