'''
Author: Nadia Hassan (nah3zb)
This document is to summarize various possible functions and clarify confusion regarding functions. :)
'''
# This is a little note page I took while doing OH on functions.

''' FUNCTIONS '''
''' 
Make sure you read this link and study this epistle in its entirety:

http://www.cs.virginia.edu/~cs1112/term/183/resources/epistles/22-functions/

Let's get into functions! 

Functions: units of code that break down a problem so that we can have an easier, cleaner, 
and reusable way for manipulation and calculation of values.

A lot of our CS 1112 functions are just code that we did in Python files 
that are condensed into one definition of a function so that it can perform
the operation (or action) within it each time it is called. Think of them almost like
mini programs that we can use! 

For programs, you need:

- What information is needed upon startup 
    What are our parameters? What types are the parameters? What values are we working with in the function?
- What information it is to produce 
    What do we want to return or print? Sometimes we don't want to return or print anything but rather just manipulate data (that can be passed in through parameters) or in general. 
- Provide an algorithm for going from one to the other
    How do we get from the parameters to the end of the action/function/what we want to return?
    
SO: 
For functions, we almost always tell you what the function takes in and what types and what should be returned.
What this means is MAKE SURE YOU ARE RETURNING EXACTLYYYY WHAT WE WANT YOU TO! 
Ex. If it says "this function returns a list of integers" RETURN A LIST OF INTEGERS 

Think in terms of input/output:
PARAMETERS -> RETURN VALUE/END RESULT

PYTHON FUNCTION SETUP:
----------------------------------------------------------------------
A Python function definition looks like the following: 
    def function-name( parameters ):
        header comment
        action

Indentation is super important. Let me say that again. EVERYTHING YOU WANT THE FUNCTION TO DO SHOULD BE INDENTED INTO YOUR CODE.
Indent Indent Indent!!! 

def means that we are defining a function.

Parameters are the identifiers for the variable names we want to pass in. 
We want to pass in arguments for these parameters when invoking the function.
Meaning: we want to fill in values for the parameters when we call the function.

: is separator for function header from the block of code we write for the function.

The action is just what we want the function to do! 'return' is a keyword we use to return values. 

INVOCATION: 
-----------------------------------------------------------------------
Starting up or calling a function is called an invocation.

We use the following format:

module-name.function_name(arguments)

The module-name is just the file containing the definition of the function!
We use a . to get the function from that module. 

function_name is the function you wanna call/use.

Arguments are the list of values passed into the function based on the parameters the function has in its function definition. 

UNDER THE HOOD / HOW PYTHON IMPLEMENTS FUNCTIONS:

Python checks that the number of invocation arguments passed in matches the number of parameters. 

The activation record stores values of the parameter variables. 
The parameter variables are initialized with the argument values. If a function needs other variables to perform its task, those variables are also stored there.

Once the code is executed and hits a return statement, the value of the expression is determined aka the function returns that something and doesn't keep looking at the rest of the function.


LOCAL VARIABLES:

Parameters and other function variables are collectively called local variables. Local variables only exist during that invocation.
What does this mean?

The value of variables inside your function are only accessible within the scope of that function.
So basically, once the function invocation is over, the values of the local variables are basically reset to what they were initialized to in the function before
you changed them when running the function based on the function.

Ask me for an example if needed! 

'''

''' 
__________________________________________________________________________________________________
I NEED YOU TO LEARN THE FOLLOWING: are you ready are you listening ok

The value of the return expression is the value of the function invocation.
_________________________________________________________________________________________________________________


NOTE: THIS WAS ON PREVIOUS TESTS AS TRUE OR FALSE
Not all functions have parameters! 
Not all functions have to return something! They can just manipulate data or print and be done. 
Not all functions have an explicit return statement, but all functions return something. 
If you use keyword 'return' to return something, it will return that value. Otherwise a function with no return statement returns None. 
All invoked Python functions return a value. If there is no explicit return value supplied, a Python function invocation returns None. 

PRINT IS NOT THE SAME THINGS AS RETURN. 
If I could bold that I would. 
PRINT IS NOT THE SAME THING AS RETURN!!!!!!!!

Print simply prints to the console. 
The value of the return expression is the value of the function invocation. 

If you return a value, it doesn't mean it will print it unless you say to print it inside or outside the function.
I would be careful where you are printing inside your function if you ever do. It is useful when writing the code but often times we will return more than print.

'''

''' LETS ENJOY THESE EXAMPLES I JUST MADE UP IN OFFICE HOURS '''

''' EXAMPLE OF A FUNCTION THAT TAKES IN NO PARAMETERS AND RETURNS AN INT '''
def my_age():
    return 19

# this function takes in no parameters; the name of the function is my_age so that is what I'll call when I INVOKE the function
# this function RETURNS the number 19 does not print it but returns it so the value stored when you set a variable equal to this function invocation is 19

x = my_age() # the value of the variable is whatever the invocation of the function returns WHATEVER THE FUNCTION RETURNS!!! WHAT DOES IT RETURN
print(x) # x has stored the value 19 since it was returned from the function

x1 = 2 # this is just like setting x = 2 and printing it because the
# value of x becomes 19 in the previous example and then you print it
print(x1)

# THINK OF ASSIGNMENT WITH FUNCTION INVOCATIONS

# built in function print WILL PRINT WHATEVER YOU PUT IN IT
# INTO THE CONSOLE RIGHT?


# PRINT RETURNS ABSOLUTELY NOTHING; WHOEVER WROTE PRINT IN
# THE PYTHON LIBRARY DID NOT INCLUDE A RETURN STATEMENT
# What happens you define a function without a return statement?
# If you define a function and do not explicitely state what it returns the function WILL DEFAULT RETURN NONE

x2 = print('cs 1112')
print(x2)
# this prings 'cs 1112' to the console BUTTT when you print x2, what is stored in x2? None since the function print returns None by default!
# so when you print x2 it prints None

# Anatomy of print function (THIS IS NOT THE ACTUAL OR ALGORITHM BUT TO SHOW YOU THAT PRINT DOESNT RETURN ANYTHING)

# def print(whatever i want to print)
    # this is gonna print to the console (action)
    # WHATEVER YOU PUT IN THE PARAMETERS THAT IS NOT BEING RETURNEDDDDDDD NOT RETURNEDDD it will print it to the console solely because that is the action
    # BUT IT RETURNS NONE SINCE THERE WAS NO RETURN STATEMENT

# ACTION AND RETURN ARE TWO PARTS OF THE FUNCTION DEFINITION
# A FUNCTION DOESN'T HAVE TO RETURN SOMETHING BUT IF IT DOESN'T HAVE A RETURN STATEMENT IT RETURNS NONE

# there is no return statement -> no return statement means that the function returns None by default

# what is the value of x2? it is none since print() returns none!

# WHEN I PRINT x2 the reason why is prints both 'cs1112' and 'None' is because it will do whatever is in the function (IT WILL DO THAT ACTION) UPON INVOCATION
# BUT X2 IN THE SECOND PRINT STATEMENT THE VALUE OF x2 IS NONE SINCE IT IS SET TO THE VALUE OF THE FUNCTION INVOCATION NWHICH RETURNS NONE (what does print return?
# SO IT PRINTED OUT 'cs1112' since that's what the function print is supposed to do upon invocation
# and prints out none since that's the value of x2 when you print(x2)


''' EXAMPLE OF FUNCTION THAT TAKES IN A STRING AND RETURNS A STRING '''
def whats_my_name( name_number ):
    if (name_number == 1):
        return "Nadia"
    if (name_number == 2):
        return "Jonathan"
    if (name_number == 3):
        return "Wes"

# def -> this defines a function
# name of the function which is whats_my_name
# we have arguments -> what are the arguments? (the things in the parantheses -> we want to pass in an argument into these parantheses
# the statements within a function is your action

# and we return a string based on the argument passed in

name_i_want = whats_my_name( 3 ) # returns Wes

# what is the value of name_i_want? You know that whats_my_name returns a string based on the argument right? SO if i pass in a 2, RETURNS JONATHAN which means that
# name_i_want stores the value of whatever is returned by that function so if the argument is 2, it will store the string 'Jonathan'

''' WHEN YOU SET A VARIABLE EQUAL TO A FUNCTION INVOCATION THE VALUE STORED IN THAT VARIABLE IS WHATEVER IS RETURNED BY THAT FUNCTION INVOCATION'''
print(name_i_want)

def print_something():
    print('functions') # ACTION
    # NO RETURN STATEMENT so what happens?

# this function returns absolutely nonthing right? WHY? I have no return stateement i dont see return ANYWHEREEE in my block of code for that function

# default returns none

function_call = print_something() # what is gonna happen if I print function call

print(function_call)

# the value stored in function call is NONE BUTTTTTT before that it's gonna run through the function and perform the actions first AKA the print statement
# it's gonna print 'functions' upon invocation BUTTTT it's not gonna return anything because the value stored by that function invocation in function_call is None since there's no return

# You can email me at nah3zb@virginia.edu if you have questions!

''' FUNCTION COMBINATIONS 

Alright let me be real. You can have any possibility of function combinations but here's some I can think of that are common. 

No Parameters, No Return

def func1():
    x = 2 

No Parameters, Return
def func2():
    return 2 

Parameters, No Return (WE USUALLY USE THIS FOR MANIPULATION OF LISTS OR OTHER PARAMETERS WE PASS IN TO CHANGE UP SOMETHING LIKE IN ROTATE BUT IT DOESNT RETURN ANYTHING)
def func3( list ): # takes in a list 
    list.append(3) # appends 3 to the list 

Parameters, Return
def func4( number ): # this can change up data in parameters and return a changed up data
    number = number + 4 
    return number 
'''

''' FINAL THOUGHTS

Remember in testers, we use module.func_name( parameters ) to call a function and you can store the value of what is returned in a variable. 

result = module.func_name( parameters ) so you can store the value of whatever is returned by the function in variable. 

ex:

def func5(number):
    return number + 1 
    
result = module.func5( 5 )

Since the invocation of the function returns 5 + 1 since 5 is the argument passed in , 6 is the evaluation value and that value is stored in result so you can use it. 
That's basically it! 

'''

''' ASK ME TO GO OVER TEST FUNCTIONS OR OLD CLASS EXAMPLES IF NEEDED

Happy studying and good luck! :)

- Nadia 


'''