Documentation Array and Searching

1. DocumentationArray 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) l11 or 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 <name of parameter><description> For example: /* @param fileNamethis represents the name of the file created for writing purpose. */ public void writeToFile(String fileName)

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

14. Required tags @author <name of author> @version <version number>, <date>

15. Required tags • @return     <description of the item returned> 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 <datatype> <field name>; 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 <documentation directory> <java file name>

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 */ publicstaticdouble 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: <data type>[] <array_name>; OR <data type> <array_name>[]; 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[0] number 6 0 1 2 3 4

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. 0 1 1 2 2 3 3 4 4 5 Passing Array to Methods for(int i=0; i<number.length; i++) number[i] = i; anObj.changeArrayValue(number); number 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.