1. User-Defined Functions & Subroutines Part 2 Outline

Transcription

1 User-Defined Functions Subroutines Part 2 Outline 1. User-Defined Functions Subroutines Part 2 Outline 2. Argument Order When Passing Arrays 3. Code Reuse Is GOOD GOOD GOOD 4. Reusing User-Defined Functions via the INCLUDE Statement 5. The Meaning of the INCLUDE Statement 6. INCLUDE Statement Example #1 7. INCLUDE Statement Example #2 8. Example #2 Without INCLUDE Statement 9. Actual Arguments vs. Formal Arguments 10. Argument Order 11. Argument Order Within the Function Is Arbitrary 12. The Order in the Argument List in the Function Definition Needn t Match the Order in the Argument Declaration in the Function Definition 13. Argument Order of Function Definition MUST EXACTLY MATCH Argument Order of Function Call 14. Argument Order Conventions: Pick One and Stick to It 15. Side Effects 16. Side Effects Example 17. A Function That Doesn t Return a Value 18. Subroutines 19. Subroutine Call Example 20. Subroutine Call Example Runs 21. Why Do We Like Code Reuse?/ Why Do We Like User-Defined Procedures? See Programming in Fortran 90/95, 1st or 2nd edition, Chapters Argument Order When Passing Arrays REAL FUNCTION mean (array, REAL,DIMENSION(, INTENT(IN) :: array... END FUNCTION mean When we pass an array to a function as an argument, we also need to pass its length, because the declared length of the array in the main program (that is, in the array s DIMENSION attribute) is not automatically known by the function. When passing an array as a function argument and therefore passing the length of the array as well it does not matter what order the formal arguments appear in the function s formal argument list. (It matters very much, however, that the order of the formal arguments in the function s formal argument list exactly match the order of the actual arguments in the function call.) Inside the function definition, the order of the formal argument declarations MATTERS A LOT. Specifically, the length argument MUST be declared BEFORE the array argument whose length it specifies. Then, in the declaration of the array argument, the length in the array s DIMENSION attribute will be the length argument. IMPORTANT NOTE: the length argument MUST be an INTEGER. 2

2 Code Reuse Is GOOD GOOD GOOD We like to make our programming experiences reasonably efficient. Often, we find ourselves doing a particular task the same way in many different contexts. It doesn t make sense, from a software development point of view, to have to type in the same piece of source code over and over and over. So, in solving a new problem that is, in writing a new program we want to be able to reuse as much existing source code as we possibly can. Not surprisingly, this is called code reuse. Code reuse is GOOD GOOD GOOD. It makes us happy as programmers, because: 1. we can get to the solution of a new problem much more quickly; 2. we can thoroughly test and debug a piece of source code that does a common, well-defined task, and then be confident that it will work well in a new context. Reusing User-Defined Functions via the INCLUDE Statement In the two example programs at the end of the previous slide packet, we saw two copies of the function definition for cube root, and these two copies were character-for-character identical. It d be a big waste of time to have to type the exact same function definition over and over and over if we wanted to use it multiple times, especially if our function definition was, say, 100 lines long (which is not at all unreasonable). So, Fortran 90 allows us to put the function in a completely separate Fortran 90 source file, and to include it when we re compiling, by using an INCLUDE statement. The general form of the INCLUDE statement is: or: For example: INCLUDE "filename" INCLUDE filename INCLUDE "cube root.f90" What does this mean? 3 4

3 The Meaning of the INCLUDE Statement When the compiler encounters an INCLUDE statement, it brings the contents of the included source file into the primary source file that it s currently compiling. So, the upshot is that the compiler ends up treating the primary source file exactly as if you had typed the contents of the included file into it, in the place where the INCLUDE statement is. This promotes code reuse. INCLUDE Statement Example #1 % cat cube_root_scalarinc.f90 PROGRAM cube_root_scalar INTEGER,PARAMETER :: number_of_values = 3 REAL :: input_value1, cube_root_value1 REAL :: input_value2, cube_root_value2 REAL :: input_value3, cube_root_value3 REAL,EXTERNAL :: cube_root! Function return type PRINT *, "What ", number_of_values, " real numbers would you like ", "the cube roots of?" READ *, input_value1, input_value2, input_value3 cube_root_value1 = cube_root(input_value1) cube_root_value2 = cube_root(input_value2) cube_root_value3 = cube_root(input_value3) PRINT *, "The cube root of ", input_value1, " is ", cube_root_value1, "." PRINT *, "The cube root of ", input_value2, " is ", cube_root_value2, "." PRINT *, "The cube root of ", input_value3, " is ", cube_root_value3, "." END PROGRAM cube_root_scalar INCLUDE "cube_root.f90"!! NOTICE NOTICE NOTICE % cat cube_root.f90 REAL FUNCTION cube_root (original_value) REAL,INTENT(IN) :: original_value REAL,PARAMETER :: cube_root_power = 1.0 / 3.0 cube_root = original_value ** cube_root_power END FUNCTION cube_root % f95 -o cube_root_scalarinc cube_root_scalarinc.f90 % cube_root_scalarinc What 3 real numbers would you like the cube roots of? The cube root of is The cube root of is The cube root of E+02 is

4 INCLUDE Statement Example #2 % cat cube_root_arrayinc.f90 PROGRAM cube_root_array INTEGER,PARAMETER :: first_input = 1 INTEGER,PARAMETER :: number_of_inputs = 5 REAL,DIMENSION(number_of_inputs) :: input_value, cube_root_value INTEGER :: index REAL,EXTERNAL :: cube_root PRINT *, "What ", number_of_inputs, " real numbers" PRINT *, " would you like the cube roots of?" READ *, (input_value(index), index = first_input, number_of_inputs) DO index = first_input, number_of_inputs cube_root_value(index) = cube_root(input_value(index)) END DO!! index = first_input, number_of_inputs DO index = first_input, number_of_inputs PRINT *, "The cube root of ", input_value(index), " is ", cube_root_value(index), "." END DO!! index = first_input, number_of_inputs END PROGRAM cube_root_array INCLUDE "cube_root.f90" % cat cube_root.f90 REAL FUNCTION cube_root (original_value) REAL,INTENT(IN) :: original_value REAL,PARAMETER :: cube_root_power = 1.0 / 3.0 cube_root = original_value ** cube_root_power END FUNCTION cube_root % f95 -o cube_root_arrayinc cube_root_arrayinc.f90 % cube_root_arrayinc What 5 real numbers would you like the cube roots of? The cube root of is The cube root of is The cube root of E+02 is The cube root of E+02 is The cube root of E+02 is Example #2 Without INCLUDE Statement % cat cube_root_array.f90 PROGRAM cube_root_array INTEGER,PARAMETER :: first_input = 1 INTEGER,PARAMETER :: number_of_inputs = 5 REAL,DIMENSION(number_of_inputs) :: input_value, cube_root_value INTEGER :: index REAL,EXTERNAL :: cube_root PRINT *, "What ", number_of_inputs, " real numbers" PRINT *, " would you like the cube roots of?" READ *, (input_value(index), index = first_input, number_of_inputs) DO index = first_input, number_of_inputs cube_root_value(index) = cube_root(input_value(index)) END DO!! index = first_input, number_of_inputs DO index = first_input, number_of_inputs PRINT *, "The cube root of ", input_value(index), " is ", cube_root_value(index), "." END DO!! index = first_input, number_of_inputs END PROGRAM cube_root_array REAL FUNCTION cube_root (original_value) REAL,INTENT(IN) :: original_value REAL,PARAMETER :: cube_root_power = 1.0 / 3.0 cube_root = original_value ** cube_root_power END FUNCTION cube_root % f95 -o cube_root_array cube_root_array.f90 % cube_root_array What 5 real numbers would you like the cube roots of? The cube root of is The cube root of is The cube root of E+02 is The cube root of E+02 is The cube root of E+02 is

5 Actual Arguments vs. Formal Arguments In our cube root examples, we ve seen function calls that look like this: We say that cube root value1 = cube root(input value1) this assignment statement calls the user-defined function cube root using as its actual argument the variable input value1 which corresponds to the function definition s formal argument original value and returns the cube root of the value of stored in the variable input value1. The actual argument is the argument that appears in the call to the function (for example, in the main program). The formal argument which in Fortran 90 is also called the dummy argument is the argument that appears in the definition of the function. Argument Order Suppose that a function has multiple arguments. Does their order matter? No, no, yes and yes. No, in the sense that the order of arguments in the function definition is arbitrary. No, in the sense that the order of arguments in the function definition does not have to match the order of argument declarations in the function definition. Yes, in the sense that the order of the formal arguments in the function definition must EXACTLY MATCH the order of the actual arguments in the function call. Yes, in the sense that it s a good idea to set a convention for how you re going to order your arguments, and then to stick to that convention. Not surprisingly, the mathematical case is the same. In a mathematical function definition like if we want the value of then is the formal argument of the function argument., and is the actual 9 10

6 Argument Order Within the Function Is Arbitrary REAL FUNCTION mean (array, REAL,DIMENSION(, INTENT(IN) :: array REAL, PARAMETER :: initial_sum = 0.0 INTEGER,PARAMETER :: minimum_number_of_elements = 1 REAL :: sum INTEGER :: element IF (number_of_elements < minimum_ THEN PRINT *, "ERROR: can t have an array ", "of length ", number_of_elements, ":" PRINT *, " it must have at least ", minimum_number_of_elements, " element." END IF!! (number_of_elements < min...) sum = initial_sum DO element = first_element, number_of_elements sum = sum + array(element) END DO!! element = first_element, number_of_elements mean = sum / number_of_elements END FUNCTION mean REAL FUNCTION mean (number_of_elements, array)!! <-- NOTICE! REAL,DIMENSION(, INTENT(IN) :: array REAL, PARAMETER :: initial_sum = 0.0 INTEGER,PARAMETER :: minimum_number_of_elements = 1 REAL :: sum INTEGER :: element IF (number_of_elements < minimum_ THEN PRINT *, "ERROR: can t have an array ", "of length ", number_of_elements, ":" PRINT *, " it must have at least ", minimum_number_of_elements, " element." END IF!! (number_of_elements < min...) sum = initial_sum DO element = first_element, number_of_elements sum = sum + array(element) END DO!! element = first_element, number_of_elements mean = sum / number_of_elements END FUNCTION mean The Order in the Argument List in the Function Definition Needn t Match the Order of Argument Declarations in the Function Definition REAL FUNCTION mean (array, REAL,DIMENSION(, INTENT(IN) :: array REAL, PARAMETER :: initial_sum = 0.0 INTEGER,PARAMETER :: minimum_number_of_elements = 1 REAL :: sum INTEGER :: element IF (number_of_elements < minimum_ THEN PRINT *, "ERROR: can t have an array ", "of length ", number_of_elements, ":" PRINT *, " it must have at least ", minimum_number_of_elements, " element." END IF!! (number_of_elements < min...) sum = initial_sum DO element = first_element, number_of_elements sum = sum + array(element) END DO!! element = first_element, number_of_elements mean = sum / number_of_elements END FUNCTION mean 11 12

7 Argument Order of Function Definition MUST EXACTLY MATCH Argument Order of Function Call % cat meanfunctestrevarg.f90 PROGRAM mean_function_test... input_mean = mean(input_value,... END PROGRAM mean_function_test REAL FUNCTION mean (number_of_elements, array)!! <-- NOTICE! REAL,DIMENSION(, INTENT(IN) :: array REAL, PARAMETER :: initial_sum = 0.0 INTEGER,PARAMETER :: minimum_number_of_elements = 1 REAL :: sum INTEGER :: element IF (number_of_elements < minimum_ THEN PRINT *, "ERROR: can t have an array ", "of length ", number_of_elements, ":" PRINT *, " it must have at least ", minimum_number_of_elements, " element." END IF!! (number_of_elements < min...) sum = initial_sum DO element = first_element, number_of_elements sum = sum + array(element) END DO!! element = first_element, number_of_elements mean = sum / number_of_elements END FUNCTION mean % f95 -o meanfunctestrevarg meanfunctestrevarg.f90 Error: meanfunctestrevarg.f90: Argument NUMBER_OF_ELEMENTS (no. 1) in reference to MEAN from MEAN_FUNCTION_TEST has the wrong data type Error: meanfunctestrevarg.f90: Argument ARRAY (no. 2) in reference to MEAN from MEAN_FUNCTION_TEST has the wrong data type [f95 error termination] Argument Order Conventions: Pick One and Stick to It In general, it s good practice to pick a convention for how you will order your argument lists, and to stick with that convention. The reason for this is that, as you develop your program, you ll jump around a lot from place to place in the program, and you ll forget what you did in the other parts of the program. So, pick an argument order convention and stick to it. Here s an example: 1. all arrays with INTENT(OUT), in alphabetical order, and then 2. all arrays with INTENT(IN), in alphabetical order, and then 3. all lengths of arrays with INTENT(OUT), in the same order as those arrays, and then 4. all lengths of arrays with INTENT(IN), in the same order as those arrays, and then 5. all non-length scalars, in alphabetical order. Given this convention: when you define a new function, you know what order to use in the function definition; when you call a function that you ve defined, you know what order to use in the function call

8 Side Effects A side effect of a function is something that the function does other than calculate and return its return value, and that affects something other than the values of local variables. For example, consider this function: INTEGER FUNCTION input_number_of_elements () INTEGER,PARAMETER :: minimum_number_of_elements = 1 PRINT *, "" PRINT *, " the array to have (at least ", minimum_number_of_elements, ")?" READ *, input_number_of_elements IF (input_number_of_elements < minimum_ THEN PRINT *, "Too few, idiot!" END IF!! (input_number_of_elements <... ) END FUNCTION input_number_of_elements This function has the side effect of outputting a prompt message to the user, as well as of idiotproofing (i.e., outputting an error message and terminating if needed). Side Effects Example % cat userarray.f90 PROGRAM user_array_test INTEGER,PARAMETER :: allocate_success = 0 REAL,DIMENSION(:),ALLOCATABLE :: element INTEGER :: number_of_elements INTEGER :: allocate_status INTEGER,EXTERNAL :: input_number_of_elements number_of_elements = input_number_of_elements() PRINT *, "The number of elements that you ", "plan to input is ", number_of_elements, "." ALLOCATE(element(, STAT=allocate_status) IF (allocate_status /= allocate_success) THEN PRINT *, "ERROR: couldn t allocate the ", "array named element" PRINT *, " of ", number_of_elements, " elements." END IF!! (allocate_status /= allocate_success) END PROGRAM user_array_test INCLUDE "inputnumelts.f90" % cat inputnumelts.f90 INTEGER FUNCTION input_number_of_elements () INTEGER,PARAMETER :: minimum_number_of_elements = 1 PRINT *, "" PRINT *, " the array to have (at least ", minimum_number_of_elements, ")?" READ *, input_number_of_elements IF (input_number_of_elements < minimum_ THEN PRINT *, "Too few, idiot!" END IF!! (input_number_of_elements <... ) END FUNCTION input_number_of_elements f95 -o userarray userarray.f90 % userarray 0 Too few, idiot! % userarray 10 The number of elements that you plan to input is 10. % userarray The number of elements that you plan to input is ERROR: couldn t allocate the array named element of elements

9 A Function That Doesn t Return a Value Suppose we wanted, for example, to read values into an array of a specified length. We might define a function like so: INTEGER FUNCTION input_elements (element, REAL,DIMENSION(, INTENT(OUT) :: element INTEGER :: index PRINT *, "What are the ", number_of_elements, " elements of the array?" READ *, (element(index), index = first_element, input_elements =??? END FUNCTION input_elements What on earth are we going to return? The best answer is, we re not going to return anything. But if we re not returning anything, then it s not a function. So, we have a special construct in case we don t want to return anything: a subroutine. Subroutines A subroutine is exactly like a function, except that: 1. The keyword FUNCTION is replaced by the keyword SUBROUTINE. So, the subroutine has a SUBROUTINE statement and an END SUBROUTINE statement, which are analogous to a function s FUNCTION statement and END FUNCTION statement. 2. A subroutine has no return type and no return variable. SUBROUTINE input_elements (element, REAL,DIMENSION(, INTENT(OUT) :: element INTEGER :: index PRINT *, "What are the ", number_of_elements, " elements of the array?" READ *, (element(index), index = first_element, END SUBROUTINE input_elements A subroutine is invoked using a CALL statement (e.g., in the main program): CALL input_elements(project1_score, number_of_students) Notice that a subroutine has to have side effects to be useful. The general term for functions and subroutines is procedure. That is, a procedure is either a function or a subroutine

10 Subroutine Call Example % cat userarray2.f90 PROGRAM user_array_test2 INTEGER,PARAMETER :: allocate_success = 0 REAL,DIMENSION(:),ALLOCATABLE :: element INTEGER :: number_of_elements INTEGER :: allocate_status, index INTEGER,EXTERNAL :: input_number_of_elements number_of_elements = input_number_of_elements() PRINT *, "The number of elements that you ", "plan to input is ", number_of_elements, "." ALLOCATE(element(, STAT=allocate_status) IF (allocate_status /= allocate_success) THEN PRINT *, "ERROR: couldn t allocate the ", "array named element" PRINT *, " of ", number_of_elements, " elements." END IF!! (allocate_status /= allocate_success) CALL input_elements(element, PRINT *, "The ", number_of_elements, " elements are:" PRINT *, (element(index), index = first_element, END PROGRAM user_array_test2 INCLUDE "inputnumelts.f90" INCLUDE "inputarray.f90" % cat inputnumelts.f90 INTEGER FUNCTION input_number_of_elements () INTEGER,PARAMETER :: minimum_number_of_elements = 1 PRINT *, "" PRINT *, " the array to have (at least ", minimum_number_of_elements, ")?" READ *, input_number_of_elements IF (input_number_of_elements < minimum_ THEN PRINT *, "Too few, idiot!" END IF!! (input_number_of_elements <... ) END FUNCTION input_number_of_elements % cat inputarray.f90 SUBROUTINE input_elements (element, REAL,DIMENSION(, INTENT(OUT) :: element INTEGER :: index PRINT *, "What are the ", number_of_elements, " elements of the array?" READ *, (element(index), index = first_element, END SUBROUTINE input_elements Subroutine Call Example Runs % f95 -o userarray2 userarray2.f90 % userarray2 0 Too few, idiot! % userarray The number of elements that you plan to input is ERROR: couldn t allocate the array named element of elements. % userarray2 3 The number of elements that you plan to input is 3. What are the 3 elements of the array? The 3 elements are:

11 Why Do We Like Code Reuse? 1. Bug avoidance: Since we don t have to retype the procedure from scratch every time we use it, we aren t constantly making new and exciting typos. 2. Implementation efficiency: We aren t wasting valuable programming time ($8 - $100s per programmer per hour) on writing commonly used procedures from scratch. 3. Verification: We can test a procedure under every conceivable case, so that we re confident that it works, and then we don t have to worry about whether the procedure has bugs when we use it in a new program. Why Do We Like User-Defined Procedures? 1. Code Reuse (see above) 2. Encapsulation: We can write a procedure that packages an important concept (e.g., the cube root). That way, we don t have to litter our program with cube root calculations. So, someone reading our program will be able to tell immediately that, for example, a particular statement has a cube root in it, rather than constantly having to figure out the meaning of x ** (1.0 / 3.0) 3. Modular Programming: If we make a bunch of encapsulations, then we can have our main program simply call a bunch of procedures. That way, it s easy for someone reading our code to tell what s going on in the main program, and then to look at individual procedures to see how they work. 21