Project 1 | CS 2113 Software Engineering - Spring 2021
Project 1
There are two parts to this project, with two different deadlines. In part A, you will implement a hashtable
(hashmap) and linked list in C that is used in a spellcheck and boggle solver application. In part B, you will
complete the same data structures and applications using Java.
Preliminaries
Github Classroom links
Part A: https://classroom.github.com/a/fxDdTKFg (C Portion)
Part B: https://classroom.github.com/a/0QShWEWQ (Java Portion)
Test Script
To help you complete this project, each part is provided with a test script. The script is not designed to be
comprehensive, and you will graded based on a larger array of tests. To execute the test script, run it from
anywhere within the lab directory.
./test.sh
Note that when executing the test script using replit, due to using valgrind, it may take upwards of 5 minutes to
complete! So you are better served developing some tests on your own rather than relying on the test script.
Compiling your code:
Part A
For part A (C implementation), we have provided you with a Makefile . You can compile the spellchecker or
boggle solver by typing:
make spellcheck
make onePlayerBoggle
If you want to compile everything at once, simply type make . This will produce a number of additional .o files
(or object files), which are compiled C files that are not yet assembled. Do not add these to your repository as
they get overridden on every compilation.
To clean up your repository, you can use make clean command.
Part B
For part B (Java implementation), you should compile using javac .
CS2113SoftwareEngineering-Spring2021
2/24/2021 Project 1 | CS 2113 Software Engineering - Spring 2021
https://cs2113-s21.github.io/project/1 2/13
javac SpellChecker
javac OnePlayerBoggle
You should not add your class files ( .class ) to the repository.
Development Environments
You can complete both parts using replit, if you so desire. For part A you will find that valgrind will run much
faster using a local Ubuntu installation, either via WSL or in a virtual machine — this is our recommended
development choice.
For part B, you may use replit, or you could develop your code in IntelliJ. One benefit of IntelliJ is that you can use
its built in debugger, which is extremely helpful.
Data Structure Implementations
In both parts of the project, you will be implementing two basic data structures: a Linked List and a Hash Table (or
Hashmap).
Linked List
The Linked List you will complete only requires forward pointers on its nodes, and only the push() operation, that
is, put a new node on the front of the list. Each node in the list stores a string value. There is no need for the list to
be generic.
Hashmap
The Hashmap data structure is simply a membership Hash Table — unlike a truly generic Hashmap that stores key,
value pairs, this table returns true if an items is stored in the data structure and false otherwise. Put another
way, itʼs a Hashmap that maps a value to true. The Hashmap you will implement only needs to store strings. It has
the following member functions:
add(string) -> void : add a string to the hashmap
check(string) -> bool : check to see if a string is in the hashamp, return true if present, else false.
The Hashmap should be implemented as a hash table with separate chaining. You may recall from your data
structures class, this means that when two elements collide at an index, you add the item on to that spot, using say
Linked List.
Following that model, your Hashmap should have an array (or buckets) of Linked Lists. After achieving the hash
value for a given string (modulo the range of buckets), you push that string onto the Linked List at that index
associated with the hash value. Critically, the performance of the Hashmap depends on the length of the lists of
each bucket — if the lists get too long, then the look up operation could become O(n)!
The load on a hash table is defined as the number of items stored in the table divided by the number of buckets.
High loads means longer lists at each bucket and worse performance. To keep performance steady, once the load
reaches 0.75, you have to resize the hash table by doubling the number of buckets and reinserting all the items into
their new hash locations. YOU MUST IMPLEMENT A RESIZE ROUTINE – YOU CANNOT SIMPLY SET YOUR
NUMBER OF BUCKETS TO A LARGE VALUE!!
2/24/2021 Project 1 | CS 2113 Software Engineering - Spring 2021
https://cs2113-s21.github.io/project/1 3/13
Part (A) (C Implementation) (70 Points)
Github
Data Structure Implementation
The crucial part of this project is the data structure implementations. In C, you typically divide your data structures
between a header file (a .h file) and a source file (a .c file). The header file contains the structure and function
definitions, while the source file contains their implementations. You will primarily work with the source files ( .c ).
Linked List
As you can see the llist.h , the Linked List defines two strucures:
//node type stored in lists
typedef struct ll_node{
struct ll_node * next; //next node in list
char * val; //string value stored in list
} ll_node_t;
//list_t struct to store a list
typedef struct{
ll_node_t * head; //pointer to the node at the head of the list
int size; //the number of nodes in the list
} llist_t;
The ``ll_node_t is a node within the linked list, storing the value (a char * string) and a
pointer to the next node. The llist_t` is a structure representation of the list, storing a pointer to the head of
the list and itʼs current size (number of nodes.
There are three functions that operate over lists, described below. In llist.c you implement these methods.
// Return a newly initialized, empty linked list
llist_t * ll_init();
//delete/deallocate a linked list
void ll_delete(llist_t * ll);
//insert the string v (duplicated vis strdup!) onto the front of the list
void ll_push(llist_t * ll, char * s);
Hash Map
The hashmap data strcucture is defined in hashmap.h and you will implemented in hashmap.c . The header file
containing the structure and functions can be found below (with comments).
#define HM_INIT_NUM_BUCKETS 16
#define HM_MAX_LOAD 0.75
2/24/2021 Project 1 | CS 2113 Software Engineering - Spring 2021
https://cs2113-s21.github.io/project/1 4/13
In the C file you will implement a non-public (as in not in the header file) function _resize()
void _resize(hashmap_t * hm)
which is called when the load is greater than 0.75.
Spellchecker
To help test your Hashmap and Linked List implementation, weʼve provided a simple interactive spellchecker
program that allows the user to type phrases (without punctuation) and it will spellcheck it. Hereʼs some sample
inputs and outputs, along with the compilation.
typedef struct{
llist_t ** buckets; //array of `buckets` each pointing to a list_t (see list.h)
int num_buckets; //how many buckets, or lenght of the bucket array (should always be a power of 2
int size; //how many items stored
} hashmap_t;
//initliaze a hashmap with INITIAL_BUCKETS number of buckets
hashmap_t * hm_init();
//delete/deallocate the hashmap
void hm_delete(hashmap_t * hm);
//add a string value to the hashmap
void hm_add(hashmap_t * hm, char * v);
//see if a string value is in the hashmap
bool hm_check(hashmap_t * hm, char * v);
$ make
gcc -Wall -Wno-unused-variable -g -c -o hashmap.o hashmap.c
gcc -Wall -Wno-unused-variable -g -c -o llist.o llist.c
gcc -Wall -Wno-unused-variable -g -o spellcheck spellcheck.c hashmap.o llist.o -lreadline -lm
gcc -Wall -Wno-unused-variable -g -c -o boggle.o boggle.c
gcc -Wall -Wno-unused-variable -g -o onePlayerBoggle onePlayerBoggle.c boggle.o hashmap.o llist.o -
$ ./spellcheck
ERROR: require dictionary file
$ ./spellcheck dictionary.txt
spellcheck > spellcheck all these words at once
SPELLCHECK -> not a word
ALL -> WORD
THESE -> WORD
WORDS -> WORD
AT -> WORD
ONCE -> WORD
spellcheck > or
OR -> WORD
spellcheck > one
ONE -> WORD
2/24/2021 Project 1 | CS 2113 Software Engineering - Spring 2021
https://cs2113-s21.github.io/project/1 5/13
Boggle Solver
Now that youʼre Hash Map and Linked List are working, letʼs use them to do something a bit more interesting —
finding all the words on a boggle board!
The boggle game structure and functions are defined in boggle.h and you will do most of your work in
boggle.c . A boggle instance is defined as a 5x5 grid of dice, where each dice displays a different character.
#define BOGGLE_DIMENSION 5
typedef struct {
char board[BOGGLE_DIMENSION][BOGGLE_DIMENSION]; //the boggle board
hashmap_t * dict; //dictionary mapping
} boggle_t;
When printed the board looks like
.-----------.
| S N T A Y |
| W N T E I |
| N QuI H I |
| N F O S U |
| E E H N L |
'-----------'
The goal is to find as many words (at least three letters long) by traversing from one dice to another in all
directions (left, right, up, down, and diagonal) without using a dice more than once. So for example QUIT is a
word found on the board, and so is QUITE . (You get a free ‘uʼ for your ‘Qʼ.)
A number of functions are implemented and provided for you in boggle.c , your main work will be completing the
bg_all_words() function, which will search the boggle board for all words 3 letters to 8 letters in length.
spellcheck > at
AT -> WORD
spellcheck > a
A -> WORD
spellcheck > time
TIME -> WORD
spellcheck > this adfasdfasdf is not a word
THIS -> WORD
ADFASDFASDF -> not a word
IS -> WORD
NOT -> WORD
A -> WORD
WORD -> WORD
spellcheck > nor !!!
NOR -> WORD
!!! -> not a word
spellcheck >
$ # type ^D to insert EOF to exit (or ^C)
2/24/2021 Project 1 | CS 2113 Software Engineering - Spring 2021
https://cs2113-s21.github.io/project/1 6/13
This is a recursive method that will explore outwards from a letter tile using depth first search. The idea is that
you start a tile, like Qu and then try all neighbors (via a recursive call), outward, adding letters as you go and
checking to see if you found a word. At somepoint you either search off the board or descended too far (checking
a 9 letter word), and the recursion returns to explore another path. An algorithmic description is provided in a
comment within boggle.c — see there for more details.
Once you complete, you can run the onePlayerBoggle program at a given random seed, like below:
aaviv@cs2113-vm:~/project-1a-inst$ ./onePlayerBoggle dictionary.txt 100
Total Points: 205
Note that the words are not alphabetical because hash tables are not ordered data structures.
Part (B) (Java Implementation) (30 Points)
In the second part of this project, you will implement your Hash Map and Linked List in Java using Object Oriented
Principles. Hereʼs a quick guide to the source files found in this part. There are comments throughout and TODO
marked where you should do your implementation. The same functions/methods on each of the objects as
described in part A still apply, but now in Java.
LList.java : Java class for implementing a Linked List. Additionally, you need to make your Linked List
iterable, such that it can be used in for(String s : list) — see details in the source file.
HMap.java : Java class for implementing your Hash Map. Additionally, you need to implement a
traversal() method that returns a LList of all the values stored in the HMap.
SpellCheck.java : Java class with a main method for testing your Lined List and HMap. Run it like so:
java SpellCheck dictionary.txt
Boggle.java : Java class representing a Boggle instance. You (again) will need to complete the
allWords() method.
OnePlayerBoggle.java : Java class with a main method for performing a boggle solve. Run it like so:
java OnePlayerBoggle dictionary.txt [seed]
where [seed] is replaced with the seed for the random number generator. If omitted, a random seed is
used.
Hereʼs some sample output of running the boggle solver with seed 100. Note that Java uses a different random
number generator, so it is different than above.
Total Points: 185
Bonus (part B) (up to +25 points)
Create a new branch in your repository called optimized and work within that branch — do not
make these changes on your main branch otherwise it may affect your grading of part B. Once
complete push this branch to the github and also open a issue with the title “BONUS Submission
Optimized”
Modify your HMap and LList implementations (or implement/use other data structures from Java stdlib) in part B,
as well as the boggle routines such that you optimize performance as best you can. The top 5 fastest boggle
solvers in the class will win recognition and bonus points:
1st place: 25 points
2nd/3rd place: 15 points
4th/5th place: 10 points
Some ideas/hints for optimizing your performance:
There are some combinations of letters that can never form words
You could avoid resizing your hashtable if you know how many items your were storing?
I/O is a drag
Java stdlib can be fast, but specialized data structures can be faster — depends on what your doing
Try running with java -Xss2m to profile your implementation
You can test your speed of your java solver by running it with
time java OnePlayerBoggle dictionary.txt
and look at the real time output.
Bonus (part B) (10 points)
Create a new branch in your repository called ordered and work within that branch — do not
make these changes on your main branch otherwise it may affect your grading of part B. Once
complete push this branch to the github and also open a issue with the title “BONUS Submission
Ordered”
Use Java standard library to replace/modify/etc your Hash Map and Linked List implementations with different data
structures provided there such that the output of the words from the OnePlayerBoggle are in sorted order.