Return Values

The functions you've written so far print something, and that's it. But often you want a function to calculate a value for the program to keep working with: to add up, compare or store. Then the function returns the value with return:

local function harvestValue(count, price)
    return count * price
end

local carrots = harvestValue(12, 5)
print("Carrots: " .. carrots .. " coins")
print("Pumpkins: " .. harvestValue(4, 20) .. " coins")

This prints:

Carrots: 60 coins
Pumpkins: 80 coins

The call harvestValue(12, 5) runs the function, and return sends 60 back to the place of the call. You can imagine that Lua replaces the call with the returned value, so local carrots = harvestValue(12, 5) becomes local carrots = 60. This value is the function's return value. You can use a call anywhere you'd write a value: in a variable, in print, in a calculation or in a condition such as if harvestValue(12, 5) > 50 then. You know such functions already: math.max(3, 8) returns 8, and tostring(5) returns "5".

return also ends the function right away. Together with conditions, that makes short functions that return different values in different cases:

local function sellPrice(crop)
    if crop == "carrot" then
        return 5
    elseif crop == "potato" then
        return 8
    end
    return 0
end

print(sellPrice("potato"), sellPrice("carrot"), sellPrice("stone"))

This prints:

8	5	0

For "potato", the second return runs and the function ends: Lua never gets to return 0. It gets there only when no condition is true. In Lua, return must be the last line of its block (right before end, else or elseif). A line after it in the same block is a syntax error: 'end' expected … near 'print'.

Beginners often mix up print and return, because both seem to give a value out. But print only shows the value to you, in the output, and the program can't work with it. return gives the value to the program. Look at a function that prints its result instead of returning it:

local function harvestValue(count, price)
    print(count * price)
end

local carrots = harvestValue(12, 5)
print(carrots)
print(carrots + 10)

This prints:

60
nil
main.lua:7: attempt to perform arithmetic on a nil value (local 'carrots')

The 60 comes from the print inside the function. But the function returned nothing, so carrots is nil, and the calculation ends with an error. When you see nil where you expected the result of a function, check that the function has a return. A good rule: a function that calculates something returns the result, and the code that calls it decides whether to print it, store it or keep calculating.