Passing Arguments by Value and by Reference

Article
11/16/2012

In Visual Basic, you can pass an argument to a procedure by value or by reference. This is known as the passing mechanism, and it determines whether the procedure can modify the programming element underlying the argument in the calling code. The procedure declaration determines the passing mechanism for each parameter by specifying the ByVal or ByRef keyword.

Distinctions

When passing an argument to a procedure, be aware of several different distinctions that interact with each other:

Whether the underlying programming element is modifiable or nonmodifiable
Whether the argument itself is modifiable or nonmodifiable
Whether the argument is being passed by value or by reference
Whether the argument data type is a value type or a reference type

For more information, see Differences Between Modifiable and Nonmodifiable Arguments and Differences Between Passing an Argument By Value and By Reference.

Choice of Passing Mechanism

You should choose the passing mechanism carefully for each argument.

Protection. In choosing between the two passing mechanisms, the most important criterion is the exposure of calling variables to change. The advantage of passing an argument ByRef is that the procedure can return a value to the calling code through that argument. The advantage of passing an argument ByVal is that it protects a variable from being changed by the procedure.
Performance. Although the passing mechanism can affect the performance of your code, the difference is usually insignificant. One exception to this is a value type passed ByVal. In this case, Visual Basic copies the entire data contents of the argument. Therefore, for a large value type such as a structure, it can be more efficient to pass it ByRef.

For reference types, only the pointer to the data is copied (four bytes on 32-bit platforms, eight bytes on 64-bit platforms). Therefore, you can pass arguments of type String or Object by value without harming performance.

Determination of the Passing Mechanism

The procedure declaration specifies the passing mechanism for each parameter. The calling code cannot override a ByVal mechanism, but if a parameter is declared with ByRef, the calling code can force the mechanism to ByVal by enclosing the argument name in parentheses in the call.

The default in Visual Basic is to pass arguments by value. You can make your code easier to read by using the ByVal keyword. It is good programming practice to include either the ByVal or ByRef keyword with every declared parameter.

When To Pass an Argument by Value

If the calling code element underlying the argument is a nonmodifiable element, declare the corresponding parameter ByVal. No code can change the value of a nonmodifiable element.
If the underlying element is modifiable, but you do not want the procedure to be able to change its value, declare the parameter ByVal. Only the calling code can change the value of a modifiable element passed by value.

When To Pass an Argument by Reference

If the procedure has a genuine need to change the underlying element in the calling code, declare the corresponding parameter ByRef.
If the correct execution of the code depends on the procedure changing the underlying element in the calling code, declare the parameter ByRef. If you pass it by value, or if the calling code overrides the ByRef passing mechanism by enclosing the argument in parentheses, the procedure call might produce unexpected results.

Example

Description

The following example illustrates when to pass arguments by value and when to pass them by reference. Procedure Calculate has both a ByVal and a ByRef parameter. Given an interest rate, rate, and a sum of money, debt, the task of the procedure is to calculate a new value for debt that is the result of applying the interest rate to the original value of debt. Because debt is a ByRef parameter, the new total is reflected in the value of the argument in the calling code that corresponds to debt. Parameter rate is a ByVal parameter because Calculate should not change its value.

Code

Module Module1

    Sub Main()
        ' Two interest rates are declared, one a constant and one a  
        ' variable. 
        Const highRate As Double = 12.5
        Dim lowRate = highRate * 0.6

        Dim initialDebt = 4999.99
        ' Make a copy of the original value of the debt. 
        Dim debtWithInterest = initialDebt

        ' Calculate the total debt with the high interest rate applied. 
        ' Argument highRate is a constant, which is appropriate for a  
        ' ByVal parameter. Argument debtWithInterest must be a variable 
        ' because the procedure will change its value to the calculated 
        ' total with interest applied.
        Calculate(highRate, debtWithInterest)
        ' Format the result to represent currency, and display it. 
        Dim debtString = Format(debtWithInterest, "C")
        Console.WriteLine("What I owe with high interest: " & debtString)

        ' Repeat the process with lowRate. Argument lowRate is not a  
        ' constant, but the ByVal parameter protects it from accidental 
        ' or intentional change by the procedure.  

        ' Set debtWithInterest back to the original value.
        debtWithInterest = initialDebt
        Calculate(lowRate, debtWithInterest)
        debtString = Format(debtWithInterest, "C")
        Console.WriteLine("What I owe with low interest:  " & debtString)
    End Sub 

    ' Parameter rate is a ByVal parameter because the procedure should 
    ' not change the value of the corresponding argument in the  
    ' calling code.  

    ' The calculated value of the debt parameter, however, should be 
    ' reflected in the value of the corresponding argument in the  
    ' calling code. Therefore, it must be declared ByRef.  
    Sub Calculate(ByVal rate As Double, ByRef debt As Double)
        debt = debt + (debt * rate / 100)
    End Sub 

End Module

Change History

Date	History	Reason
September 2008	Added example section.	Customer feedback.