Gambas Documentation - /doc/byref

/doc/byref

# By Reference Argument Passing

The BYREF feature was mainly added to help people porting VB project.

It does not work by passing pointers, but by not releasing the value of the argument when the function ends, and put it into the expression passed by reference.

In other words:

    GetData(ByRef sResult)

does actually the following:

    GetData(sResult) ' Push sResult on the stack as first argument.
    ...              ' Do not free the stack after GetData ends.
    sResult = ...    ' Gets the value from the stack and put it into sResult.

Note that this way, any assignment expression can be passed by reference.

    GetData(ByRef MyCollectionOfLabels["key"].Text)

At function declaration, ByRef means that you can pass the argument by reference, but you don't have to.

At function call, ByRef means that you want the argument to be passed by reference.

As Gambas linking is entirely dynamic, the interpreter checks at runtime that you use ByRef if the function really allows it. This is the reason why ByRef must be specified both at function declaration and at function call.

ByRef makes the function call slower because of the needed checks and the added process of recalling the value from the stack.