Added assignment details as a README and LICENSEHEADmaster

2 files changed, 79 insertions, 0 deletions

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..c3e87d9
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Douglas B. Rumbaugh <dbrumbaugh@harrisburgu.edu>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright notice, 
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright 
+   notice, this list of conditions and the following disclaimer in the 
+   documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
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>