A question was raised on the various Corona support channels: “What is the return statement and when do I need to use it?” Before that question can be answered, you need to understand what functions are and how Lua uses them.
Functions are blocks of code that can be reused. Consider changing a car tire:
- Take out jack, lug wrench and spare tire from trunk
- Put the lug wrench on nut #1
- Rotate counter-clockwise until the nut comes off
- Put the lug nut in a safe place
- Put the lug wrench on nut #2
- Rotate counter-clockwise until the nut comes off
- Put the lug nut in a safe place
- Put the lug wrench on nut #3
- Rotate counter-clockwise until the nut comes off
- Put the lug nut in a safe place
- Put the lug wrench on nut #4
- Rotate counter-clockwise until the nut comes off
- Put the lug nut in a safe place
- Put the lug wrench on nut #5
- Rotate counter-clockwise until the nut comes off
- Put the lug nut in a safe place
- Jack up the car
- Remove the flat tire
- Put the spare tire on
etc.
Computer code executes in a linear fashion. If you were to write this out in computer code you end up repeating yourself multiple times. It makes more sense to take the lug nut removal code and put it in a function. Consider this pseudo-code:
Function removeLugNut( lugNutNunber ) Put the lug wrench on nut # lugNutNumber Rotate counter-wise until the nut comes off. Put the lug nut in a safe place
This reduces our algorithm to:
- Take out jack, lug wrench and spare tire from trunk
- For each lugNutNumber
- removeLugNut( lugNutNumber)
- Jack up the car
- Remove the flat tire
- Put the spare tire on
The code is much more compact. It follows a main developer principle called DRY – Don’t Repeat Yourself.
Functions can be used in a variety of ways in Corona apps. Let’s look at a basic example:
local function movePlayer() player.x = player.x + 1 end
This function does not need any information. It uses an existing defined object: player and increments its .x position by one. It takes no parameters and doesn’t pass any data back to the calling code. You might use this inside another function that runs every clock tick:
local function enterFrameListener() movePlayer() end
Since you don’t put anything inside the parentheses, you are sending nothing to the function. But you could easily pass information to the function. You may want to make this function a little more generic. Instead of movePlayer, you could say moveObject. You could also provide the speed:
local function moveObject( object, speed ) object.x = object.x + speed end local function enterFrameListener() moveObject( player, 1) end
Now that you know how to pass information to a function what about getting it back? First, not all functions need to send data back, but when you do, you can do so using Lua’s return statement.
At the machine code level, all of the above functions have an implied return statement. As a convenience to Lua developers, you don’t need to specify one if you don’t need it, thus:
local function moveObject( object, speed ) object.x = object.x + speed end
and
local function moveObject( object, speed ) object.x = object.x + speed return nil end
are identical.
The return statement has two main purposes. First, it can be used to force a function to end early. Let’s look at that example:
local function moveObject( object, speed ) If object == nil or object.x == nil then -- This isn't a display object, so exit the function without doing any more work return end object.x = object.x + speed end
Since the code didn’t have a valid object to change the value of x on, you can exit the function and avoid a potential error.
The second use of a return statement is to pass information back to the code that called the function, That information could be a simple success or failure indicator, or it could pass back values that are more useful. Let’s look at the simple success/failure situation modifying above function.
local function moveObject( object, speed ) if object == nil or object.x == nil then -- This isn't a display object, so exit the function without doing any more work return false -- let the calling code know it failed end object.x = object.x + speed return true -- the function successful, so let the caller know. end
To receive the data, the code calling the function can either store the return value in a variable or test it in a conditional test.
local function enterFrameListener() if not moveObject( player, 1) then print("The object failed to move since object isn't a display object") end end
Sometimes you need to capture the values. Let’s look at this simple function that adds two numbers together:
local function addTwoNumbers( num1, num2 ) local sum = num1 + num2 return sum end local sum = addTwoNumbers(10, 20) print("The sum is", sum)
Now you can pass data to the function as well as receive information back using the return statement.
Most programming languages can only return one value (though it could be a table, dictionary, or list with multiple values). Lua, however lets you return multiple values. Lets go back to the moveObject function.
local function moveObject( object, speed ) if object == nil or object.x == nil then -- This isn't a display object, so exit the function without doing any more work return false, "This does not appear to be a display object" -- let the calling code know it failed end object.x = object.x + speed return true, "Success" -- the function successful, so let the caller know. end local function enterFrameListener() local success, message = moveObject( player, 1) if not success then print( message ) end end
You can see from this tutorial how the return statement can be useful in your Corona adventures.