Merge pull request #28 from csalmeida/return

Return

Author: csalmeida

README.md

@@ -46,6 +46,7 @@ Introduction to core features of the [Ruby](https://www.ruby-lang.org) programmi
   - [Define and Call Methods](#define-and-call-methods)
   - [Variable Scope](#variable-scope)
   - [Arguments](#arguments)
+  - [Return](#return)
 </details>
 
 # Getting Started
@@ -1640,4 +1641,67 @@ end
 
 puts welcome("It's you,", welcome_options); # It's you, Geralt...
 puts welcome("Hello"); # Hello friend!
+```
+
+## Return
+
+Methods return values, and in Ruby the last operation's value in the code block is the one returned by default. For instance, in the example below, `y + z` is the value returned:
+
+```ruby
+def custom_method(x,y,z)
+  x + y
+  z + x
+  y + z
+end
+```
+
+The last operation's value is the one returned. This can lead to pitfalls in cases where conditionals take place:
+
+```ruby
+# custom-methods/return.rb
+def subtract(number_1, number_2)
+  result = number_1 - number_2
+  result = 0 if result < 5
+end
+
+puts subtract(8, 3) # nil
+```
+
+It is not required in Ruby for the `return` keyword to be used in the last line of the method. In some cases, a return value might be required to be declared explicitly. This can be done with the `return` keyword and it can be useful whe applying `if` statements and loops and there's the need to return early.
+
+```ruby
+# custom-methods/return.rb
+def greet_again(cool = false)
+  if cool
+    return greeting = "Yo"
+  end
+  greeting = "Hello"
+end
+
+cool = true
+puts greet_again(cool)
+```
+
+Additionally, `puts` and `print` should be avoided in most methods as it makes them more flexible. The return value can be assigned to a variable or interpolated into a string.
+
+It is recommended to have separate methods to make calculations and another for output.
+
+### Return Multiple Values
+
+Methods are able to return only one object. If more than one value needs to be returned, they need to be stored in an object enumerable like a `hash` or an `array`.
+
+```ruby
+# custom-methods/return.rb
+def add_and_subtract(number_1, number_2)
+  add = number_1 + number_2
+  subtract = number_1 - number_2
+  [add, subtract]
+end
+```
+
+Furthermore the values can be assigned to variables using Ruby's multitple assignment feature. It takes array values and assign them to each variable:
+
+```ruby
+add_result, sub_result = add_and_subtract(15,2)
+puts "Addition result was #{add_result} whilst subtraction was #{sub_result}."
 ```

custom-methods/return.rb

@@ -0,0 +1,54 @@
+#!usr/bin/env ruby
+
+# The last operation's statement is returned.
+# In this case, "Hey".
+def greet
+  greeting = "Hi"
+  greeting = "Yo"
+  greeting = "Hey"
+end
+
+puts greet
+
+# The return value can be explicitly declared as needed.
+def greet_again(cool = false)
+  if cool
+    return greeting = "Yo"
+  end
+  greeting = "Hello"
+end
+
+cool = true
+puts greet_again(cool)
+
+# The last statement has a conditional 
+# that when it is not met returns nil.
+# This can lead to unexpected behaviour.
+def subtract(number_1, number_2)
+  result = number_1 - number_2
+  result = 0 if result < 5
+end
+
+# The return value might be nil
+puts subtract(8, 3).class
+
+# To avoid unexpected behaviour if condition is not met,
+# The value might be specified again to make sure it returns correctly.
+def add(number_1, number_2)
+  result = number_1 + number_2
+  result = 0 if result < 5
+  result
+end
+
+puts add(8, 3)
+
+# Multiple values can be returned in an array or hash.
+def add_and_subtract(number_1, number_2)
+  add = number_1 + number_2
+  subtract = number_1 - number_2
+  [add, subtract]
+end
+
+# Multiple assignment can be used to take values out of an array and assign them to variables.
+add_result, sub_result = add_and_subtract(15,2)
+puts "Addition result was #{add_result} whilst subtraction was #{sub_result}."