CSCI 235 Lab 4: Writing simple methods

The primary goal of this lab is to get practice with basic methods. The logic is very simple in this lab; the point is to become familiar with the syntax of methods and how to document them. This lab also gives you an opportunity for practice with the Mercurial revision control system. You have been previously provided with an overview of Mercurial, which is also accessible online.

1. Setup

Clone the repository for this lab from the shared class directory:

$ hg clone /cslab/class/csci235/labs/lab4

After you clone, you can cd into the lab4 directory that holds your new working copy. That directory also contains a local copy of the repository, which you will not usually see. If you do a plain ls, you won’t see anything but one Java source file. However, if you give the -a (for all) option to ls, it will show you the filenames that start with dots. You should see a couple that start with .hg; that is where your repository is hiding.

You can check the status of your working copy with

$ hg status

That won’t tell you much right now, because you haven’t done anything. If you try

$ hg log

you will see the history of revisions to the repository (which starts a couple of class meetings ago).

Now fire up your editor and make an awful mess of ArrayManip.java, being sure you save the results. If you try the status command again, the file will be flagged as ”modified”. Now try

$ hg revert ArrayManip.java

That will cause the file ArrayManip.java to revert to the last version committed to the repository. You’ll need to re-load it in the editor to see that, but it should look better than your mess.

The ”revert” will also leave behind a file ArrayManip.java.orig containing your mess. That would give you a chance to salvage something from it, if you needed to. If you now try

$ hg status

you should see that file listed as unknown to Mercurial. You probably want to go ahead and remove it now.

2. Time travel

The command hg log lists the available revisions. The first line for each revision starts with changeset, followed by two numbers. The first number (before the colon) is the convenient way to identify a revision; what follows the colon is a less convenient way to do the same thing. Notice that each revision indicates who made it and when, and it has a line summarizing the change.

You can set your working copy to any revision in the log. So do

$ hg update -r 9

to see a cleaned-up version of what we had at the end of class. You might look at MoreArrays.java with an editor. If you look at ArrayManip.java you’ll see what you got on the printout yesterday—we did not get to making any changes.

After you have looked it over, travel back to the latest revision with

$ hg update -r 10

This version matches the printed copy you received today. I have added in parts of some method definitions at the end to help you get started. To make it easier to find a particular method, I’ve kept the additions in alphabetical order.

Notice the descriptive comment that I have inserted before each of these methods (and that I’ve included some such comments for methods that I have not written). Each of these comments begins with ”/**” and includes one or more lines with @ to indicate a tag. This style of documenting methods allows special tools to generate the kind of documentation that you see for the library. Writing comments like these is an important part of making your program intelligible to the people that will read it.

3. Overview

You are going to be working on ArrayManip.java, filling in some methods, writing new methods, and modifying the cases within the main() switch statement to use the methods you are writing. Before you start making changes, take a few more minutes to review the code. Compared to the revision you were looking at previously, it has some additional methods and comments about methods. They are in alphabetical order, to make it easier to find the one you are looking for.

I have provided you with the complete method fillRandom(), the skeleton for average(), isSorted() and printArray(),

and comments or place-holders for several more methods.

The comments that I have filled in are examples of how we will document (describe) each method we write. Here is the comment for isSorted():

    /**  
     * Test whether an array is sorted (in ascending order).  
     * @param a The array to test.  
     * @return Whether a is sorted.  
     */

Note how it is formatted and that it starts with ’/**’. The first line of text is a sentence stating what the method should do. The next two lines have tags; they describe (in order) the parameters of the method and the value that it returns.

The comment for fillRandom() is similar. There is no @return tag, because the return type is void. The POSTCONDITION line states what is true after the method returns. Some methods will have a PRECONDITION line to say what must be true before the method is called (see the comment for enlarge()).

4. What to do

Open ArrayManip.java in an editor and add your names after the @author tag in the header comment. After you change the file, use hg status to verify that just the file you want shows up as modified, and then commit your change to the repository with

hg commit -m "Filled in our names"

The message on the end is what you will now will be able to see in the repository’s logs. So try

$ hg log

to see the revisions in your repository. There are a bunch of revisions, and you’re probably only interested in the last few; so you might try

$ hg log --limit=4

to see just the last four.

Make the following changes, one at a time. As you finish each, test to make sure it works correctly, and commit the change to your repository (check status and commit). Do as many of the changes as you have time for.

  1. Fill in case 10 to use the fillRandom() method.
  2. Write the body of printArray(), and change case 4 to call it.
  3. Write the body of average(), and change case 2 to call it.
  4. Fill in case 8 to call the isSorted() method and print whether the array is in order. An array is sorted when every element is greater than or equal to the element preceding it.
  5. Write the method enlarge() to do the work for case 5. The comment has already been written. You can then change case 5 by replacing the last eight lines before the break with
    a = enlarge(a, newLength);

  6. Write a method reverse() that reverses the elements in the array passed to it without creating a new array. The heading for that method will be
    public static void reverse(int[] a)

    You need to write the comment, too.

    Change case 7 to use this method..

  7. Write the heading and body of the method changeLength() that makes a new array that is either larger or smaller than the one passed to it. Case 6 should prompt for a new size (as case 5 does) and then use this method to make the change.
  8. Write a method fillSequence() that fills the array with numbers in sequence; change case 9 to call your new method. You will have to decide on the interface and write the comment that describes it. Put that method in the correct place in the file.

    (The simplest version would always fill starting from zero and counting by ones. You could opt for a fancier version that takes a starting value and a step between values, in which case you would want to make case 7 prompt for the additional values it needs.)

5. Turn in

Be sure that you have your changes committed.

Remove your .class file. Then create a script file in which you compile and run your program. Do enough operations to demonstrate each of the methods you wrote. After you have run the program, include hg log before you end the script.

Use handin to turn in your source file and the script file as lab4. Do not turn in a printed copy.

5. Cloning a repository to your account

You can copy the repository (with all of its history) to your account as a Mercurial clone. Assuming that your account name is mortimersnerd and that you already have a subdirectory named cs235, you’d do the command

$ hg clone . ssh://mortimersnerd@cslab25/cs235/lab4/

You’ll be prompted for your password, of course.

The script file is not in your repository. If it is named typescript you can copy it with the command

$ scp typescript mortimersnerd@cslab25:cs235/lab4/