I've need help understanding what returning is. Can someone please explain?

Return

---

The return statement tells the program to stop executing in it's current environment, and return to where the environment was created, along with passing information if provided. Yeah, you probably have some questions about this:

• What's an "environment"?

  • An environment can be looked at as any scope of code that can be modified with the built-in setfenv (set function environment) function. It's basically just a hidden table of variables that you can access without having to index the environment manually.

• How do I create one?

  • You can't create a whole new environment like the one that stores all the global variables in your program (the global environment), but you can create a function environment. Functions environments are created whenever you initialize a function. For example:

  -- Declare function
  local function x()
      print("New function environment!")
  end
  
  -- Initialize function by calling it for the first time
  x()
  
  -- Calling the function again which re-uses the environment it originally created
  x()
  

Now whenever we call x, it will either create or use the old function environment for that function to store all of it's local variables, and hold on to a return address to resume executing where the code left off when the function was called.

The global environment

---

We now know what a function environment is, but what about the environment you're coding everything in? The global environment? The global environment (or global scope) is where your entire program begins and ends. This is also where global variables are held. For example: x = 10 is a global variable, meaning no matter where it's created, it's available globally in your code (as long as it's declared before something tries to use it). This is opposed to local variables, where you can only use them if you're in a descendant of the local variable's scope. (Example):

-- x is declared in global scope space
local x = "hello world"

-- We create a new scope, where we have access to 'x' because this new scope is a descendant of the globla scope.
do print(x) end

However if we tried to index x outside of it's context, we would get nil, as demonstrated:

-- x is only local to this do-end scope
do local x = "hello world" end

-- x is does not exist outside of it's scope
print(x) --> nil

Aside from local variables only staying true to their scope, local variables are also accessed much quicker in memory, and keep the global environment from getting cluttered with random variables. For such reasons, you should always use local variables, unless explicitly required to do otherwise.

All functions return

---

Functions are very unique. They're not just random blocks of code (i.e, do end, while do ... end, for do ... end, or anything that requires an end statement). Functions are similar, but they need a specific space in memory (called the stack), where it's local variables and return address is held so it knows where to return back to. All functions return to where they were originally called once they're done executing. If no return statement was given, it's automatically evaluated as nil just like everything else that's undefined in Lua. Here's an example:

local function x()
    print("New function environment!")
end

-- Running some code in the global scope...
print("Hello world")

x() -- We called a function, let's stop here and execute the code inside the function, then return back here when it's done.

-- ... and we're back!
print("Goodbye world")

-- Let's see what happens if we try and print out what the function returns:
print( x() ) -- > nil

Because functions always return, we get to decide what it does return if it's deemed necessary. This is probably the most important mechanic functions have, as it allows us to organize our code by doing all the heavy lifting for us and return what we're looking for, with just a simple call. As a small example, say we wanted to create a function that returned the sum of two numbers. Probably to most common example of returning something there is:

-- Function that returns to sum of two numbers
local function add(a, b)
    return a + b -- Return this to where it was called!
end

-- Obviously nothing will happen here, because we're not doing anything with the data we've returned. However, the data was stilled returned to this location. Which means add(5, 10) equals 15, no matter where we use it.
add(5, 10)

-- This means we could use it directly in the print function, to display the result:
print( add(5, 10) ) -- >15

-- Or, we could store what the function returns in a variable, and use that variable whenever we want:

local sum = add(5, 10)
print(sum) -- > 15

As you can see, everything returns back to where it left off once the function terminates. Think about calling a function as sending a package to somebody, and you don't want to do anything until you get something back from that person. You send the package, you wait, and you get another package they sent you with a return address.. Then you can continue about your business.

Oh, and did I mention you can return multiple values at once? Just separate each element with a coma like you would in a table, and it will return everything as an ordered tuple!

local function returnElements(a, b, c)
    return a, b, c, "extra!"
end

local a, b, c, x = returnElements(1, 2, 3)
print(a, b, c, x) --> 1, 2, 3, "extra!"

Just like passing arguments to functions, returning data works in the same order and syntax.

Returning in different scopes

---

It's important to remember that the only environment you're working with is either inside a function, or in the global environment. As mentioned before, blocks of code are not considered new environments. They're simply just a designated area with no address for local variables to stay private in.

For this reason, using return in a code block will not return back to where the code block was created, it will return back to where the environment the scope is inside of was created in. Here's an example demonstrating this:

local function x()
     -- simple do-end block, returning the string "hello"
    do return "hello" end

    -- returns "goodbye" when reached.
    return "goodbye"
end

-- Despite the end of our function returning "goodbye", we get where return was first stated.
print( x() ) -- > "hello"

One may expect do return "hello" end in this context to return back to where do was created, and move on with the rest of the code inside the function. But, since this scope is inside a function environment (x), it stops everything at that point and returns directly to where x itself was called.

Nothing can happen after return

---

Yeah, in the previous example we clearly had two return statements in one function, but they're in different scopes. You can only have one return statement per scope. Anything written to be ran as code after that return statement, is considered a syntax error, and will break. Example:

print("hello") --> hello
return;
print("goodbye") --> Error in script: '<eof>' expected near 'print'

The error message basically just means the scope expected to end where print("goodbye") was written, since we had return right before it.

THE END

---

That was a lot to write. I hope I didn't create more questions than answered, but I do believe you should know most of this in order to have a clear understanding of what return does, with some useful information scattered about relating to it. If you do have any questions though, feel free to ask in a comment or post another question on the site if need be.

return "Goodbye!"

return --anything Gives you anything you want as a final result of a function. If you want a function to do something, you have to return that something.

Say you want a function to give you a word, you have to return the word.

function getWord()
    return "asdf"
end

local word = getWord()
print(word)

Of course returning also exits the function, which is very useful itself, so you often see return alone.

Lets say you wanted to use a function to get a random number but how will you get it from another method?

function example()
return math.random()
end

print("this is where ima run now")
local number = example() --i returned the number so i can use it in the script, method has to be --in script for this
print(number)