In this article we will continue our discussion of C# methods, especially passing parameters by value and by reference, and we will also discuss the out and ref keywords. We will end the article with a discussion covering how to create variable parameters methods. An understanding of .NET Types is essential to understanding important parts of this tutorial, so you should read the previous articles (of the series) in order to get the most out of this work.
When you call a method, your code must provide values for the method's parameters. By default, the method creates its copy of the arguments, so you will have two separate copies (the argument and the parameter). This process is called pass by-value, and it's the default in C#.The behavior will differ depending on the passed type, so if you are passing a Value-Type (in this case the value itself will be copied to the method) then the changes made in the parameter value (the one inside the method) will not affect the argument value, because it's a separate copy.
If the passed type is a Reference-Type (in this case the reference itself will be copied, not the object's properties and methods, because it's a copy by value), then you will have two references to the same object, and you can change a property value of the object because you have a reference to it.
There is another parameter vs. argument copying behavior called copy by reference. Again, it differs from Value-Types to Reference-Types, and you have to use the parameter modifier keywords out or ref, as we will discuss soon. For now, when you pass a value type by reference, a reference to the value-type will be passed, and changes made inside the method will be reflected to the argument value. When you pass a Reference-Type, it will pass a reference to the Reference that refers to the object; in other words, it's a double reference.
So we have four cases here: passing Value-Types by value, passing Value-Types by reference, passing Reference-Types by value and passing Reference-Types by reference. Reading this article will help you to establish a good foundation in C# programming techniques.
As you know, a variable of a Value-Type contains the value itself, and when you assign that variable to another variable, it will copy its value into the new variable. The same thing happens when you pass a variable as an argument to a method's parameter; the method makes a copy of the variable's value on its local stack. So the argument and the parameter both refer to separate copies, and any changes made by the method to its own copy (the method parameter) will not be reflected to the calling code variable (the argument). This is the default, as we said before. Consider the following example:
using System; namespace MyCompany { public class MethodTest { static void Main() { int ValueType = 10; Console.WriteLine("The value of the variable ValueType = {0}",ValueType); TakeNumber(ValueType); Console.WriteLine("After calling the method the value of" + "the variable ValueType = {0}", ValueType); Console.ReadLine(); }
static void TakeNumber(int x) { x++; Console.WriteLine("Inside the method the parameter x = {0}", x); } } }
The result will be:
The code declares a variable of type integer (ValueType) and assigns the value 10 to it, then it prints this variable's value to the Console window. It then calls the method TakeNumber, and passes the variable to it. Inside the method, we increase the parameter x by one, then print its value (which is 11). The method ends, and we are back to our Main method, where we again print the value of the variable ValueType after the method call, and it's still 10. This proves that changes made to the parameter inside the method don't change or modify the calling code variable (ValueType). The method creates its own copy of the variable (which we call the parameter) and allocates it on its local Stack.
Let's pass the ValueType variable by reference to see what will happen. To pass a Value-Type (or Reference-Type) by reference, you need to use the parameter modifier keyword ref (or out as we will see in the section covering output parameters). You must use the ref keyword in the method declaration, with method invocation. When you use the ref keyword, you actually pass a reference to the data, and there is no data copying process. Changes made to the method's parameter will be reflected to the calling code variable. Modify the above code as follows:
using System; namespace MyCompany { public class MethodTest { static void Main() { int ValueType = 10; Console.WriteLine("The value of the variable ValueType = {0}",ValueType); TakeNumber(ref ValueType); Console.WriteLine("After calling the method the value of" + "the variable ValueType = {0}", ValueType); Console.ReadLine(); }
static void TakeNumber(ref int x) { x++; Console.WriteLine("Inside the method the parameter x = {0}", x); } } }
Here's the result:
This time the result is different. Inside the method, the parameter x = 11, and after the method terminates the calling code variable has been assigned 11. To make it easy for you, think of passing a Value-Type by reference as follows: first, you declare the method's parameter with the ref keyword, then you call the method and pass the Value-Type, also with the ref keyword. The ref keyword actually does one thing with Value-Type: it tells the CLR where the value type is. When the method modifies the parameter and terminates, the new value is copied back to the location where the Value-Type lives.
I can't tell you when to pass a Value-Type by reference because it may fit in many scenarios. For example, you have a class that contains a method that accepts three Value-Type parameters and, as you know, that methods return only one value back. But in your scenario, you need to change these three variables, so the perfect solution is to make your method as void, and declare the parameters with the ref keyword, so any changes made inside the method will affect the variables.
Let's take a look at how passing by value and by reference affects Reference-Types.
When you pass an object variable to a method parameter, the default behavior is to copy by value -- but in the case of a Reference-Type, the copied value is not the object itself. In other words, the copied value is not the object fields and methods. What actually happens is that a reference to the object is just copied from the object variable to the method parameter, and this is similar for to having a Value-Type passed by reference (using the ref keyword).
When you pass a Value-Type by reference, a reference to the variable is passed to the method. This means that both the variable (which contains the value itself) and the method parameter (which contains a reference to the value) refer to the same data. Passing a Reference-Type by value differs. When you pass a Reference-Type by value, a copy of the object reference is passed to the method parameter, which means that we have one object located on the Heap, with two references located on the Stack. Actually, it is worth noting that the object reference is a value that lives on the Stack, and it refers to the actual object on the Heap.
So let's look at an example:
using System; namespace MyCompany { public class MethodTest {
static void Main() { Order order = new Order(); order.OrderNumber = 12345; Console.WriteLine("order.OrderNumber = {0}",order.OrderNumber); TakeObject(order); Console.WriteLine("after the method call " + "order.OrderNumber = {0}",order.OrderNumber); Console.ReadLine(); }
As you can see, the Main method creates an object of type Order and assigns the value 12345 to the OrderNumber field of that object. Then it prints to the Console the value of the object's field, calls the static method TakeObject, and passes the order object to it. The method assigns a new value to the parameter and terminates. The Main method again prints the value of the object's field and, as you can see, it has been changed after the method call. To make it clear that the method just has another reference to the object, take a look at the following revised version of the above code:
using System; namespace MyCompany { public class MethodTest {
static void Main() { Order order = new Order(); order.OrderNumber = 12345; Console.WriteLine("order.OrderNumber = {0}",order.OrderNumber); TakeObject(order); Console.WriteLine("after the method call " + "order.OrderNumber = {0}",order.OrderNumber); Console.ReadLine(); }
static void TakeObject(Order ord) { ord = null; } }
public class Order { public int OrderNumber; } }
Now the result is:
We just assign null to the method parameter to prove that it's just another reference. When we assigned the reference to null, the object had not been affected, and the order .OrderNumber still equals to the same value (12345).
You can also pass a Reference-Type by reference, but it's dangerous and should be avoided except for the situations that you are sure you need it. For example, you can pass an object to a method (by reference using the ref keyword) and the method can destroy your object, or even assign it to a new, different one. The next example is a modified version of the above code:
using System; namespace MyCompany { public class MethodTest {
static void Main() { Order order = new Order(); order.OrderNumber = 12345; Console.WriteLine("order.OrderNumber = {0}",order.OrderNumber); TakeObject(ref order); Console.WriteLine("after the method call " + "order.OrderNumber = {0}",order.OrderNumber); Console.ReadLine(); }
static void TakeObject(ref Order ord) { Order newOrder = new Order(); newOrder.OrderNumber = 987123; ord = newOrder; Console.WriteLine("The method assign a new object to the parameter" + "and passing 987123 to OrderNumber"); } }
public class Order { public int OrderNumber; } }
The result is:
The method TakeObject takes an Order object parameter and destroys it by creating a new one and assigning a new value to the field OrderNumber. So passing a Reference-Type by reference makes a double reference. In other words, it makes a reference to the reference, which refers to the object. In our example, when we pass the order object reference to the method, the ref keyword creates a reference to the order object reference, and when the method makes any changes it will be reflected to the reference (because we have a reference to the object reference). In our example, we assigned a new object to the parameter ord, which in turn assigned this new object reference to the calling code object reference.
The out parameter modifier keyword has the same effects as the ref keyword, with one important difference. With the ref keyword, you must initialize the variable before you pass it as the method parameters, but with the out keyword you can initialize the variable inside the method as follows:
using System; namespace MyCompany { public class MethodTest {
static void Main() { int ValueType; TakeNumber(out ValueType); Console.WriteLine("After calling the method the value of" + "the variable ValueType = {0}", ValueType); Console.ReadLine(); }
static void TakeNumber(out int x) { x = 10; Console.WriteLine("Inside the method we initialized x, x = {0}", x); x++; Console.WriteLine("we increased x by one inside the method, x = {0}", x); } } }
The result will be:
We have passed an uninitialized variable to the method, and then we have initialized the variable inside the method. Note that the effects of the out keyword are the same as the ref keyword, so it's considered pass by reference behavior.
The best example to explain a method that takes a variable length of parameters at runtime is the Main method. Look at the following code:
using System; namespace MyCompany { public class MethodTest {
static void Main(params string[] names) { foreach(string name in names) { Console.WriteLine(name); } Console.ReadLine(); } } }
Run this code as you see in the next Console Window and you will get the result you see:
Note that we didn't use a parameter list with the Main method, but we used the params keyword followed by an array of string objects. When you execute a command line program, you can pass a variable list of parameters to the application for processing. Using the params keyword followed by an array, you can pass a variable list of parameters. The application does nothing more than iterate through the array and print the names.
C# Methods, part 1
