CS 206 - Introduction to Data Structures

Homework 2

Array and Classes - Zipcode lookup

Due Feb 25, before 11:59pm

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 store the data contained in file of information about every 5 digit zip code in the United States. This information is stored in a CSV file. The general idea is that you will create a class (called Place below) whose instances hold information read from the CSV file about a single zip code. You will create a second class (called Places) that stores all of the instances Place in a single large array. Finally, in a third class 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 '00000' to quit.

Here is a sample session:

      zipcode: 19010
      Bryn Mawr, PA
      
      zipcode: 99400
      No such zipcode
      
      zipcode: 91729
      Rancho Cucamonga, CA
      
      zipcode: 00000
      Good Bye!
In this session everything is from the program other than the 5 digits immediately following "zipcode:"

Input File Format

All data files for this assignment are in /home/gtowell/Public/206/a2.
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. (This is actually encouraged. Use scp as described in lab1 to copy the file from the location given above to your device. This is also described in more detail below.) The version you submit must read from /home/gtowell/Public/206/a2.

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:

<num>,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 be ignored.

The rest of the lines come in the following format:

<zip>,<town name>,<state code>,<population>,<males>,<females>,

where the comma-separated fields have the following meanings:

zip the 5-digit zipcode
town name name of the town with the zipcode
state code2-character encoding of the state name
populationpopulation 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,  
...  

There are 42,613 entries following the first line. Zipcode 00501 belongs to the town of Holtsville, NY, for which we have no population recorded. Importantly, do NOT hard code 42,613 into your program. Rather read the first line, extract the number of lines; then create the appropriately sized array.

In this assignment, you will ignore the population numbers, and store only the zip code, the town and the state. Note however that there are towns whose names have more than one word, such as “Palm Springs”.

2 Specific Tasks

  1. Within Visual Studio Code (if you are not using VSC, you do whatever you need to do here) create a new Workspace as you did in Lab 2. Specifically, do the following steps:
    1. Select File Menu / Close Folder
    2. Select File Menu / Open Folder
    3. Click on cs206 in the main folder list
    4. Click on the starred folder icon in the upper right (UNIX). On Macs this is “add folder” in lower left.
    5. Name the new folder “Assignment2”
    6. Click on “Create”
    7. Click on “OK”
  2. If you are working on your own local machine, get a copy of the data file. Use the following steps:
    1. Open a terminal (or power shell, etc)
    2. Change your directory to the one which you created in the previous step
    3. execute the following
      scp YOURNAME@165.106.10.186:/home/gtowell/Public/206/a2/testZip.csv .
      scp YOURNAME@165.106.10.186:/home/gtowell/Public/206/a2/uszipcodes.csv .
                       
      This should copy two files to your machine, testZip.csv ands uszipcodes.csv. (Recall that the period at the endof the line is significant, do not miss it.)
  3. Create a class called Place to store 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.
  4. 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. Do it this way in this assignment.
  5. Write a second class Places 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 fileName the zip code file
         * @throws FileNotFoundException if the file does not exist
         */
        public void readZipCodes(String fileName) throws FileNotFoundException 
    
        /**
         * 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 Places and the above methods.
  6. The general idea is that the class Places 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.

  7. 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 does not directly use methods in Place). It should then implement the user interaction shown above.

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 per my installation instructions in lab 2, 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 /home/gtowell/Public/206/a2/uszipcodes.csv before handing your program in.

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 uses. (There should not be any)
DO NOT INCLUDE:
Data files that are read from the class site. Do include any of your own data files.

The following steps for submission assume you are using Visual Studio Code, and that you created a folder named Assignment2 in the directory /home/YOU/cs206/

  1. Put the README file into the Project directory (/home/YOU/cs206/Assignment2)
  2. Go to the directory /home/YOU/cs206
  3. Enter /home/gtowell/bin/submit -c 206 -p 2 -d Assignment2 For more on using the submit script click here