From fc16e380f3728a80bd4d7845bf6a04b76fa4fb16 Mon Sep 17 00:00:00 2001
From: "Douglas B. Rumbaugh" <doug@douglasrumbaugh.com>
Date: Mon, 3 Nov 2025 12:03:39 -0500
Subject: Added assignment details as a README and LICENSE

---
 README.html | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 README.html

(limited to 'README.html')

diff --git a/README.html b/README.html
new file mode 100644
index 0000000..4b1a1af
--- /dev/null
+++ b/README.html
@@ -0,0 +1,49 @@
+<p>Unlike in Java or Python, C has a very limited standard library which lacks general collections/data structures. This means that, if you need a particular structure, you'll need to either include an external library, or implement it yourself. In this project, you'll write a very useful data structure called a hash map, which will be useful to you in future assignments. As a starting point, <a class="instructure_file_link inline_disabled" title="project-1.tar.gz" href="https://harrisburgu.instructure.com/courses/18692/files/4818806?wrap=1" target="_blank" rel="noopener" data-canvas-previewable="false" data-api-endpoint="https://harrisburgu.instructure.com/api/v1/courses/18692/files/4818806" data-api-returntype="File">download and extract this tarball.</a> It includes the following basic directory structure,</p>
+<pre>.
+|-- include
+|   |-- hashfuncs.h
+|   `-- strmap.h
+|-- src
+|   `-- strmap.c
+`-- tests
+    `-- strmap_tests.c
+</pre>
+<p>The interfaces that you must implement are defined in <tt>include/strmap.h</tt>. <strong>DO NOT EDIT THIS FILE.</strong> You should implement this functions, along with any internal helper functions or structures you may want to add, in <tt>src/strmap.c</tt>. I've provided a suite of unit tests to verify the functionality of your data structure in <tt>tests/strmap_tests.c</tt>. <strong>DO NOT EDIT THIS FILE</strong> either.</p>
+<h2>Specific Tasks</h2>
+<p>For this project, you must complete the following tasks</p>
+<ul>
+    <li>Implement the required functions in <tt>src/strmap.c</tt></li>
+    <li>Create a Makefile which builds a static library, <tt>lib/libmap.a</tt>, and builds the unit test program in <tt>bin/strmap-tests</tt></li>
+    <li>Ensure that all unit tests pass</li>
+</ul>
+<h2>Submission</h2>
+<p>Create a tarball containing the following files,</p>
+<pre>project-1
+|-- Makefile
+|-- include
+|   |-- hashfuncs.h
+|   `-- strmap.h
+|-- src
+|   `-- strmap.c
+`-- tests
+    `-- strmap_tests.c
+</pre>
+<p>and upload it to Canvas by the deadline. Do not alter the provided include or unit test files.</p>
+<h2>Tips and Advice</h2>
+<ul>
+    <li>Make sure that any functions or globals that should be internal to your library (private helpers, etc.) are defined as <tt>static</tt>. Anything in the global namespace of <tt>src/strmap.c</tt> that is not static should be defined in the header.</li>
+    <li>I've provided two different hash functions for your use. The first one, <tt>hash_key</tt> is a generally appropriate hash function that you'd actually use in a real map. The second, <tt>test_hash</tt> will only map elements into the first three buckets of the hash table, regardless of how many buckets there are. It is provided to force hash collisions in an easy to predict manner for testing and debugging purposes.</li>
+    <li>There's no requirement for the hash table to resize. You can allocate it to a single, static number of buckets and run with it. Just understand that fixed-size hash tables will see large performance degradation as the number of records within them grows. If you'd like, you can implement dynamic resizing similarly to how you would implement a dynamic array. If you do so, remember to rehash every element within the map.</li>
+    <li>Make sure that you handle memory allocation failures. I will be overriding your default <tt>malloc</tt> with one that lets me inject failures to test your error handling.</li>
+    <li>Ensure that allocated memory is eventually freed, even on error paths. I will be testing with induced allocation failures and memory instrumentation to search for memory leaks even on error handling paths.&nbsp;</li>
+    <li>In order to compile the unit tests, you will need to link in the unit test library, and include pthreads. The flags for this are,
+        <ul>
+            <li><tt>-lcheck</tt></li>
+            <li><tt>-pthread</tt></li>
+        </ul>
+    </li>
+</ul>
+<h2>Errata</h2>
+<ul>
+    <li>Some compilers might not like the approach I initially used to suppress unused parameter warnings in <tt>include/hashfuncs.h</tt>. If you have problems, <a class="instructure_file_link instructure_scribd_file inline_disabled" title="patch.diff" href="https://harrisburgu.instructure.com/courses/18692/files/4832576?wrap=1" target="_blank" rel="noopener" data-canvas-previewable="false" data-api-endpoint="https://harrisburgu.instructure.com/api/v1/courses/18692/files/4832576" data-api-returntype="File">try applying this patch</a>. It doesn't change anything materially--just switches over to an older technique for suppressing these warnings with better compatibility. [9/4/2025]</li>
+</ul>
-- 
cgit v1.2.3