cs151 - Homework 1 CS 151 - Introduction to Data Structures Homework 1 Array and Classes - Zipcode lookup Read the program design principles and code formatting standards carefully. You are expected to adhere to all stated standards. Overview In this assignment you will read from a file data about every 5 digit zip code in the United States. In addition you will develop an interface that will allow you to query the data. (The data file is in CSV format. CSV is an acronym for Comma Separated Value. Most of the data files in the course will be in CSV format.) The general idea for the program in this assignment is that you will create a class (called Place below). Instances of the Place class hold information about a single zip code. You will create a second class (called PlaceContainer) that stores all of the instances of Place in a single large array. In addition that class will have methods for searching the array. Finally, in a third class (called Main) your program will interact with a user to allow search of the zip codes. Importantly, your program should only read the zip code file once! After reading and storing all of the zip codes, your program should continuously prompt the user for a zipcode until the user enters 'q' to quit. Here is a sample session of the unser interaction:
zipcode: 19010
Bryn Mawr, PA
zipcode: 99400
No such zipcode
zipcode: 91729
Rancho Cucamonga, CA
zipcode: q
Good Bye!
In the session shown above, everything is from the program other than the bold text immediately following "zipcode:"; the bold text is from the user. To get input from the user, use the Java Scanner class as ilustrated in this little program.
import java.util.Scanner;
public class UseScanner {
public static void main(String[] args) {
Scanner scnr = new Scanner(System.in);
while (true) {
System.out.print("Give me a string (q to quit):");
String l = scnr.next();
if (l.equals("q")) {
break;
}
System.out.println("You entered " + l);
}
}
}
Throughtout this course, you should use the Scanner class ONLY for user input. DO NOT use it otherwise. (There are ways to get user input other than Scanner; you may use any of them.) Input File Format The data file for this assignment is on the web at https://cs.brynmawr.edu/cs151/Data/Hw1/uszipcodes.csv. The file uszipcodes.csv contains all zipcodes used in the United States. Your program should read the data from exactly this location. (More precisely, the version of the program that you submit MUST read the file from exactly this location.) If you make a local copy for your development, that is OK. (To make a local copy use scp as described in lab1 to copy the file from /home/gtowell/Public/151/A01/uszipcodes.csv.) Here are the details of the data file’s format: The first line is a special line, giving some basic info about the file, in the following comma-separated values:
,zip,city,state,population,males,females, where the first field in the line is an integer giving you the number of zip codes stored in the file. The rest of the line contains column headers for the file. Other than the number of zip codes, this line can, and should, be ignored. The rest of the lines come in the following format: ,,,,,, where the comma-separated fields have the following meanings: zip the 5-digit zipcode town name name of the town with the zipcode state code 2-character encoding of the state name population population in this zipcode, an integer males number of males in this zipcode, an integer females number of females in this zipcode, an integer Sample snippet: 42613,zip,city,state,population,males,females, 00501,Holtsville,NY,,,, 00544,Holtsville,NY,,,, 00601,Adjuntas,PR,18570,9078,9492, 00602,Aguada,PR,41520,20396,21124, 00603,Aguadilla,PR,54689,26597,28092, ... According to the first line, there are 42,613 entries following the first line. In your code, create an array of exactly the size given on this line. DO NOT hard code this number into your program. Rather, read the first line and create an array whose size is given on the first line. This number may be different during testing. Zipcode 00501 belongs to the town of Holtsville, NY, for which we have no population recorded. In this assignment, you will ignore the population numbers, and store only the zip code, the town and the state. Note that there are towns whose names have more than one word, such as “Palm Springs”. You should definitely use the CSV reader class from Lab 1. (This is not required but is a really good idea.) 2 Specific Tasks Within Visual Studio Code (if you are not using VSC, do whatever you need to do here) create a new Folder. Specifically, do the following steps: Select File Menu / Close Folder Select File Menu / Open Click on cs151 in the main folder list (you should have made a cs151 folder in Lab 1) Click on the starred folder icon in the upper right (UNIX). On Macs this is "add folder" in lower left. Name the new folder "Assignment1" -- or any name that makes sense to you Click on "Create" Click on "OK" You may want to a local copy of the data file. Use the following steps: Open a terminal (or power shell, etc) Change your directory to the one which you created in the previous step If you want to keep copies of the data on your machine, execute the following
scp YOURNAME@goldengate.cs.brynmawr.edu:/home/gtowell/Public/151/A01/testZip.csv testzip.csv
scp YOURNAME@goldengate.cs.brynmawr.edu:/home/gtowell/Public/151/A01/uszipcodes.csv uszipcodes.csv
If you are working within the lab, you could make local copies of these data files
cp /home/gtowell/Public/151/A01/testZip.csv testzip.csv
cp /home/gtowell/Public/151/A01/uszipcodes.csv uszipcodes.csv
This should copy two files to your machine, testZip.csv and uszipcodes.csv. Create a class called Place to store information about each zipcode. Place should contain the following data fields: zipcode, town, state. Per data encapsulation, these fields should be private. You will need a constructor and several accessor methods in the Place class to set up the fields and to access them. The Place class should have a constructor with the following signature:
/**
* Creates a place with zip, town name and state
* @param zip a 5 digit zip code
* @param town the town name
* @param state the state abbreviation
*/
public Place(String zip, String town, String state)
There are many other ways you might implement the Place constructor. (You need to write the body for this constructor.) Do it this way in this assignment. Write a second class PlaceContainer that contains at least the following public methods to implement the main part of the assignment:
/**
* Reads a zip code file, parsing and storing every line
* @param a string containing either the name the zip code file or a URL for the zip code file
*/
public void readZipCodes(String name)
/**
* Find a Place record given a zip code
* @param zipCode the zip code to find.
* @return the place, or null if the zip code is unknown
*/
public Place lookupZip(String zipCode)
Implement the class PlaceContainer and the above methods. You may find it convenient to implement some other methods as well. The general idea is that the class PlaceContainer will have an private instance variable something like:
Place[] allZips;
which will get initialized and filled by readZipCodes. Then the method lookupZip will scan that array to find information. Finally, implement a class Main that contains only a main method. This method should use the methods in Place and Places to read and store the zip code file. (It could be that in reading and storing the main method within Main will not directly use methods in Place). The main method within Main should then implement the user interaction shown above. You might also have main methods inside both Place and PlaceContainer, but these should be only validate methods within those classes. A smaller file (of the same format), named testZip.csv, is available as well, in case you want to debug on a smaller dataset. 3 Electronic Submissions Your submission will be handed in using the submit script. If you write your program on computers other than those in the lab, be aware that your program will be graded based on how it runs on the department’s Linux server, not how it runs on your computer. If you are using Java 11, you will not have any problems with Java compatability. A way you might get into trouble is, for instance, if you developed this program on your personal computer and made a local copy of the uszipcodes.csv file and hardcoded the address of that file on your computer into your program. To fix, be sure to change the file name to https://cs.brynmawr.edu/cs151/Data/Hw1/uszipcodes.csv before handing your program in. Make a README Once you have finished coding (and fully commenting your code) make a README file. This file should follow the format of this sample README. This is your opportunity to tell me what went well or poorly, what is still broken and why, etc. I will read, and often respond to, everthing you write in the README. The easiest place to write your readme is within VSC. Make a file just like a standard java file but name it README.txt then just write in it. You should start by copying the sample readme. Submit If you developed this program on your own computer, do the following to transfer your program to the Linux computers so you will be able to submit. Open a terminal window on your computer (a windows powershell or a Mac terminal) Connect to a linux lab machine. A full list of possibly available lab machines is at Machine list. I will assume you are using 165.106.10.186 -- you can use any machine. To connect:
ssh YOURUNIXNAME@165.106.10.186
Enter your Unix password when prompted On the linux computer:
cd CS151
mkdir a1
You made the CS151 directory in Lab1. You can change a1 to whatever you like, the directions below assume a1. Leave this terminal window open and connected to Linux, you will use it again in a couple of steps Within VSC open a terminal by going to the Terminal menu and selecting "new terminal" In the Terminal inside of VSC you should be in the directory containing your program. Enter
scp * YOURNAME@165.106.10.186:cs151/a1
You should get messages on screen showing that each file in this directory has been copied. Confirm that the copy was successful. Back in the Terminal you opened on the Linux machines (in step 2)
ls a1
This should show a list of of the files copied in your scp command. When all of the files are in the a1 directory and you are still in the cs151 directory
/home/gtowell/bin/submit -c 151 -p 1 -d a1
This says to submit for project 1 (-p) everything in the directory a1 (-d) for the class 151 (-c). You should see listing of all the files you submitted and a message that says "success". You can submit multiple times. I will grade only the last submission -- unless you tell me otherwise. The submission process attaches a timestamp so I know when you submitted (down to the second). The closest submission I have ever received to the deadline is 7 seconds. If the submission deadline is approaching and you cannot get this process to work, send email gtowell151@cs.brynmawr.edu with all of your files attached. I will accept email submission for assignment 1 ONLY. The submission should include the following items: 1. README: This file should follow the format of this sample README 2. Source files: Main.java etc 3. Data files used: Be sure to include any non-standard data files used. (This would be very unusual) DO NOT INCLUDE Data files that are read from the class site. Do include any of your own data files.
