## CS 101 (Fall 2002) Lab 4: Persian Recursion

Lab Assigned Design Due
(In class)
10 AM
Implement
(In Lab)
Demo
(In Lab)
Lab Due
(In class)
Friday
10 AM
30 Sep 4 Oct 1-2 Oct 8-9 Oct 11 Oct

### Overview:

Recursive programs are useful when a large problem can be cast as smaller instances of itself. Recursive programs tend to be short compared with the job that they do. In this lab, you will first design an API and then implement classes that have the effect of drawing a Persian rug on the screen.

### Goals:

By the end of this lab, you should
• Gain experience in API design
• Gain more experience with recursive solutions and programs
This lab contains two parts, design and implementation, due as shown at the beginning of this document. The Monday after your design is due, a sample design will be handed out in class. We may choose one of your designs for this honor; or, we may write one up on our own. Remember, there is no right or wrong design, but each design may have its own strengths and weaknesses.

### Before starting:

• Read over this entire document before you start.
• Make sure you understand what is expected from you by way of an API.
• Study the recursion examples given in class.
• Run the sample solution.
Zip includes:

Recall that the following line should appear at the top of any files that use the canvas classes.

```import canvas.*;
```

### Problem description: Persian Recursion

The idea for this lab appeared in the article "Persian Recursion", by Anne M. Burns, Mathematics Magazine, volume 70, 1997, pages 196-199.
Design and implement the class `PersianRug.java` that does the following.

• Initially (when the constructor is called), a square S of a supplied size is drawn. The color of each edge of this square is the same color.
• Subsequently, when a method of your choosing (in your design) is called
• S is subdivided into four quadrants by placing a horizontal and vertical line through the middle. The color of these two lines is identical, and is some function of the colors of S's edges.
• This algorithm is replied recursively to the resulting 4 subquadrants.
• Recursion stops when further subdivision cannot contribute to the picture.
• Your design should include the specification of some methods to find out how much work your Persian recursion class did. At the least, methods to obtain the following should be specified:
• How many lines were drawn?
• What was the size of the smallest line?
• How often was a given color used?
• The results of these statistics should be formatted nicely as a string of your `PersianRug`'s `toString()`.
• If you allow the algorithm to run for a few days, you can generate a rug that looks like this:
To run this solution, first set your screen resolution to 1600x1200 (or you will not recieve the same degree of detail).
To setup your code to draw with such precision, set the minimum size for a line to 2 pixels.
Then, run this sample solution.

### Design Strategy

1. Complete a design cover sheet.
2. You are given the code for `Crayon.java`. As an exercise, write the API for this class and turn it in as part of your design.
3. Define your `PersianRug` class. Give its API and describe what all of its methods do. Normally, private methods would not appear in an API, but for this assignment consider them as well.

To find out how to draw colored lines, take a look at the `Line` class. Look for a constructor that accepts the line's coordinates as well as a color. (If we had given you an API for `Line` this would be easy!)

The effect of this lab is to make a picture that looks like a Persian rug. To see this effect, run the sample solution.

For the purpose of this lab, it is helpful to regard color as an integer. This is a kind of abstraction that allows us to compute one color as the function of other colors. You are supplied with the class `Crayon.java`, which lets you provide an integer and get a `Color`. As part of the design component of this lab, you are asked to write the API for `Crayon.java`.

You will have to invent a method for this class that takes four colors (the colors of a square's sides) and computes what color the middle (subdividing) lines should be. Let c1, c2, c3, and c4 represent the (`int`) color of each of the four sides of a square. If the initial square's sides are color 0, then a bad function would be:

```  (c1 + c2 + c3 + c4)
```
because the result would always be 0. For the design don't worry about the particular function---worry only about its type signature. However, for the implementation you will experiment with a few functions:
1. Find a function that always draws the same color
2. Find a function that always alternates between two colors
3. Find a function that uses all the colors

Place code in your class to count how many times your recursive method is called from within the class. At the end of the computation, print out this number (with a nice message) using `Terminal.println`.

### What is an API?

An API is an Application Programming Interface. It tells somebody what they need to know to use a particular class. As an example of an API, take a look at what you were provided for `Rect` in Lab 2. The API should include the following:
• A simple, short-paragraph description of what the class does
• A list of constructor(s) offered by the class
• A list of the public method(s) offered by the class. The private methods do not need to be documented: others cannot use them. However, the public methods must be documented, in terms of their
For each constructor or method, you should specify its
• parameters (names, types, and meaning); the meaning of a parameter gives us an idea of the units of the parameter.

As an example, consider the work you must do for the API for `Crayon.java`. The constructor uses the parameter `colorNumber`. So, you must say what its type is:

``` int colorNumber
```
but you should also specify its meaningful values:
``` int colorNumber (an integer between 0 and 15, inclusively)
```
as well as its function:
``` int colorNumber
an integer between 0 and 15, inclusively
Crayon converts this integer into a unique color
if the constructor is called with an an integer outside the
allowed range, an error is generated
```
• return type (type and meaning)
• function in your class design
A good test of your API is to show it to somebody (maybe somebody in cs101, a TA, or the instructor), and ask that person if the API tells him or her what is needed to use your class.