Add PA 09

Author: ErikSwan

pa09/README

@@ -0,0 +1,268 @@
+// Adapted from an assignment used Fall 2014 in EE 264 under Prof. Lu 
+
+// READING ASSIGNMENT: Chapter 20 of the online PDF text covers binary trees.
+
+
+// ~ Overview ~ //
+
+Recursion is an elegant method for solving many problems, and many data
+structures are actually easier to manipulate with recursive functions.
+In this assignment, we will see how a binary tree (actually any tree
+data structure) can utilize the power of recursion.
+
+// ~ Learning Goals ~ //
+
+(0) The main goal: learning the programming environment tools
+(1) Recursion
+(2) Binary (search) trees
+(3) Large datasets
+(4) Memory management
+
+Your solution will be a single
+(1) answer09.c
+
+We provide a tester program for FINAL EVALUATION to be run as follows:
+
+ > ./tester
+
+Don't get tempted and run this program before constructing your own tests.
+
+
+
+// ~ Binary (Search) Trees ~ //
+
+Practically, you may have enough background to solve the assignment
+without reading this section of the README, but it is required reading
+for deepening your understanding of binary trees.
+
+From Wikipedia: A binary tree is a tree data structure in which each
+node has at most two children (referred to as the left child and the
+right child).
+
+This is similar (and more general) to "linked lists", where nodes have
+at most one child.
+
+Linked List, 4 examples of increasing length:
+
+    O   head/tail   O   head        O   head        O   head
+                    |               |               |
+                    V               V               V
+                    O   tail        O               O
+                                    |               |
+                                    V               V
+                                    O   tail        O
+                                                    |
+                                                    V
+                                                    O   tail
+
+Binary Tree, 4 examples of increasing depth:
+
+    O   root        O   root       O   root            O   root
+                   / \           /   \              /     \
+                  O   O         O     O          O           O
+                left right     / \   / \       /   \       /   \
+                              O   O O   O     O     O     O     O
+                                             / \   / \   / \   / \
+                                            O   O O   O O   O O   O
+
+The above diagrams show *full* binary trees, where every node has
+either zero or two children. It is perfectly acceptable to have a node
+with one child somewhere in the tree:
+
+More Binary Trees:
+
+    O   root        O   root       O   root       O   root
+                   / \            / \            / \
+                  O   O          O   O          O   O
+                       \        /                \   \
+                        O      O                  O   O
+
+Note that every linked list is (conceptually) also a binary tree.
+
+NOTE: at each O in the above diagrams, data can be stored.  We are
+just showing the linkage structure relating the nodes, not any contents.
+
+These work well with recursion because the very definition of the data
+structure is actually recursive.  Consider this definition:
+
+A "Linked List" is either the NULL pointer, or a node whose next
+pointer points to a "Linked List".
+
+This defines the term "Linked List" in terms of itself.  There is a
+formal meaning for such definitions which we will not cover this
+semester, but in fact, it is formally interpreted to be exactly the
+type "Linked List" that you expect.  The recursive definition tells
+you that any list processing function can be defined for all linked
+lists by defining it for NULL and for a node pointing to a linked
+list.  IF the latter case can be defined by using the same function,
+voila, a recursive function emerges.
+
+Now consider the recursive definition of binary tree:
+
+A "binary tree" is either the NULL pointer, or a node with left and
+right children that are "binary trees".
+
+Again, the definition implies the construction of a recursive function
+that processes trees.  
+
+As long as the desired function on trees (or lists) can be naturally
+defined in terms of the results of the SAME function called on the
+children (or next pointer), then a recursive function is natural. The
+body of the function itself only has to consider one node and use
+recursion to handle the rest.
+
+i.e., if a recursive program can handle one node, then it can handle the
+entire tree.
+
+The relevant theory for why a binary tree is more efficient than a
+regular list is covered in future courses, but for a teaser, think
+about this: if you have a collection of N elements in a linked list,
+and you want to see if element X is in the list, then you need to
+compare X to every element in the list, a total of N
+comparisons. However, if you use a binary search tree, you only need
+to traverse down a single branch, and on average will make around
+log_2(N) comparisons. (i.e., log-base-2 of N.) What it means to
+"traverse down a single branch" will become clear as you write the
+code for this assignment.  In more technical terms, the worst-case
+behavior of lookup in a binary-search tree involves comparing at each
+node in the longest path from the root to a leaf, i.e. the worst-case
+runtime grows with the "depth" of the tree.  If the tree is well
+balanced (leaf nodes occur at similar depths on all paths), then this
+depth will be log_2(N), because at each node when you choose a child
+you eliminate about half the candidates, those that are below the
+other child.
+
+// ~ The Yelp Database as a Tree ~ //
+
+This assignment combines the power of binary search trees with a set of data
+that is as close to the real world as possible: Data about local businesses.
+Users of the website yelp (http://www.yelp.com) can post reviews and
+recommendation about their local restaurants and share them with the world.
+Yelp hosts about 57 million reviews for businesses catering to 132 million
+users a month, who constantly query their servers for information about their
+local businesses.
+
+One fundamental problem for companies with huge datasets like Yelp is
+retrieving information from a database. The user experience of the Yelp website
+would be unacceptable if, hypothetically, all of the data describing the
+businesses would be stored in a simple array or linked list: It would mean that
+for every search, the server would have to compare every single entry in the
+database to the search term.
+
+Of course, this is not how it is done in the real world, and this is where tree
+data structures like the binary search tree described above come in.
+
+The dataset you'll be working with is a small fraction of data pulled from
+Yelp's servers. The information available to you is:
+
+ - the name of the business
+ - the address of the business
+ - an average rating of the business on a scale of 1 through 4
+
+You will construct a binary tree from this dataset that is ordered according
+to the names of the businesses. Recall that there exists a certain C library
+that provides functions to compare two strings to each other. This will create
+a tree data structure with the following properties:
+
+(1) Each node's left subtree contains nodes with names "less than" "equal to"
+    its own name
+
+(2) Each node's right subtree contains nodes with names "greater than" its
+    own name
+
+(3) All left and right subtrees are binary search trees themselves.
+
+
+// ~ The Yelp Dataset File ~ //
+
+The dataset you'll be working with is a small fraction of the Yelp Academic
+dataset, which is itself a fraction of Yelp's database that was made public for
+use in academia. More information and a download for the full dataset can be
+found here: http://www.yelp.com/dataset_challenge
+
+The data was converted from the JSON format to a text file filled with
+tab-seperated values with the extension '.tsv'. There is a lot more information
+in the full dataset, but for this assignment, you will only use the average
+rating, the name, and the address. The file you're provided with, called
+'yelp_businesses.tsv' has information about 42153 businesses in the United
+States and should be read line by line.
+
+One line in the .tsv file lists one business and is structured like this:
+
+  [rating]\t[name]\t[address]\n
+
+In order to fill the fields of one node, you need to seperate a line according
+to the delimiter '\t'. Remember your explode() function from PA03? It could
+come in very handy for this assignment. If you want to use your explode 
+function from PA03, then you will need to copy and paste it somewhere into
+your answer09.c file. Of course, you don't HAVE to use explode(...) here, as
+long as you create the nodes properly and without memory leaks.
+
+// ~ Hints ~ //
+
+Chapter 20 of the online PDF text covers binary trees.
+
+----------------------------------------------------------------------
+
+(*) Even though a tree is not an array, it is still easy to "iterate"
+over all of the elements. Iteration means you want to visit every
+element once, and only once. You already know how to do this with an
+array:
+
+int myints[] = { 5, 3, 6, 7 };
+for(ind = 0; ind < 4; ++ind)
+   do_something_with(myints[ind]); // see, visit each element once and only once
+
+With trees, you choose either pre-order, in-order, or post-order
+traversal to do the same thing. Please look these up in the class notes.
+
+----------------------------------------------------------------------
+
+(*) If you get stuck getting started, then try writing just
+create_node(...), and a print_tree(...) function. You should
+then be able to do the following:
+
+// Step 1 //
+Create and print trees like so:
+
+int main(int argc, char * * argv)
+{
+   // calls to create_node below needs to use ustrdup() on each string, omitted for clarity
+   BusinessNode * root = create_node("5.0", "random name", "random address");
+   root->left = create_node("3.5", "another name", "another address");
+   root->right = create_node("4.0", "yet another name", "some address");
+   root->left->right = create_node("1.5", "name 3", "address 3");
+   print_tree(root);
+   return 0;
+}
+
+// Step 2 //
+Write destroy_tree(...). You should now have no memory leaks or
+errors.
+
+// Step 3 //
+Write tree_insert(...) and make sure it
+always works no matter what is thrown at it.
+
+// Step 4 //
+Write load_tree_from_file(...), which calls insert in a loop.
+
+// Step 5 //
+Write tree_search_name() and try to search for some Businesses that you know
+are in the tree.
+
+At this stage you will be reasonably close to completing the assignment.
+
+----------------------------------------------------------------------
+
+(*) To test the load_tree_from_file(...) function, it makes sense to work with
+a smaller subset of the data. To read the first 5 lines of
+'yelp_businesses.tsv' into a new file called 'shortfile.tsv', use the following
+command:
+
+ > cat yelp_businesses.tsv | head -n 5 > shortfile.tsv
+
+Use "man cat" and "man head" to understand these two commands.  This
+simple shell command also uses "pipes" (|) and "output redirection"
+(>), both of which are simple and easy to understand and very very
+useful.