1. Documentation Array and Searching

2. Documentation rules Easy rules: –Naming convention for variables, constants and methods Difficult rules: –Professional comments that generate professional looking documentation using Javadoc tool

3. Naming convention Variables: –Class names, method names, and variable names must be descriptive. –NO one character names, short cryptic names/abbreviations are accepted Exception: counting variable in a for loop Constants: - 0 and 1 may be used through out the program - Otherwise, all constants should be defined and given descriptive names.

4. Examples 1. Which one is more descriptive (for a class to compute a special type of loan – discounted loan) DataProcessing or DiscountedLoan 2. Which one is better (for a variable name) l11or loanAmount 3. Is this acceptable: for (int i=0; i<MAX_AMOUNT; i++) { …… }

5. Examples Can I do this: int n = 12; Why/Why not?

6. Using Javadoc to generate documentation Examples: documentation for String class in Java documentation for JOptionPane class in Java How can we generate a similar document for our own class

7. Javadoc tool generating Application Program Interface (API) documentation in HTML format from doc comments in source code. Resource: http://java.sun.com/j2se/javadoc/

8. What we focus on in this course How to write simple doc comments for Javadoc How to run Javadoc

9. Writing Doc comments A doc comment must precede a class, field, constructor or method declaration Class description: First sentence: should be a summary sentence, containing a concise but complete description of a class. In other words, it should talk about the purpose of this class

10. Writing DOC comments Constructors/methods: Contains: PURPOSE, Data (parameters, what they are) and details description of data (parameters name, their data types) Example: public void writeToFile(String fileName, int array[]) /** Purpose: Write an array of integers to a file and throws exception if there is any errors happening during this process. Data: It takes two arguments: file name and array name. The filename argument must specify a valid file name. The array argument must specify the name of the array being written to a file. ………….. **/

11. Writing Doc comments Block tags: @param (classes, interfaces, methods and constructors only) @return (methods only) @exception (@throws is a synonym added in Javadoc 1.2) @author (classes and interfaces only, required) @version (classes and interfaces only, required.

12. Required tags @param For example: /* @param fileName this represents the name of the file created for writing purpose. */ public void writeToFile(String fileName)

13. Require tags @throws Example: /* @throws IOException if any error happens during the process of writing to a file. */ public void writeToFile(String filename, int[] array) throws IOException

14. Required tags @author @version,

15. Required tags @return Note: Omit this for constructors and void methods Example: public void writeToFile(String fileName) ??? /* @return a boolean value (true/false) if there is no error/or any errors during reading process. */ public boolean readFromFile(String fileName)

16. Example /** What do I write here????? **/ public void readFromFile(String filename) throws IOException { ……………………………………………….. }

17. Fields /** field description */ public ; Note: The documentation is only generated for those methods/fields that are declared as public

18. How to run Javadoc Step 1: Make sure you have javadoc installed Step 2: Command line mode: change to the source directory type: javadoc d

19. How to run Javadoc in eclipse Step 1: Make sure you have javadoc installed (searching for javadoc.exe, usually in bin subdirectory of your JDK) Step 2: In eclipse: Choose Project -> Generate javadoc -> Configure to navigate to where your javadoc resides -> change the directory where javadoc documents will be generated if necessary. -> Finish

20. Example /** * Converts a given length in inches to equivalent centimeters. * @param inches the length expressed in inches * @return length expressed in centimeters */ public static double inchesToCentimeters( double inches ) { // this is a stub return 0; // please change it with your code }

21. Lab 2

22. Project 1 checklist Java files *.java Create your own book.txt Commenting your code

23. On the fly review Given a one dimensional array myArray, what is the correct way of getting the number of elements in this array. a. myArray.length b. myArray.length - 1 c. myArray.size d. myArray.size – 1

24. On the fly review Given a one dimensional array myArray, what is the correct way of getting the number of elements in this array. a. myArray.length b. myArray.length - 1 c. myArray.size d. myArray.size – 1

25. On the fly review Array is a collection of data values of the different data types a. True b. False

26. On the fly review Array is a collection of data values of the different data types a. True b. False

27. Arrays Array is a collection of data values of the same data type. Example: int[ ] number; // This is an array of integers double[] gpa; // This an array of double

28. Array Declaration Format: [] ; OR []; data type: double, int, float, String Example: double[] gpa; Or double gpa[];

29. Arrays The amount of memory allocated to store an array depends on the size and type of values in the array –Size: number of elements in the array –Type of values: data type of each element in the array –An individual value in an array is called array element Example: int[ ] number = new int[5]; data type: integer (4 bytes) size: 5 memory: 20 bytes Array is a reference data type. Array is NOT an object

30. Arrays Example: int[ ] number = new int[5]; number 12304 number[0] 6

31. Arrays Elements of an array are indexed from zero to size -1 Size: the number of elements in an array length: a public constant represents the size of an array. Example: sum =0; for (int i=0; i<number.length; i++) sum += number[i];

32. Fixed –size array declaration Size of an array is pre-determined. Example: int[] number= new int[5]; Problems: What if we have more than pre-determined size of an array? Underutilization of space.

33. Variable-size array declaration In Java, we can declare an array of different size every time we run a program Example: int size; int[] number; inputStr = JOptionPane.showInputDialog(null,"Please enter the number of elements "); size = Integer.parseInt(inputStr); number = new int[size];

34. Arrays for Objects // An array for the names of the distinct private Loan[] loanArray = new Loan[5]; Note: No Loan objects are created. Only a container for Loan. Each location is initialized to null. loanArray NULL

35. Arrays of Objects private Loan[] loanArray = new Loan[5]; for (i=0; i<5; i++) { loanArray[i] = new Loan(); } loanArray

36. Indexing an Array int[] number = new int [5]; number[0] =2; number[1]=3; number[2]=4; number[3]= 6; number[4]=-1;

37. Initializing Arrays... // Differentially number the assignments. private int[] number = {1, 2, 1, 5, 1,}; private final int totalNumber = number.length; No new required. Terminating semicolon. Optional final comma.

38. Further Initializer Examples String[] suitNames = { "Spades", "Hearts", "Diamonds", "Clubs" }; Point[] vertices = { new Point(0,0), new Point(0,1), new Point(1,1), new Point(1,0), }; YearlyRainfall y2k = new YearlyRainfall( new int[]{10,10,8,8,6,4,4,0,4,4,7,10,});

39. Iterating over an Array in Reverse int size = 5; minValue = number[size-1]; for (int i=size-2; i>=0; i--) { if (minValue > number[i]) minValue = number[i]; }

40. Passing Array to Methods When an array is passed to a method, only its reference is passed. A copy of the array is not created in the method. That means: we pass the identifier for that array which in fact is a reference to a start address of the array.

41. Passing Array to Methods Assuming changeArrayValue is one method of a class named ArrayClass public void changeArrayValue(int[] arrayChanged) { for (int i=0; i< arrayChanged.length-1; i++) arrayChanged[i] += 1; } We call this method as:

42. Passing Array to Methods ArrayClass anObj = new ArrayClass(); int number[] = new int[5]; for(int i=0; i<number.length; i++) number[0] = i; anObj.changeArrayValue(number);

43. Passing Array to Methods for(int i=0; i<number.length; i++) number[i] = i; anObj.changeArrayValue(number); 0123 4 1234 5 number

44. On the fly review The amount of memory allocated to store an array depends on: a. the name of the array b. the size of the array c. the size and type of values in the array d. none of the above

45. On the fly review The amount of memory allocated to store an array depends on: a. the name of the array b. the size of the array c. the size and type of values in the array d. none of the above

46. On the fly review Arrays are: a. variable-length entities. b. fixed-length entities. c. data structures that contain up to 10 related data items. d. used to draw a sequence of lines, or “rays.”

47. On the fly review Arrays are: a. variable-length entities. b. fixed-length entities. c. data structures that contain up to 10 related data items. d. used to draw a sequence of lines, or “rays.”

48. Searching an Unsorted Array We often need to search an array for a particular item of data. The data is often unsorted. The item might or might not be present. –Care must be taken not to search beyond the end of the array. –We need to decide how to return a found item.

49. Search with Multiple Returns public int indexOf(int[] numbers,int value){ final int notPresent = -1; for(int index = 0; index < numbers.length; index++){ if(numbers[index] == value){ return index; } // We did not find it. return notPresent; }

50. The Arrays Class Defined in the java.util package. Contains static methods for manipulating arrays: –binarySearch : search for a value. –equals : compare the contents of two arrays. –fill : fill an array with a particular value. –sort : sort the contents of an array.

51. Multi-Dimensional Arrays Arrays of multiple dimensions are possible. –2D grid, for a board game such as chess. –3D cube structure, etc. Multi-dimensional arrays are regarded as being arrays of arrays. Non-rectangular structures are possible.

52. 2D Array Construction final int numRows = 10, numCols = 5; double[][] matrix = new double[numRows][numCols]; char[][] hiddenWord = { { 'd', 'g', 'i', 'b' }, { 'e', 'i', 'u', 'm' }, { 't', 'a', 's', 'a' }, };

53. Review Arrays make it possible to group related items in a single object. An array's length is fixed on construction. Arrays may have multiple dimensions.

54. Multidimensional Arrays Multidimensional arrays –Tables with rows and columns Two-dimensional array m-by-n array

55. Two-dimensional array with three rows and four columns.

56. Multidimensional Arrays (Cont.) Arrays of one-dimensional array –Declaring two-dimensional array b[2][2] int b[][] = { { 1, 2 }, { 3, 4 } }; –1 and 2 initialize b[0][0] and b[0][1] –3 and 4 initialize b[1][0] and b[1][1] int b[][] = { { 1, 2 }, { 3, 4, 5 } }; –row 0 contains elements 1 and 2 –row 1 contains elements 3, 4 and 5

57. Multidimensional Arrays (Cont.) Two-dimensional arrays with rows of different lengths –Lengths of rows in array are not required to be the same E.g., int b[][] = { { 1, 2 }, { 3, 4, 5 } };

58. Multidimensional Arrays (Cont.) Creating two-dimensional arrays with array- creation expressions –Can be created dynamically 3 -by- 4 array int b[][]; b = new int[ 3 ][ 4 ]; Rows can have different number of columns int b[][]; b = new int[ 2 ][ ]; // create 2 rows b[ 0 ] = new int[ 5 ]; // create 5 columns for row 0 b[ 1 ] = new int[ 3 ]; // create 3 columns for row 1

59. Multidimensional Arrays (Cont.) Common multidimensional-array manipulations performed with for statements –Many common array manipulations use for statements E.g., for ( int column = 0; column < a[ 2 ].length; column++ ) a[ 2 ][ column ] = 0;

60. On the fly review In array items, which expression below retrieve the value at row 4 and column 5? a. items[ 3 ].[ 4 ] b. items[ 3[ 4 ] ] c. items[ 3 ][ 4 ] d. items[ 3, 4 ]

61. On the fly review In array items, which expression below retrieve the value at row 4 and column 5? a. items[ 3 ].[ 4 ] b. items[ 3[ 4 ] ] c. items[ 3 ][ 4 ] d. items[ 3, 4 ]

62. On the fly review An array with m rows and n columns is NOT: A. An m-by-n array.B. An n-by-m array. C. A two-dimensional array. 1. A and C. 2. A. 3. B. 4. C.

63. On the fly review An array with m rows and n columns is NOT: A. An m-by-n array.B. An n-by-m array. C. A two-dimensional array. 1. A and C. 2. A. 3. B. 4. C.