[TOPIC: topicViewTemplate]
[GLOBAL: userSmallPhoto]

## From The Blog: Functions and return statements in Corona Started by CoronaBot Sep 13 2019 11:19 AM

No replies to this topic
[TOPIC CONTROLS]
[/TOPIC CONTROLS]
[modOptionsDropdown]
[/modOptionsDropdown]
[reputationFilter]
[TOPIC: post.html]
#1

### CoronaBot

[GLOBAL: userInfoPane.html]
CoronaBot
• Contributor

• 430 posts
• Corona Staff

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

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.