This post was originally published at Functions and return statements in Corona

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:

  1. Take out jack, lug wrench and spare tire from trunk
  2. Put the lug wrench on nut #1
  3. Rotate counter-clockwise until the nut comes off
  4. Put the lug nut in a safe place
  5. Put the lug wrench on nut #2
  6. Rotate counter-clockwise until the nut comes off
  7. Put the lug nut in a safe place
  8. Put the lug wrench on nut #3
  9. Rotate counter-clockwise until the nut comes off
  10. Put the lug nut in a safe place
  11. Put the lug wrench on nut #4
  12. Rotate counter-clockwise until the nut comes off
  13. Put the lug nut in a safe place
  14. Put the lug wrench on nut #5
  15. Rotate counter-clockwise until the nut comes off
  16. Put the lug nut in a safe place
  17. Jack up the car
  18. Remove the flat tire
  19. 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:

  1. Take out jack, lug wrench and spare tire from trunk
  2. For each lugNutNumber
  3. removeLugNut( lugNutNumber)
  4. Jack up the car
  5. Remove the flat tire
  6. 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.

Link:

This post was originally published at Functions and return statements in Corona