Skip to main content

Homework 0: Array and Classes - Zipcode lookup

Due: 2024-01-01 23:59:00EDT


In this project, we will practice file input, class design and arrays. All programming assignments will go through an autograder on Gradescope. The autograder will test for correctness, so it is important that you pay attention to naming conventions. In other words, name your classes, methods and directories EXACTLY as given here, including cases (otherwise you will receive points off).

All programming assignments in this class will follow the convention of having a Driver program. The driver should be called Driver<HWNumber>.java where <Number> is replaced with the homework number. In this assignment, your driver should be called

In addition, please read the program design principles and code formatting standards carefully. You are expected to adhere to all stated standards. Violations will result in deductions.

1 Input File Format

First, download your input file using wget uszipcodes.csv

The file uszipcodes.csv contains all zipcodes used in the United States. 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:


The remaining lines in the csv file are in the following format: <zip>,<city name>,<state code>,<population>,<males>,<females>,

where the comma-separated fields have the following meanings:

If you run head uszipcodes.csv, you should see something like the following:


As you can see from the above, 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 zipcode, the town and the state.

Note: there are some towns whose names have more than one word, such as “Palm Springs”.

2. Place class

In a file called, create a class called Place to model each zipcode to contain the following data fields: zipcode, town, state. In order to support data encapsulation, these fields should be labeled private. You will thus need a constructor and several accessor methods in the Place class to set up the fields and to access them.

2.1 Place constructor

Make sure to include a constructor in your Place class according to this signature:

/** Creates a Place with the given zip, town name, and
* state
* @param zip The 5-digit zip code
* @param town The town name
* @param state The state abbreviation
public Place(String zip, String town, String state)

2.2 toString

Override toString of the Place class so that System.out.print(ln) will print the town and state in the format “town, state”.

2.3 Accessors

Since a place should be immutable, we are not going to create any setters. Make sure to include accessors for the three instance variables. In order to match the autgrading (and Java standard), please name your accessors getZip(), getTown() and getState().

3. LookupZip class

Write a separate class LookupZip that will contain several public static methods. These methods are the main part of the assignment. Implement the class LookupZip by implementing the following methods based on the method signatures and javadocs.

3.1 parseLine

/** Parses one line of input by creating a Place that
* denotes the information in the given line
* @param line One line from the zipcodes file
* @return A Place that contains the relevant information
* (zip code, town, state) from that line
public static Place parseLine(String line)

3.2 readZipCodes

/** Reads a zipcodes file, parsing every line
   * @param filename The name of the zipcodes file
   * @param numEntries the number of places in the csv file
   * @return The array of Places representing all the
   * data in the file.
  public static Place[] readZipCodes(String filename, int numEntries) throws FileNotFoundException {

3.3 lookupZip

/** Find a Place with a given zip code
* @param places The array of Place objects to search through
* @param zip The zip code (as a String) to look up
* @return A place that matches the given zip code,
* or null if no such place exists.
public static Place lookupZip(Place[] places, String zip)

4. Driver

In, implement a main method that ties it all together. Your program should continuously prompt the user for a zipcode until the user enters 00000 to quit.

The driver should take in two command line arguments. First is the csv file that contains the information, second is the number of entries in that csv file. The given CSV has 42613 entries.

Here’s a sample session:

zipcode: 19010
Bryn Mawr, PA

zipcode: 99400
No such zipcode

zipcode: 91729
Rancho Cucamonga, CA

zipcode: 00000
Good Bye!


Your solutions will be run by an autograder. Thus it is important that you stick to the output format EXACTLY. That means exactly the same amount of white spaces, exactly the same punctuations and exactly the same error message. Below are a few tips on how to check for correctness yourself:

  1. Test your code on a smaller input file. We provide a smaller file named testZip.csv.

  2. Check your output (manually) against the sample output given above.

  3. Test some more zipcodes of your choice (your hometown, some other place you know, or just select a few random lines from the data file).

  4. To test your program, download some sample inputs and outputs: wget in.txt and wget out.txt

Provided in.txt contains 17 test inputs and out.txt contains the expected output if you ran your program with in.txt. Of course, you are not expected to type each input into your program by hand. You should use the command-line redirection feature of the Linux shell, which re-directs terminal I/O to files, like this:

java Driver00 uszipcodes.csv 42613 < in.txt > my-out.txt

< specifies replacing terminal input with the named file > specifies placing terminal output into the named file The Linux command diff can be used to compare two files for differences. If your program works correctly, diff my-out.txt out.txt should return nothing.


In a text file called README.txt answer the following questions:

  1. How much time did you spend on the homework
  2. What did you learn from this homework
  3. optional: What did you struggle with during this homework
  4. optional: any other feedback you would like to share


Submit the following files to the assignment called HW00 on Gradescope:

  4. README.txt

Make sure to name these files exactly what we specify here. Otherwise, our autograders might not work and we might have to take points off. DO NOT submit a .docx or .pdf file.

Copying the files

You will likely want to submit the files from your own laptop/computer. To copy the files from goldengate to your own machine, open up a terminal on your own computer. If you have a mac or linux, you can use the Terminal application, if you have a windows you can use the Powershell app.

Run the following command:

$ scp <username><username>/cs151/homeworks/hw00/*

Make sure to replace <username> with your username. scp is a command to secure-copy files from one server to another. In this case, from goldengate to your own machine.