In this lesson, we'll learn to write functions that return values. Such functions answer a question and hand back the result of their work, as if to say: "Here you go, I've done the counting".

For example, a function can return a string with processed text, or a number calculated from a formula. The returned value can be used further on. It gets saved in a variable, passed to another function, or printed on the screen.

To make a function hand back a result, it uses the special keyword return. It ends the function and specifies exactly what has to be returned.

Here is an example of a function that turns text into uppercase:

def shout(name):
    return name.upper()

We call shout(), pass a name into it, and get back a string in uppercase. That string is the result of the function.

result = shout("hexlet")
print(result)  # => HEXLET

result2 = shout("code-basics")
print(result2)  # => CODE-BASICS

Unlike print(), return doesn't print anything. It just returns a value. The decision about what to do with it is made by the calling code.

When the function shout("hexlet") is called, the expression name.upper() is evaluated first. It returns the string "HEXLET". Then return hands that value outward, to the place the function was called from. In our case, the value is saved in the variable result and then printed on the screen with print().

Returning a calculated expression

Functions don't have to return a parameter as is. Usually return is given an expression, which is evaluated first, and only then is the result handed outward.

def full_name(first, last):
    return first.capitalize() + " " + last.capitalize()

In this example we assemble a full name from a first name and a last name. First the capitalize() methods are called, then the strings are joined with +, and the finished string is returned.

name = full_name("aria", "stark")
print(name)  # => Aria Stark

Here, in the line return first.capitalize() + " " + last.capitalize(), both method calls are executed first, then the space is added, and only then the result is passed as the return value.

Multi-line functions

Sometimes the body of a function needs several steps before the result is ready. In such cases we write several lines of code and use return at the end to give back the final value.

For example, let's write a function that formats a name: it trims the spaces around the edges and turns all the letters into uppercase.

def format_name(name):
    clean = name.strip()
    uppercased = clean.upper()
    return uppercased

First we remove the spaces with the strip() method, then convert to uppercase with upper(), and return the final value.

print(format_name("  hexlet  "))  # => HEXLET

Code after return

When Python reaches the return statement, the function stops executing. Everything written after it inside the function will not be executed:

def example():
    return "done"
    print("this code will never run")

That's why return is always written at the end of the logic. There can be many such endings inside one function, though. We'll look at that in more detail when we get to conditional expressions.

Finish the function truncate(), which cuts the given string down to the specified number of characters, adds an ellipsis at the end and returns the resulting string. Logic like this is often used on sites to show long text in a shortened form.

The function takes two parameters:

1. The string that has to be cut
2. The number of characters to keep

An example of how the function you write should behave:

# Passing the text directly
# Cutting the text down to 2 characters
truncate("hexlet", 2)  # 'he...'

# Through a variable
text = "it works!"
# Cutting the text down to 4 characters
truncate(text, 4)  # 'it w...'

The task can be solved in several ways; we will hint at just one of them. For that way you need to take a substring of the string passed as the first parameter. Use string slices for this. Based on the task, think about which index you have to extract the substring from and to:

word = "welcome!"
index = 3
word[:index]  # wel