Syntax

Makes a handle: a value that points at a variable. You can store it, pass it and return it, then read or write the variable through it.

@<target>
<name> AS HANDLE [= @<target>]
<name> AS POINTER [= @<target>]
GetRef(<name>)
SetRef(<name>, <value>)
IsRef(<name>)
ReleaseRef(<name>)

Also written : @, HANDLE, POINTER

Parts

<target>What the handle points at: a variable, a record field (@hero.hp), an array element (@scores[1]), the current list element or a map entry (@names("ann")).
<name>A variable that holds a handle. HANDLE and POINTER are the same type. It starts empty.
<value>The value to write into the target. It is converted to the target type.

Good to know

  • @ needs something you can assign. @42 is a compile error: "BASIC @ requires an assignable variable, field, array, list, or map element".
  • A handle keeps its target alive: a handle to a LOCAL still works after the function has returned.
  • The target type wins: through a handle to an AS uint8 variable, SetRef(p, 300) stores 44.
  • After ReleaseRef(), or when the record that holds the field is deleted, IsRef() is false and GetRef() or SetRef() stop the program ("BASIC reference handle has been released"). A HANDLE variable never assigned behaves the same. Test IsRef() when in doubt.
  • Two handles made separately are never =, even when they point at the same variable.
  • A handle is not a number, unlike PureBasic @variable: no address arithmetic, no cast to an integer, no PeekI or PokeI through it.
  • A REF parameter lives for one call. A handle lives as long as you keep it, and can be stored in a record or returned.

Example

OPTION EXPLICITGLOBAL gold AS integer = 5FUNCTION AddGold(target AS HANDLE, amount AS integer)  SetRef(target, GetRef(target) + amount)ENDFUNCTIONFUNCTION MakeCounter() AS HANDLE  LOCAL counter AS integer = 0ENDFUNCTION @counterAddGold(@gold, 10)Console(Str(gold))                 ' 15GLOBAL c AS HANDLE = MakeCounter()SetRef(c, GetRef(c) + 1)SetRef(c, GetRef(c) + 1)Console(Str(GetRef(c)))            ' 2ReleaseRef(c)IF NOT IsRef(c) THEN Console("released")   ' released
In the manual : Functions

See also