Documentation Array and Searching
DocumentationArray and Searching
Documentation rules
• Easy rules: – Naming convention for variables, constants
and methods
• Difficult rules: – Professional comments that generate
professional looking documentation using Javadoc tool
Naming convention
• Variables:– Class names, method names, and variable names
must be descriptive.– NO one character names, short cryptic
names/abbreviations are acceptedException: 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.
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 orloanAmount
3. Is this acceptable: for (int i=0; i<MAX_AMOUNT; i++) {……}
Examples
• Can I do this:int n = 12;
Why/Why not?
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
Javadoc tool
• generating Application Program Interface (API) documentation in HTML format from doc comments in source code.
• Resource:http://java.sun.com/j2se/javadoc/
What we focus on in this course
• How to write simple doc comments for Javadoc
• How to run Javadoc
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
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.
…………..**/
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.
Required tags
• @param <name of parameter> <description>
For example: /* @param fileName this represents the
name of the file created for writing purpose.
*/public void writeToFile(String fileName)
Require tags
@throws <exception> <description>Example:/* @throws IOException if any error
happens during the process of writing to a file.
*/public void writeToFile(String filename,
int[] array) throws IOException
Required tags
@author <name of author>
@version <version number>, <date>
Required tags
• @return <description of the item returned>Note: Omit this for constructors and void
methodsExample: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)
Example
/**What do I write here?????
**/public void readFromFile(String filename) throws
IOException {
………………………………………………..
}
Fields
/** field description*/public <datatype> <field name>;
Note: The documentation is only generated for those methods/fields that are declared as public
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>
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
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
}
Lab 2
Project 1 checklist
• Java files *.java• Create your own book.txt• Commenting your code
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
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
On the fly review
• Array is a collection of data values of the different data typesa. Trueb. False
On the fly review
• Array is a collection of data values of the different data typesa. Trueb. False
Arrays
• Array is a collection of data values of the same data type.
• Example:int[ ] number; // This is an array of integersdouble[] gpa; // This an array of double
Array Declaration
Format:<data type>[] <array_name>;
OR<data type> <array_name>[];
data type: double, int, float, StringExample:
double[] gpa;Or
double gpa[];
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: 5memory: 20 bytes
Array is a reference data type. Array is NOT an object
Arrays
Example:int[ ] number = new int[5];
number
1 2 30 4
number[0]
6
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];
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.
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];
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
Arrays of Objects
private Loan[] loanArray = new Loan[5];
for (i=0; i<5; i++) {loanArray[i] = new Loan();
}loanArray
Indexing an Array
int[] number = new int [5];number[0] =2;number[1]=3;number[2]=4;number[3]= 6;number[4]=-1;
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.
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,});
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];
}
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.
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:
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);
Passing Array to Methods
for(int i=0; i<number.length; i++)number[i] = i;
anObj.changeArrayValue(number);
0 1 2 3 4
1 2 3 4 5
number
number
On the fly review
The amount of memory allocated to store an array depends on:a. the name of the arrayb. the size of the arrayc. the size and type of values in the arrayd. none of the above
On the fly review
The amount of memory allocated to store an array depends on:a. the name of the arrayb. the size of the arrayc. the size and type of values in the arrayd. none of the above
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.”
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.”
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.
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;}
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.
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.
2D Array Constructionfinal 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' },};
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.
Multidimensional Arrays
• Multidimensional arrays– Tables with rows and columns
• Two-dimensional array• m-by-n array
Two-dimensional array with three rows and four
columns.
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
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 } };
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
Multidimensional Arrays (Cont.)
• Common multidimensional-array manipulations performed with for statements– Many common array manipulations use for
statementsE.g.,
for ( int column = 0; column < a[ 2 ].length; column++ ) a[ 2 ][ column ] = 0;
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 ]
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 ]
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.
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.