What's the meaning of 'ByRef'?

[Joeyy]

ByRef Parameters: From the function's point of view, parameters are essentially the same as local variables unless they are defined as ByRef as in this example:
Swap(ByRef Left, ByRef Right)

{
temp := Left
Left := Right
Right := temp
}

In the example above, the use of ByRef causes each parameter to become an alias for the variable passed in from the caller. In other words, the parameter and the caller's variable both refer to the same contents in memory. This allows the Swap function to alter the caller's variables by moving Left's contents into Right and vice versa.

By contrast, if ByRef were not used in the example above, Left and Right would be copies of the caller's variables and thus the Swap function would have no external effect.

Since return can send back only one value to a function's caller, ByRef can be used to send back extra results. This is achieved by having the caller pass in a variable (usually empty) in which the function stores a value.

I have read the help above, but I still don't understand. Can anyone give me an example to explain this?

[Masonjar13]

Typically, params stated for a function will copy the variable contents. ByRef means to use the pointer to the original variable instead, rather than make a copy. That means, if the function changes the variable, it will affect the original one as well.

Taking one step back, assuming you know nothing of functions, the namespace, or data that a function has available, is limited to the space it has created. Unless a function or variable is defined as [super]global, a function can't interact with variables outside of the function. This is what makes functions reusable. You call a function, it creates a space for it, then discards the space afterwards, so any future calls will not reflect previous calls.

Using [super]global variables is considered bad practice due to most code following a modular design, one that anyone can add to. If there are a bunch of global vars hanging about, it can very easily mess up a newly created function by someone who wasn't aware of those global vars. To get around that while still keeping functions contained, you can pass pointers, which are just location values of the variables in memory. Since you can only return one value (which could be an object with a set of values), if you wanted to return multiple separate variables, you could use ByRef to do that.

Here's a non-practical example:

Code: Select all

var1:=20
var2:=30
returnVar:=func1(var1,var2) ; will create a local copy in the function, won't touch original variables
msgbox % var1 . "`n" . var2 . "`n" . returnVar
returnVar:=func2(var1,var2) ; will use a pointer, will affect original variables
msgbox % var1 . "`n" . var2 . "`n" . returnVar
exitApp

func1(param1,param2){
    param1:=1000,param2:=2000
    return param1+param2
}
func2(byref param1,byref param2){
    param1:=1000,param2:=2000
    return param1+param2
}

[wolf_II]

Try this:

Code: Select all

#NoEnv
#SingleInstance Force

Input := 5
Output := 0

myFunc(Input, Output)
MsgBox, % Output

myFunc(a, ByRef b) {
    MsgBox, %a%`n%b%
    b := 42
}

In the example, I use a single ByRef. Remove it to see how usually, we can not put output values into an input-parameter.
Byref allows exactly that.
I hope that helps.

[Joeyy]

@wolf_II@Masonjar13
Thanks for your kindness!