'''
 20190915
 R. Dawes
 
 Several examples of how functions work in Python.
'''

print("\n\nExample: double_it")

def double_it(x):
   ''' double the value of the argument and return it '''
   return 2*x

y = double_it(3)
print("the value returned by double_it(3):", double_it(3))
print("the value returned by double_it(double_it(3)):", double_it(double_it(3)))

double_it(3)      # ignoring the return value ...

print("\n\nExample: cube_it_and_print")

def cube_it_and_print(x):
   '''cube the argument and print the result'''
   y = x**3
   print("the cube of", x, "is", y)
   # without a return statement, the function automatically returns "None"
   
cube_it_and_print(7)
z = cube_it_and_print(7)
print("the value returned by cube_it_and_print:", z)

y = 999
print("y before:", y)
cube_it_and_print(8)
print("y after :", y)


print("\n\nExample: smaller_and_larger")

def smaller_and_larger(x, y):
   '''return the smaller and larger of the two arguments''' 
   # this function returns 2 values at the same time
   if x <= y:
      return x, y
   else:
      return y, x
      
small, large = smaller_and_larger(17, 3)
print("small =",small,"\tlarge =", large)


print("\n\nExample: change_parameter_value")

def change_parameter_value(x):
   ''' increment the argument by 1'''
   x = x+1
   print("inside change_parameter_value, x =", x)
   # the parameter's value is changed, but the value of the variable passed to it is not changed
   
x = 5
print("x before:", x)
change_parameter_value(x)
print("x after: ", x)


print("\n\nExample: change_list_content")

def change_list_content(a_list):
   '''append an element and change the value of an element'''
   a_list.append("New Element")
   a_list[1] = "Changed Element"
   #  "a_list" and the list variable passed to it both "point to" the same mutable
   # object in memory.  Modifying that object does not sever those pointers, so it
   # effectively modifies both lists (since they are really just two names for the same
   # object).
   
my_list = list(range(7))
print("my_list before:", my_list)
change_list_content(my_list)
print("my_list after :", my_list)



print("\n\nExample: change entire list")

def change_entire_list(a_list):
   '''assign a new list to the argument'''
   a_list = ["this", "is", "a", "new", "list"]
   # Here we are creating a new list and making "a_list" point to it.  This does NOT
   # make the list variable that was passed to the function point to the new list.  Its
   # value is unchanged.
   
my_list = list(range(7))
print("my_list before:",my_list)
change_entire_list(my_list)
print("my_list after :",my_list)   
   

print("\n\nExample: access a global variable")

def access_global_variable(x):
   '''return the argument plus a global variable'''
   return x + important_number
   # This will work as long as "important_number" is given a value before this
   # function is called

important_number = 42
print("the value returned by access_global_variable: ",access_global_variable(99))


print("\n\nChange a global variable")

def change_global_variable(x):
   '''attempt to assign a new value to  a global variable'''
   important_number = x + 1
   return important_number
   # Python identifies local variables (i.e. ones that are local to a function) by finding all
   # variable names that are on the left side of assignment statements.  In this function
   # "important_number" is identified as a local variable, and any references to it or changes
   # to its value will not affect the global variable that has the same name

important_number = 42
print("important_number before:",important_number)
z = change_global_variable(23)
print("value returned by change_global_variable:",z)
print("important_number after:",important_number)


#~ print("\n\nIncrement a global variable (causes execution error)")

#~ def increment_global_variable(x):
   #~ '''attempt to increment a global variable by value of argument'''
   #~ important_number = important_number + x
   #~ return important_number
   #~ # this causes an execution error because "important_number" is identified as
   #~ # a local variable, and we attempt to use it in "important_number + x" before
   #~ # it has any value

#~ important_number = 42
#~ print("important_number before:",important_number)
#~ z = increment_global_variable(23)
#~ print("value returned by increment_global_variable:",z)
#~ print("important_number after:",important_number)



print("\n\nExample: unspecified number of parameters")

def  return_list_of_evens(*args):
   '''find the even values with any number of arguments '''
   result = []
   for x in args:
      if x % 2 == 0:
         result.append(x)
   return result
   # the "*args" parameter can be used to accept any number of arguments
   
print("Some even numbers:",return_list_of_evens(1, 2, 3, 4, -2, 5, 100, 13, 35, 60))

print("Some more even numbers:",return_list_of_evens(10, 11, 8))

print("The evens in an empty list:",return_list_of_evens())