Function Call Tutorial

wiki

Passing arguments

Since Lua is dynamically typed and has no need for function type declaration, checking the number and type of arguments required for a function seems somewhat redundant. Lua deals gracefully with mismatched numbers of calling and formal function arguments. Formal function arguments receive a default value of nil if they are not filled. Where too many arguments are passed they are simply ignored. No type is specified for each argument as they are dynamically typed. i.e. we only need to know the type of an object when we use it, not when we reference it. We'll use the following function as an example:

> function foo(a,b,c) print(a,b,c) end

> foo()
nil     nil     nil

> foo(1,2,3,4)
1       2       3

> foo("hello")
hello   nil     nil
> foo("pi", 3.1415, { comment="this is a table" })
pi	3.1415	table: 0x21d49b0

Variable arguments

It is often useful to have variable numbers of arguments to a function. e.g. the printf(format,...) function in C. One way Lua does this is by placing the variable argument list into an array table called arg, usable by the function. e.g.,

> function foo(...) print(arg) end
> foo("abc",3,77)
table: 0x21d56a0

Note: In 5.2 arg is deprecated and three periods (...) can be used instead with similar effect.

> function foo(...) print(...) end

(In some cases, the argument list array must be referenced by placing the three periods within a set of curly braces.)

> function foo(...) for k,v in pairs({...}) do print(k,v) end end

In this example we can only see that this is a table. We could use table.foreach(table,function) to print out the values of the variable argument table, but using pairs() is better, since table.foreach() is deprecated in Lua 5.1.

> function foo(...) for k,v in pairs(arg) do print(k,v) end end
> foo()
n       0

From looking at an empty variable argument list it is easy to see that an extra table pair is added to provide the number of elements in the table, arg.n. In this case the number of arguments is zero. Let's try passing variable numbers of arguments:

> foo(1,2,3)
1       1
2       2
3       3
n       3
> foo("apple",2,"banana",99,3.1415927,foo)
1	apple
2	2
3	banana
4	99
5	3.1415927
6	function: 0x9ecd20
n	6

Another way is to use ... as a placeholder:

> function foo(...) print('x', select(2, ...), 'y', ...) end
> foo("apple", "banana", "orange")
x	banana	y	apple	banana	orange

The ... has an additional advantage in that it avoids the small performance penalty in constructing the arg table.

unpack

A useful function for variable arguments is unpack(). This takes a table and returns a list of variables, e.g.:

> = unpack({1,2,3})
1       2       3

This can be used with variable argument lists as follows:

> function listargs(...)
>>  return unpack(arg)
>> end
> = listargs({1,2,3})
1       2       3
> = listargs({"hello", {1,2,3}, function (x) return x*x end})
hello	table: 0x9efed0	function: 0x9eec40

It can also be used to pass a variable number of arguments to a function as follow:

> function countargs(...)
>>  return #arg
>> end
> = countargs(1,2,3)
3
> = countargs(unpack{1,2,3})
3

To understand how unpack works, look at this slow pseudo implementation:

>    function unpack (t, i)
>>      i = i or 1
>>      if t[i] ~= nil then
>>>        return t[i], unpack(t, i + 1)
>>      end
>    end

Taken from the lua reference manual: [chapter 5.1 - Multiple Results].

Multiple return values

Lua can return more than one value from a function. This is done by returning a comma separated list of values:

> function foo(angle)
>>  return math.cos(angle), math.sin(angle)
>> end
>
> print( foo(1) )     -- returns 2 values...
0.54030230586814        0.8414709848079
>
> c,s = foo(3.142/3)  -- assign the values to variables
> = math.atan(s/c)
1.0473333333333
> = c,s
0.49988240461137        0.86609328686923
>
> function many(x)
>>  return x, x*x, x*x*x, x*x*x*x, x*x*x*x*x
>> end
> = many(5)
5       25      125     625     3125
> = many(0.9)
0.9     0.81    0.729   0.6561  0.59049

The above function could have a variable number of return values if we construct a table, containing the values, and use unpack. E.g.,

> function many2(x,times)
>>  local t = {}
>>  for i=1,times do t[i] = x^i end
>>  return unpack(t)
>> end
> = many2(5,10)
5       25      125     625     3125    15625   78125   390625  1953125 9765625
> = many2(0.5,7)
0.5     0.25    0.125   0.0625  0.03125 0.015625        0.0078125

Values as a table

We can also return the values in a table. To do this we add curly brackets around the function call, which will construct a table, i.e.:

{ function_name ( args ) }

Here is an example using the previous function example:

> = { foo(1.5) }
table: 0x204e100
> t = { foo(1.5) }
> for k,v in ipairs(t) do print(k,v) end
1       0.070737201667703
2       0.99749498660405

Single Value

If a function returns multiple values, but we only want the first value, we put a parenthesis around the function call, i.e.

( function_name ( args ) )

> = (foo(1.5))
0.070737201667703
> = foo(1.5)
0.070737201667703       0.99749498660405

The same could be achieved by returning a table and taking the first element but the above syntax is more efficient. E.g.,

> = ({foo(1.5)}) [1]
0.070737201667703