#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Felix Muzny
10/7/2022
DS 2000
Lecture 9 - functions

Logistics:
    - HW 4 is due on *Tuesday* at 9pm
    -> no late submissions will be accepted
    -> example from last Friday 
    (https://course.ccs.neu.edu/ds2000/felix_lectures/analyze_dists.py)
        is particularly relevant
    -> today's example will be more advanced than you need for HW 4
        (you do not need to write functions)
       
    - No office hours from Sat - Mon (Monday is a holiday)
    
  
    - remote attendance (https://bit.ly/remote-ds2000-muzny)
    
 Three ways to participate (please do one of these!)
 1) via the PollEverywhere website: https://pollev.com/muzny
 2) via text: text "muzny" to the number 22333 to join the session
 3) via Poll Everywhere app (available for iOS or Android)
    

Warm-up 1 - functions 1
---

What is a better name for this function?

"""
def mystery(x):
    y = x * x
    return y

"""
A. fancy_math
B. multiply
C. square <---
D. power 
E. lightning_bolts


Warm-up 2 - functions 2
---
What is the *best* option to call this function?

"""
def mystery(x):
    y = x * x
    # return says:
    # 1) stop running this function
    # 2) return/send back the value indicated
    return y
"""

A. mystery("3") [passes in a string]
B. mystery(9)   [doesn't save the return value or display it]
C. result = mystery(input("number? ")) [passes in a string]
D. result = mystery(7.2) <--- we like this!
E. print(mystery(-5)) <--- we like this!
"""



"""
functions: syntax reminders
---
(Deitel & Deitel 4.2)

def function_name(parameters, separated, by, commas):
    # code
    return value
    
# to call the function
answer = function_name(values, matching, in, number)

Notes about parameters:
    - the first value passed to the function is always
    assigned to the first parameter
    - the second value passed to the function is always
    assigned to the second parameter
"""
print("parameter examples")

def greet(name, age):
    # name = first value passed
    # age = second value passed
    print("hello", name)
    print("you are:", age)
    print("in ten years you will be", age + 10)
    # if your function has no return statement
    # python will add the following at the end
    # return None
    
greet("Felix", 31)
# the first value is 33, gets assigned to name in
# the greet function
# the second value is Dylan, gets assigned to age in
# the greet function
# greet(33, "Dylan")


"""
Scope
---
(Deitel & Deitel 4.13)

scope: where can the program access which 
        variables/functions
        
- variables only "live" inside the functions
that they were declared in
    
(We'll do more examples of this next week)
"""

# constants are accessible everywhere
# they "live" in the whole program
# no functions should attempt to change their
# values
PI = 3.14159

# scope examples
def power(num, exp):
    # num is specific to power
    # so is exp
    
    # name only lives in main
    # print(name)
    
    # PI is accessible
    print(PI)
    
    # answer only lives inside of power
    answer = num ** exp
    # this returns the value of the 
    # variable answer
    return answer

def main():
    
    name = "Felix"
    
    # result is a new variable that lives
    # inside main and stores the value
    # returned by the power function
    result = power(2, 5)
    
    # num and answer only live in power
    # print(num)
    # print(answer)
    
    # PI is accessible
    print(PI)

main()


"""
Function comments
---
Your programs should have three kinds of comments:
    - header comment (Name, date, one-two sent. description of 
                      the program)
    - in line comments (clarify complex code, help label chunks 
                        of code)
    - function comments (description, parameters, return)
    
"""
def square(x):
    """
    Calculates the given number rasied to the 2nd power.

    Parameters
    ----------
    x : number (int or float)
        Value to be squared.

    Returns
    -------
    squared : number
        the calculated square
    """
    
    squared = x * x
    return squared


"""
Structuring your programs
---
Programs for this class will always be in the order:

top
# header comment

# imports

# constants

# non-main functions

# main

# call your main
bottom
"""



"""
main()
---
Your main function should read as the "table of contents" of 
your program. 

You don't want any one function to do everything.
You always want program flow to return to main().

Remember: each function should do one thing and do it well!
    -> normally this means that your function is doing
    one of three things:
        1) Reading in data
        2) Doing a calculation or data manipulation
        3) Displaying results (graphing or printing)
"""


"""
Example program
---

Write a program, earnings.py, that reads the data from the given earnings 
data file and calculates the average salary earned by city employees from
2011 to 2021.

Here is the small data file. The large data file follows the same format.
Columns are in the order: title,salary,overtime

Police Officer,,
Police Officer,,
Police Offc Comm Serv Offc 3$8,69772.1,82300.87
Police Officer,100963.38,67849.66
Police Offc Comm Serv Offc 3$8,109858.02,75938.65
Police Sergeant (Det),127626.76,66433.83
Police Lieutenant (Det),142466.41,167509.61
Police Lieutenant,143566.78,109101.43
Police Detective,107352.54,76434.46

(The data comes from here, originally:
 https://data.boston.gov/dataset/employee-earnings-report)
"""


"""
Next time:
    - data: where does it come from?
    - more on scope
    - lists + mutation
    - two dimensional lists
    - two dimensional lists + csv files
"""