CMPS 144 Spring 2019
Prog. Assg. #1: Freeing Java Arrays from the Index Range Straitjacket
Due: 11:59pm, Sunday, Feb. 10

Motivation

In Java, every array's index range begins at zero. This can be rather inconvenient, as for many arrays it would be preferable to have an index range starting at 1. As an example, consider the DAYS_IN_MONTH[] array from Lab #1, the k-th element of which contained the number of days in the k-th month. By convention, months are numbered from 1 to 12, so the "most natural" index range for this array would have been 1..12. Instead, the array was declared to have length 13 (hence index range 0..12) and the element at location zero was left unused. An alternative would have been for the array to have index range 0..11 (thereby having no "extra" elements) and to store the number of days of the k-th month in location k-1.

In still other cases, it would be desirable for an array's index range to begin at neither 0 nor 1. For example, suppose you wanted to use an array to count the number of occurrences of each "printable" character in a plain text file. These are the characters that are encoded (under the ASCII standard) by the numbers 32 (representing the space character) through 126 (representing the tilde character, ~). Here, having an array whose index range is 32..126 would be most natural. One can also imagine scenarios in which it would be convenient for an array's index range to begin at a negative value.

Your Task

For this assignment, you are to complete the development of the Java class IndexedIntSeq, which stands for indexed integer sequence. Note that most of its methods are stubbed and no instance variables are declared.

Instances of this class have essentially the same functionality as arrays of type int[]1, even if the syntax for accessing their elements more closely resembles that of instances of the java.util.ArrayList class. That is, as with an array, you can retrieve/get the value stored at a specified position and you can place/put a value into a specified position.

What's different —and this is how we break out of the straitjacket— is that the index range of an IndexedIntSeq object is specified, at construction time, by the client, and thus can begin at any value of type int.

Suppose, for example, that a client creates an IndexedIntSeq object and assigns to variable seq a reference to that object as follows:

IndexedIntSeq seq = new IndexedIntSeq(8, 5);

Then one can picture the situation to be this: 

                      5   6   7   8   9  10  11  12
    +---+           +---+---+---+---+---+---+---+---+
seq | *-+---------->| 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
    +---+           +---+---+---+---+---+---+---+---+

The two parameters passed to the constructor indicate the desired length (8) of the sequence and the starting point (5) of its index range. As with an array of int values, we make the initial values in the sequence be zeros.

The get() and put() methods are for retrieving and storing values in the sequence, respectively. Thus, for example, the call s.put(9, -4) will place the value -4 into position 9 of the sequence (overwriting the 0 that had been there), yielding 

                      5   6   7   8   9  10  11  12
    +---+           +---+---+---+---+---+---+---+---+
seq | *-+---------->| 0 | 0 | 0 | 0 | -4| 0 | 0 | 0 |
    +---+           +---+---+---+---+---+---+---+---+

As another example, to increment the value at position k, we could say this:

seq.put(k, seq.get(k)+1);

The get() and put() methods are specified to throw an IndexOutOfBoundsException when the value of the relevant parameter is outside the sequence's index range. A statement for doing that is

throw new IndexOutOfBoundsException();

A String parameter can be included to provide more specific information to the caller. For example, making use of the rangeImage() method:

throw new IndexOutOfBoundsException(k + " not in range " + rangeImage());

For purposes of testing your work, you may want to make use of the IIS_Tester application.

Program Submission

Use the file submission system (see the link near the top of the course web page) to submit your completed IndexedIntSeq.java file into the prog1_dir folder. Make sure to complete the comments indicated near the top of the source code that has been provided. In particular, you should put your name and list the names of anyone who aided/collaborated with you in doing the work. Also, you are to describe any behavioral defects that your class has (e.g., characterizations of test cases that it fails). If there are defects of which you are unaware, it probably means that you did a poor job of testing your work. Thus, of two submissions having similar defects, one in which those defects are acknowledged deserves a better grade than one in which they are not acknowledged.

Footnotes

[1] Soon we will learn how to use generics so that a single Java class can give rise to different container objects, each of which is capable of storing values of whatever (reference) type the client specifies.