====== BYREF ======
/* Remove the comments after creating content for each section.*/

Parameter or argument modifier to allow "passing by reference"; also used in variable declarations

/*
  For the lines below, just create links, separated by commas, to other pages of the BASICs section,
  like [[:basics:basicTagName]].
  
  "Implemented by" should mention BASICs which implement the keyword like described, in a more usual and standard way.
  
  "With variations" should point to BASICs where this keyword is used a bit differently.
  
  "Also written as" should list alternative spellings and abbreviations this keyword has. No need to
  refer to a BASIC, there is a section for that later.
*/

**Implemented by:** [[:basics:FreeBASIC:]], [[:basics:Gambas:]]

**With variations:** 

**Also written as: ** 

===== Usage =====
/* For inline examples of syntax, write the keyword between '' and '' (two single quotes) */

In a more common usage, BYREF is used in the context of a function declaration or a function call, so that if a variable name is used as argument, the function is able to access this variable itself, instead of only receiving a copy of the value it holds.

<code freebasic>
Sub ChangeVar(ByRef AVar As Integer)
    AVar = AVar + 1
End Sub

ChangeVar MyVar  ' increments MyVar itself
</code>



==== Variations ====

In Gambas, a function whose declaration contains a parameter modified by BYREF becomes able to receive the argument as a reference, but it still can come as a value only. The function //call// must also use BYREF in order to force the argument to be passed by reference:

<code gambas>
MyFunc(ByRef outerVar)
</code>

FreeBASIC's documentation is more detailed about restrictions and limitations of BYREF and its sister [[BYVAL]] (as an example: arrays are always passed by reference, so BYREF is not only unnecessary but //forbidden//). Also, the //-lang// directive for "language mode" influences such restrictions and the way parameters are passed by default: in the //fb// dialect arguments are mostly passed by value, while in //qb// and //fblite// dialects arguments are passed by reference by default.  

Also, FreeBASIC allows BYREF to be used as a modifier in variable declarations.


===== Examples =====
/*
  Below is an example of a code block, using GeSHi syntax highlighting for //gwbasic//. Other styles of interest might be
  //basic4gl//, //blitzbasic//, //freebasic//, //gambas//, //locobasic//, //purebasic//, //qbasic//, //sdlbasic//,
  //thinbasic//, //vb//, //vbnet//, //xbasic// or //zxbasic//. 

  <code gwbasic>
  10 PRINT "HELLO"
  </code>
*/



===== Comments =====
/* Origin of the keyword, opinions, history... */


===== Related keywords =====
/* Keywords that are often or always used along this one */

  * [[BYVAL]]

===== Similar keywords =====
/* Keywords with the same or similar functionality found in other versions of BASIC */

  * [[POINTER]]

===== In other languages... =====
/* For parallels and comparisons with other modern-day languages */

BYREF somehow provides a similar effect as that of passing //pointers// as function arguments in the C language.

===== References =====
/* If you used the ((citation)) syntax elsewhere in the text, they will appear under this section. But you can write some recommendations of books, magazines, etc */

  * https://www.freebasic.net/wiki/KeyPgByref , last check 2024-03-03
  * https://gambaswiki.org/wiki/lang/byref , last check 2024-03-03
  * https://gambaswiki.org/wiki/doc/byref , last check 2024-03-03

/*
  ===== TAGS =====
  Please use the syntax below for adding tags to this page, separated by spaces (use quotes for tags with spaces).
  The most important tags to be used are, separated by groups:
    - Statements | Commands | SpecialVariables | Operators
  
  {{tag>tagName}}
*/
{{tag>Modifiers Variables Parameters Arguments}}