''' Purpose: introduce modules. the module defines two functions add() and
             negate().  they are available to other python files that
             import harb.py
'''

# Harb is a module (a library that contains function definitions!)
# Inger is a program (essentially a program that runs these functions from harb)
# You need to ensure that the module and program that uses functions from the module are in the same folder!
# You import harb in inger.py to call functions like this: harb.function_name( arguments )
def add( a, b ) :              # function named add(), parameters named a and b
   ''' Returns value of a + b
   '''

   result = a + b              # compute value of interest

   # print( 'result:', result )
   return result               # function hands back its result

# a, b, and result are local variables ^
# They only exist in the scope of the function!

   # If there's no return statement, Python default returns None for the function.
   # IMPORTANT ^^^ WRITE THIS DOWN ^^^ IF YOU GET NONE FOR A FUNCTION THAT IS SUPPOSED TO RETURN
   # YOU ARE PROBABLY NOT RETURNING A VALUE

   # PRINT IS NOT THE SAME AS RETURN PRINT IS NOT THE SAME AS RETURN PRINT IS NOT THE SAME AS RETURN
   # print() just prints it to the console
   # return is the value that the function hands back so you can store the return value in a
   # variable in a function call
   # print() just displays something to the console
   # return actually hands back a value to be used from the function when you execute the function!

   # another_result = a * b   # This code is unreachable! (Since it's after a return statement)

# If n1 and n2 are 3 and 14 in inger.py and we call the function like so:
# t1 = harb.add(n1,n2)
# The parameter a gets the argument n1 (3) and parameter b gets the argument n2 (14)
# Since we return a + b in the function, t1 stores the return value of the function (which returns a + b)
# So t1 will store the return value 17

# IMPORTANT: As soon as you hit a return statement in Python functions, it will NOT
# look at the rest of the code - the function is DONE.

# Arguments fill in parameters in the order of the parameters.
def negate( x ) :              # function named negate(), parameter named x
   ''' Returns inverse of x
   '''

   result = -x                 # compute value of interest

   return result               # function hands back the inverse