# Filename: design.txt
# Author:   Sue Evans
# Date:     4/18/10
# Email:    bogar@cs.umbc.edu
# Section:  01 & 08
#
# World Traveler is a conversion program that allows the user to convert from 
# European times to EST, convert currencies, and convert celsius to fahrenheit 
# temperatures.


Algorithm Design:

I.   The greeting is displayed to the user by a call to printGreeting()
II.  The main menu is displayed by a call to displayMainMenu()
III. The user chooses a menu option by a call to getValidInt(), which is passed
     "Your choice:" as the question, TIME as min, and QUIT as max.
IV.  A conditional on the value of choice does one of the following:
     A. If the user chose TIME, the convertTime() function is called
        1. A menu of cities is shown to the user by a call to displayLocationsMenu()
        2. A European time is gotten from the user by calling getValidTime() which
           returns an hour in 24-hr format and a minute.
           a. The hour, in 24-hr format, is gotten from the user by a call to 
           getValidInt()
	   b. The minute is gotten from the user by a call to getValidInt()
        3. The hour and the appropriate time adjustment for the location is passed
           to the function foreignTimeToEastern() which calculates the estHour and
           returns the estHour in 12-hr format and the abbreviation AM or PM
        4. The original European time is displayed as well as the EST
     B. If the user chose CURRENCY, the convertCurrency() function is called
        1. A menu of cities is shown to the user by calling displayLocationsMenu()
        2. A European amount is gotten from the user by calling getPositiveReal() 
           which returns a positive amount.
        3. The amount and the appropriate currency conversion for the location is 
           passed to the function foreignToDollars() which calculates the usd 
           (US dollars) and returns it.
        4. The original European ammount is displayed as well as the usd
     C. If the user chose TEMP, the function convertTemp() is called
        1. The user is asked for a celsius temperature
        2. celsius is passed to the celsiusToFahrenheit() function which calculates
           the fahrenheit temperature and returns it to convertTemp()
        3. The original celsius temperature is displayed as well as the fahrenheit
           temperature.
     D. If the user chose QUIT, the program exits
     E. If the user chose some other integer, an error message should be shown.
V.   While the user has not chosen QUIT, the program repeats parts II - IV.

___________________________________________________________________________________

           
Constants:

TIME = 1
CURRENCY = 2
TEMPERATURE = 3
QUIT = 4

LONDON_HRS = 5
STOCKHOLM_HRS = 6
TAMPERE_HRS = 7
HELSINKI_HRS = 7
ST_PETE_HRS = 8

POUNDS = 1.53730 
KRONORS = 0.139083 
EUROS = 1.34960
RUBLES = 0.0343348

Additional constants could be added for travel to other countries 
without breaking the program.

___________________________________________________________________________________


Functions:

# printGreeting()
# displays a greeting & explanation of the program to the user
# Inputs:  None
# Outputs: None
def printGreeting():

# displayMainMenu() 
# displays the main menu choices
# Inputs:  None
# Outputs: None
def displayMainMenu():

# displayLocationsMenu()
# displays the location menu choices
# Inputs:  None
# Outputs: None
def displayLocationsMenu():

# convertTime()
# a high level function that handles all of the user input, processing, and 
# output dealing with converting time.
# Inputs:  None
# Outputs: None
def convertTime():
        
# convertCurrency()
# a high level function that handles all of the user input, processing, and 
# output dealing with converting currency.
# Inputs:  None
# Outputs: None
def convertCurrency():

# convertTemp()
# a high level function that handles all of the user input, processing, and 
# output dealing with converting temperature.
# Inputs:  None
# Outputs: None
def convertTemp():

# foreignTimeToEastern()
# changes the hour (in 24-hour format) passed in by the amount of the adjustment 
# yeilding Eastern Standard Time in 12-hour form with the appropriate AM or PM 
# abbreviation 
# Inputs:  hour, the foreign hour
#          adjustment, the appropriate conversion constant for the location
# Outputs: estHour, the Eastern Standard Time hour in 12-hr format
#          abbrev, either AM or PM 
def foreignTimeToEastern (hour, adjustment):
        
# foreignToDollars()
# accepts the number of units of a foreign currency and a conversion factor and 
# returns the equivalent number of US dollars.
# Inputs:  amount, the foreign amount
#          conv, the appropriate conversion constant for the currency
# Outputs: US dollars
def foreignToDollars(units, conv):

# celsiusToFahrenheit()
# returns the fahrenheit equivalent of the celsius temperature passed in.
# Inputs:  celsius, the celsius temperature 
# Outputs: fahrenheit, the equivalent fahrenheit temperature
def celsiusToFahrenheit(celsius):
        
# getValidTime()
# returns a time between 00:00 and 23:59, inclusive, as an hour, minute tuple.
# Inputs:  None
# Outputs: hour, in 24-hr format
#          minute
def getValidTime():

# getValidInt()
# prompts the user and gets an integer from the user between min and max, inclusive 
# and returns that valid integer.
# Inputs:  prompt, the question to be used as the prompt
#          min, the minimum acceptable integer value
#          max, the maximum acceptable integer value
# Outputs: an integer value in the range of min & max, inclusive
getValidInt(question, min, max):

# getPositiveReal() 
# prompts the user and returns a positive float
# Inputs:  question, the question to be used as the prompt
# Outputs: a positive float
def getPositiveReal(question):