Wiki source for KeyPgByref


Show raw source

{{fbdoc item="title" value="BYREF (parameters)"}}----
Declaration specifier to explicitly pass a parameter by reference

{{fbdoc item="syntax"}}##
**Byref** //param// [[KeyPgAs|as]] [[DataType|datatype]]
##
{{fbdoc item="usage"}}##
[ [[KeyPgDeclare|declare]] ] { [[KeyPgSub|sub]] | [[KeyPgFunction|function]] } //proc_name// ( **Byref** //param// [[KeyPgAs|as]] [[DataType|datatype]] )
##
{{fbdoc item="desc"}}
Passes a variable by reference, that is its address, to a subroutine or function. When a variable is passed by reference, the contents of the variable can be changed by the target subroutine or function.

In //[[CompilerOptlang|-lang qb]]// and //[[CompilerOptlang|-lang fblite]]// dialects, ##**Byref**## is the default parameter passing convention, unless ##[[KeyPgOptionbyval|Option ByVal]]## is in effect.

Opposite of ##[[KeyPgByval|ByVal]]##.

**Note:** A constant or a literal expression can also be passed to such a procedure (which gets by reference), but they are obviously not modifiable from the procedure body. In that case, the compiler passes by reference a temporary variable initialized with the constant or the literal expression.

**Warning:** When passing by reference, it is recommended to pass an argument of the same type (or fully compatible, like a derived type for example) as that of the declared parameter. Although in some cases the compiler accepts to pass a different type, often the result is not the one expected.

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/procs/byref.bas"}}%%(freebasic)
dim MyVar as integer

sub ChangeVar(byref AVar as integer)
AVar = AVar + 1
end sub

MyVar = 1
print "MyVar: "; MyVar 'output = 1
ChangeVar MyVar
print "MyVar: "; MyVar 'output = 2
sleep
end
%%

{{fbdoc item="lang"}}
- In //[[CompilerOptlang|-lang fb]]// dialect, ##[[KeyPgByval|Byval]]## is the default parameter passing convention for all built-in types except ##[[KeyPgString|String]]## and user-defined ##[[KeyPgType|Type]]## which are passed ##**Byref**## by default. The ##[[KeyPgZstring|Zstring]]## and ##[[KeyPgWstring|Wstring]]## built-in types are also passed ##**Byref**## by default, but passing ##[[KeyPgByval|Byval]]## is forbidden. Arrays are always passed ##**Byref**## and the use of the specifier ##**Byref**## or ##[[KeyPgByval|Byval]]## is forbidden.
- In //[[CompilerOptlang|-lang qb]]// and //[[CompilerOptlang|-lang fblite]]// dialects, ##**Byref**## is the default parameter passing convention.

{{fbdoc item="diff"}}
- New to ""FreeBASIC""

{{fbdoc item="see"}}
- [[ProPgPassingArguments|Passing Arguments to Procedures]]
- ##[[KeyPgDeclare|Declare]]##
- ##[[KeyPgByval|ByVal]]##
- ##[[KeyPgByrefFunction|Byref (function results)]]##
- ##[[KeyPgByrefVariables|Byref (variables)]]##

{{fbdoc item="back" value="CatPgProcedures|Procedures"}}
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki



sf.net phatcode