This first edition was written for Lua 5.0.
While still largely relevant for later versions, there are
some differences.
The fourth edition
targets Lua 5.3 and is available at Amazon and other bookstores.
By buying the book, you also help to support the Lua project.
Programming in Lua
Part I. The Language
Chapter 5. Functions
5.1 – Multiple Results
An unconventional, but quite convenient feature of Lua
is that functions may
return multiple results.
Several predefined functions in Lua return multiple
values.
An example is the string.find function,
which locates a pattern in a
string.
It returns two indices:
the index of the character where the pattern
match starts
and the one where it ends (or nil if it cannot find the pattern).
A
multiple assignment allows the program to get both results:
s, e = string.find("hello Lua users", "Lua")
print(s, e) --> 7 9
Functions written in Lua also can return multiple results,
by listing them all
after the return keyword.
For instance, a function to find the maximum
element in an array
can return both the maximum value and its location:
function maximum (a)
local mi = 1 -- maximum index
local m = a[mi] -- maximum value
for i,val in ipairs(a) do
if val > m then
mi = i
m = val
end
end
return m, mi
end
print(maximum({8,10,23,12,5})) --> 23 3
Lua always adjusts the number of results from a function to
the circumstances
of the call.
When we call a function as a statement,
Lua discards all of its
results.
When we use a call as an expression,
Lua keeps only the first result.
We get all results
only when the call is the last (or the only) expression in
a list
of expressions.
These lists appear in four constructions in Lua:
multiple
assignment, arguments to function calls,
table constructors, and return
statements.
To illustrate all these uses,
we will assume the following
definitions
for the next examples:
function foo0 () end -- returns no results
function foo1 () return 'a' end -- returns 1 result
function foo2 () return 'a','b' end -- returns 2 results
In a multiple assignment, a function call as the last (or only)
expression
produces as many results as needed to match the
variables:
x,y = foo2() -- x='a', y='b'
x = foo2() -- x='a', 'b' is discarded
x,y,z = 10,foo2() -- x=10, y='a', z='b'
If a function has no results, or not as many results as we need,
Lua produces
nils:
x,y = foo0() -- x=nil, y=nil
x,y = foo1() -- x='a', y=nil
x,y,z = foo2() -- x='a', y='b', z=nil
A function call that is not the last element in the list
always produces one
result:
x,y = foo2(), 20 -- x='a', y=20
x,y = foo0(), 20, 30 -- x=nil, y=20, 30 is discarded
When a function call is the last (or the only) argument to another call,
all
results from the first call go as arguments.
We have seen examples of this
construction already,
with print:
print(foo0()) -->
print(foo1()) --> a
print(foo2()) --> a b
print(foo2(), 1) --> a 1
print(foo2() .. "x") --> ax (see below)
When the call to foo2 appears inside an expression,
Lua adjusts the number
of results to one;
so, in the last line, only the "a" is used in the concatenation.
The print function
may receive a variable number of arguments.
(In the next
section we will see how to write functions with
variable number of
arguments.)
If we write f(g())
and f has a fixed number of arguments,
Lua
adjusts the number of results of g to the number
of parameters of f,
as we saw
previously.
A constructor also collects all results from a call,
without any adjustments:
a = {foo0()} -- a = {} (an empty table)
a = {foo1()} -- a = {'a'}
a = {foo2()} -- a = {'a', 'b'}
As always, this behavior happens only when the call is
the last in the list;
otherwise, any call produces exactly one result:
a = {foo0(), foo2(), 4} -- a[1] = nil, a[2] = 'a', a[3] = 4
Finally, a statement like return f() returns all values
returned by f:
function foo (i)
if i == 0 then return foo0()
elseif i == 1 then return foo1()
elseif i == 2 then return foo2()
end
end
print(foo(1)) --> a
print(foo(2)) --> a b
print(foo(0)) -- (no results)
print(foo(3)) -- (no results)
You can force a call to return exactly one result by
enclosing it in an extra pair
of parentheses:
print((foo0())) --> nil
print((foo1())) --> a
print((foo2())) --> a
Beware that a return statement does not need parentheses around
the
returned value,
so any pair of parentheses placed there counts as an extra
pair.
That is,
a statement like return (f()) always returns one single value,
no matter how many values f returns.
Maybe this is what you want, maybe
not.
A special function with multiple returns is unpack.
It receives an array
and
returns as results all elements from the array,
starting from index 1:
print(unpack{10,20,30}) --> 10 20 30
a,b = unpack{10,20,30} -- a=10, b=20, 30 is discarded
An important use for unpack is in a generic call mechanism.
A generic call
mechanism allows you to call any function,
with any arguments, dynamically.
In ANSI C, for instance, there is no way to do that.
You can declare a function
that receives a variable number of arguments (with stdarg.h)
and you can
call a variable function, using pointers to functions.
However, you cannot call
a function with a variable number of arguments:
Each call you write in C has
a fixed number of arguments
and each argument has a fixed type.
In Lua, if
you want to call a variable function f
with variable arguments in an array a,
you simply write
f(unpack(a))
The call to unpack returns all values in a,
which become the arguments to f.
For instance, if we execute
f = string.find
a = {"hello", "ll"}
then the call f(unpack(a)) returns 3 and 4,
exactly the same as the static call
string.find("hello", "ll").
Although the predefined unpack is written in C,
we could write it also in Lua,
using recursion:
function unpack (t, i)
i = i or 1
if t[i] ~= nil then
return t[i], unpack(t, i + 1)
end
end
The first time we call it,
with a single argument, i gets 1.
Then the function
returns t[1]
followed by all results from unpack(t, 2),
which in turn returns
t[2]
followed by all results from unpack(t, 3),
and so on, until the last non-
nil element.
Copyright © 2003–2004 Roberto Ierusalimschy. All rights reserved.
