Reference Variables

Passing a variable by reference means that rather than copying the contents of the variable
you are working with the same actual variable.  This is similar to instancing objects
in Maya.  The look like different objects, but changing one changes all of them.

Many programming languages offer this option, and in some it is the only option.
In Mel, array variables are always passed by reference.

Here's an example, taken from the intro to this section:

// a simple procedure to combine two arrays
global proc arrayCombine(string $one[], string $two[])
{
	int $i;
	int $num = `size $two`;
	for ($i = 0; $i < $num; $i++)
	{
		$one[`size $one`] = $two[$i];
	}
}
string $someStuff[] = {"this string", "needs more"};
string $moreStuff[] = {"stuff is cool", "for the most part"};
print "Before passing by reference:\n";
print $someStuff;
arrayCombine($someStuff, $moreStuff);
print "After passing by reference:\n";
print $someStuff;


A very useful aspect of passing by reference is as a substitute for return values
in procedures.
Here's a simple example:
more about this in the file I/O section.

// read the contents of the given file into the given array
// returns 0 if it could not open the file
// 1 if it could
global proc int djnReadFileIntoArray (string $path, string $lines[])
{
	int $success = 0;
	int $file = `fopen $path "r"`;
	if ($file)
	{
		while (!`feof $file`)
		{
			$lines[`size $lines`] = `fgetline $file`;
		}
		$success = 1;
		fclose $file;
	}
	return $success;
}


One reason passing by reference is used here is for efficiency.
In C++ it would be more efficient, whether it actually is here depends on what the
Mel interpreter is doing internally. I'm not positive whether it actually makes a difference,
but it definitely isn't slowing it down.

This does allow you to simplify your code a little bit:

string $file = "E:/scripts/thisFileIsCool.mel";
string $lines[];
if(`djnReadFileIntoArray $file $lines`)
{
	// do stuff with the text
}else{
	error ("Could not open file " + $file );
}


It's even more useful when you really need multiple types of data returned from
a procedure.  For example, heres a simple proc that reads through a file and
captures every line containing a certain piece of text as well as the line number it
occurred on

global proc int getLinesWith( string $path, string $find, string $lines[], int $lineNums[])
{
	int $success = 0;
	int $fileId = `fopen $path "r"`;
	if ($fileId)
	{
		int $count = 0;
		while (!`feof $fileId`)
		{
			string $line = `fgetline $fileId`;
			string $match = `match $find $line`;
			if (size($match))
			{
				$lines[`size $lines`] = $line;
				$lineNums[`size $lineNums`] = $count;
			}
			$count++;
		}
		fclose $fileId;
		$success = 1;
	}
	return $success;
}


for more about reading and writing to files see: file I/O section.

So that's passing by reference.  It's real easy, but remember to keep track of if
a procedure modifies an array given to it, otherwise you could end up with
some nasty bugs.