Byref (Variables)

Declares a reference

Syntax
      (Dim | Static) [Shared] ByRef name1 As DataType = variable1 [, ByRef 
      name2 As DataType = variable2, ...]
   or
      (Dim | Static) [Shared] ByRef As DataType name1 = variable1 [, name2 
      = variable2, ...]
   or
      [Static] Var [Shared] ByRef name1 = variable1 [, ByRef name2 = 
      variable2, ...]

Parameters
   name
      reference name
   variable
      variable name to refer

Description
   Declares a reference (by name) to a variable.

   A reference is an entity that is a way to access data located in memory. 
   A reference is not the data itself but only information about its 
   location. A reference can be thought of as a pointer that is implicitly 
   dereferenced. In many cases, it can be used as an alternative to 
   pointer.

   A reference must always be initialized with a variable when it is 
   created.
   DataType must be the same type as that of the variable, or a compatible 
   type (for example one from the types of its Bases in case of 
   inheritance):
      * Only when the two types are identical (or using the third syntax 
        with Var), a reference can be considered as an alias of the 
        variable. One can do the same operations through such a reference 
        as one can do with the original variable.
      * Otherwise (types compatible but not identical), one cannot do all 
        same operations than with the original variable:
            For example, a base type reference referring to a derived type 
            object allows to activate polymorphism when a virtual method is 
            called on it, similarly to a base type pointer referring to a 
            derived type object. One can do the same operations through 
            such a reference as one can do with a dereferenced pointer of 
            same type (but for both not the same operations as using 
            directly the derived type instance).

   A reference can be reassigned to refer to another variable (of 
   compatible type) by doing:
      @refname = @othervariable

   NOTE: The arrays of references and the non-static reference fields for 
   UDT are not supported yet.

Example
   '' Comparison between:
   ''   - a copy ('ci') of a variable ('i')
   ''   - a reference ('ri') to a variable ('i')

   Dim As Integer i = 12
   Print @i, i

   Dim As Integer ci = i  '' or Var ci = i
   Print @ci, ci

   Dim ByRef As Integer ri = i  '' or Var Byref ri = i
   Print @ri, ri

   Print

   Print i, ci, ri
   i = 34
   Print i, ci, ri
   ci = 56
   Print i, ci, ri
   ri = 78
   Print i, ci, ri

   Sleep
      

   '' Use reference allows to simplify expressions compared to pointer
   '' (avoid to use operator '@' and especially '*')

   Function fp () As ZString Ptr
      Static As ZString * 256 z
      Return @z
   End Function

   Dim As ZString Ptr pz = fp()
   *pz = "FreeBASIC Zstring Ptr"
   Print *pz
   *pz &= " 1.3.0"
   Print *pz

   Print

   Function fr () ByRef As ZString
      Static As ZString * 256 z
      Return z
   End Function

   Dim ByRef As ZString rz = fr()  '' or Var Byref rz = fr()
   rz = "FreeBASIC Zstring Ref"
   Print rz
   rz &= " 1.4.0"
   Print rz

   Sleep
      

   '' It is possible to reassign a reference.
   '' An example with an UDT to control the successive constructions & destructions of objects handled with one only reference.

   Type UDT
     Declare Constructor ()
     Declare Destructor ()
     Dim As Integer I
   End Type

   Constructor UDT ()
     Static As Integer nb
     nb += 1
     This.I = nb
     Print "UDT.Constructor()"
   End Constructor

   Destructor UDT ()
     Print "UDT.Destructor()"
   End Destructor

   Var ByRef ru = *New UDT  '' or Dim Byref As UDT ru = *New UDT
   Print ru.I
   Delete @ru

   Print

   @ru = New UDT
   Print ru.I
   Delete @ru

   Sleep
      

   '' Polymorphism (by using inheritance and virtuality) can be activated through any of the 3 following kinds of entities:
   ''   - base-type pointers referring to derived-type objects,
   ''   - dereferenced base-type pointers referring to derived-type objects,
   ''   - base-type references referring to derived-type objects.
   '
   '' If in the first line of the below code, FALSE is put instead TRUE, the polymorphism by virtuality is no more activated.

   #define virtuality True

   Type myBase Extends Object
     #if virtuality = True
      Declare Virtual Sub hello()
     #else
      Declare Sub Hello()
     #endif
   End Type

   Sub myBase.hello()
     Print "myBase.hello()"
   End Sub

   Type myDerived Extends myBase
     Declare Sub hello()
   End Type

   Sub myDerived.hello()
     Print "myDerived.hello()"
   End Sub

   Dim As myBase mb
   Dim As myBase Ptr pmb = @mb
   Dim ByRef As myBase rmb = mb  '' or Var Byref rmb = mb
   pmb->hello()    '' pmb is a base-type pointer referring to a base-type object
   (*pmb).hello()  '' *pmb is a dereferenced base-type pointer referring to a base-type object
   rmb.hello()     '' rmb is a base-type reference referring to a base-type object

   Print

   Dim As myDerived md
   Dim As myBase Ptr pmd = @md
   Dim ByRef As myBase rmd = md  '' only syntax because the reference data-type must be different from the one of object
   pmd->hello()    '' pmd is a base-type pointer referring to a derived-type object
   (*pmd).hello()  '' *pmd is a dereferenced base-type pointer referring to a derived-type object
   rmd.hello()     '' rmd is a base-type reference referring to a derived-type object

   Sleep
      

Version
   * Since fbc 1.04.0

Dialect Differences
   * Only supported in -lang fb, -lang fblite and -lang deprecated 
     dialects.

Differences from QB
   * New to FreeBASIC.

See also
   * Dim
   * Static
   * Var
   * Shared
   * Byref (Parameters)
   * Byref (Function Results)

