documentation array and searching. documentation rules easy rules: –naming convention for...

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

http://java.sun.com/j2se/1.3/docs/api/java/lang/String.html

http://java.sun.com/j2se/1.4.2/docs/api/javax/swing/JOptionPane.html



Javadoc tool

• generating Application Program Interface (API) documentation in HTML format from doc comments in source code.

• Resource:http://java.sun.com/j2se/javadoc/

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

}

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

• 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.


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:


ArrayClass anObj = new ArrayClass();int number[] = new int[5];for(int i=0; i<number.length; i++)

number[0] = i;

anObj.changeArrayValue(number);


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

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


• 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 } };


• 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


• 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

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.

documentation array and searching. documentation rules easy rules: –naming convention for...

Documents