Using References
- Source: https://www.freebasic.net/wiki/wikka.php?wakka=ProPgReferences
- Last revised: 2021-08-31
The syntax for declaring the References and Using them instead of pointers.
Preamble:
The different syntaxes used to declare a reference all use the 'Byref' keyword.
Since a pointer is a variable, it is possible to modify its contents, and the same pointer can allow successive access to different variables. The association between a reference and the object that it designates is, however, fixed when it is declared.
The 'Byref' keyword indicates a variable that is declared by reference. It is used in three different contexts:
In a procedure signature, to pass an argument by reference (byref parameter).
In a function signature, to return a variable to the caller by reference (byref return).
In the body of the code, to define a reference variable (byref variable).
Table of Contents
1. Passing parameter by reference to procedure (byref parameter)
2. Returning variable by reference from function (byref return)
3. Defining reference variable in code (byref variable)
4. References versus pointers by comparative examples
5. Hacking on usage of references with the additional syntaxes allowed by FreeBASIC
1. Passing parameter by reference to procedure (byref parameter)
- Syntax of declaration:
- Full syntax example for passing a parameter by reference:
Note: A pointer can be passed directly (without first dereferencing it) to Byref procedure parameter if in argument term the Byval keyword is specified in front of the pointer name.
2. Returning variable by reference from function (byref return)
- Syntax of declaration:
- Full syntax example for returning a variable by reference:
Specific syntax:
On the left-hand side of an assignment expression using the '=' symbol, the result of the function (returned by reference) must be enclosed in parentheses when the function calls one single argument, in order to solve the parsing ambiguity.
From fbc version 0.90, '=>' can be used for assignments, in place of '=', same as for initializers, allowing to avoid parsing ambiguity (without parentheses):
start GeSHi
Declare Function transitbyref( ByRef _s As String ) ByRef As String
Dim As String s
s = "abcd"
Print s
'' the enclosing parentheses are required here.
( transitbyref( s ) ) = transitbyref( s ) & "efgh"
Print s
'' the enclosing parentheses are not required here.
transitbyref( s ) => transitbyref( s ) & "ijkl"
Print s
Sleep
Function transitbyref( ByRef _s As String ) ByRef As String
'' This var-len string will transit by reference (input and output), no copy will be created.
Return _s
End Functionend GeSHi
Output:
abcd
abcdefgh
abcdefghijklNote: A pointer can be returned directly (without first dereferencing it) for a Byref function return if in identifier= or Function= or Return statement the Byval keyword is specified in front of the pointer name.
3. Defining reference variable in code (byref variable)
- Syntax of declaration:
- Full syntax example for defining a reference variable in code:
4. References versus pointers by comparative examples
- Function returning the greater variable between two integer variables:
- Inheritance structure with overriding subroutine and overriding function with covariant return:
5. Hacking on usage of references with the additional syntaxes allowed by FreeBASIC
In FB, a reference is implemented under the hood through an internal pointer which holds the address of the variable.
The access to this internal pointer is presently allowed for user, in read, and also in write for a reference variable (unlike many other languages):
- Therefore, the address of the referred variable (the value of the internal pointer) can be get by using the '@' operator applied on the reference variable symbol name:
variable_address = @ref
- And even, a reference variable can be reassigned (by modifying the value of the internal pointer) to refer to another variable (of compatible type) by doing:
@ref = @other_variable
- The address of the internal pointer of a reference variable can even be obtained:
internal_pointer_address = @@ref
Note:
- A reference variable can also be re-initialized to a "null" reference:
@ref = 0
- A reference variable can even be directly declared as a "null" reference:
Dim Byref As datatype ref = *Cptr(datatype Ptr, 0)
Thus, by always using the same reference symbol name, one can mix the pure syntax on the reference with the syntax on its internal pointer.
- Example of hacking on reference symbol name:
See also
Byref (parameters),Byref (function results),Byref (variables)Operator @ (Address of),Operator * (Value of)- From Pointers to References
Back to DocToc