User Function

Revision as of 09:37, 28 August 2013

Function <name> ( <Parameters> ... )
{
	statements
	...
}

Description

Features

Remarks

Examples

Important Examples

Unlimited Function Parameters

If you’ve most likely noticed that several function such as println() can take an indeterminate number of arguments. Normally when defining a function you specify each argument in the function declaration. Obviously it would be impossible to define an infinite number of arguments in such a way. Sputnik does, however, allow you to accomplish this through the array @args.

@args is an array consisting of all of the arguments passed to a function. Using this method you can bypass the conventional method of defining parameters in the function definition all-together. Here is an example:

println( Add(1, 2, 3) ); // will return 6
 
Function Add()
{
	my $Total = 0;
	foreach( @args as my $item )
	{
		$Total += $item;
	}
	return $Total;
}

If for whatever reason you need to know the total number of arguments passed to a function, You can simply use UBound($args) within the function.

When retrieving arguments in this manner it is important to remember that @args only contains an array of arguments passed by the user. It does not account for default values etc.

Note - If outside a function @args will return an empty array.

Function Rules

You can add special rules to your function to tell it how to operate using the [] brackets before the word "Function".

Here is a list of the possible rules:

TYPE                   WHAT IT DOES
Args                   Allows disabling the creation of @ARGS variable
Returns                Forces a specific return type to the function (gives exception if wrong type is given)
ReturnCast             Casts all return values to this type if it is not already

Example of using Rule: Args

println("### First no rule");
Test("Cat", "Dog");
println("### Now with rule");
TestWithRule("Cat", "Dog");
 
// A test function with no rules so @args should be created
Function Test($a, $b)
{
	println("\$a: $a \$b: '$b'");
	println("\@args[0]: @args[0] \@args[1]: '@args[1]'");
	printr(@args);
}
 
// This function is same as above but this time with the rule
[Args("false")]
Function TestWithRule($a, $b)
{
	println("\$a: $a \$b: '$b'");
	println("\@args[0]: @args[0] \@args[1]: '@args[1]'");
	printr(@args);
}
// Notice the test with the rule had no @args variable at all?
// This can useful if this function gets called millions of times
// and you want to squeeze every ounce of speed out of it

General Examples

println( Add(1, 2) ); // will return 3
 
Function Add($a, $b)
{
	return $a + $b;
}

println( Add(2) ); // will return 52
println( Add(2, 4) ); // will return 6
 
Function Add($a, $b = 50)
{
	return $a + $b;
}

println( Add() ); // will return 60
println( Add(2) ); // will return 52
println( Add(2, 4) ); // will return 6
 
Function Add($a = 10, $b = 50)
{
	return $a + $b;
}

Test("CAT", 111);
 
Function Test
{
	my List ($Name, $Password) = @args;
	println("Name '$Name' Password '$Password'");
};