admin/C-Macro-Collections
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Leonardo committed 2020-04-17 01:33:49 -03:00
1 parent 2a7aa8e4cb
commit 6f1fb7554e
40 files changed
+466 -43
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/print.html
+67 -4
View File
@@ -83,7 +83,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div id="sidebar-scrollbox" class="sidebar-scrollbox">
<ol class="chapter"><li class="expanded "><a href="Introduction/introduction.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li><ol class="section"><li class="expanded "><a href="Introduction/why_this_library.html"><strong aria-hidden="true">1.1.</strong> Why this library</a></li><li class="expanded "><a href="Introduction/how_to_install.html"><strong aria-hidden="true">1.2.</strong> How to install</a></li><li class="expanded "><a href="Introduction/library_structure.html"><strong aria-hidden="true">1.3.</strong> Library structure</a></li><li class="expanded "><a href="Introduction/understanding_the_library.html"><strong aria-hidden="true">1.4.</strong> Understanding the library</a></li><li class="expanded "><a href="Introduction/how_to_use_the_library.html"><strong aria-hidden="true">1.5.</strong> How to use the library</a></li></ol></li><li class="expanded "><a href="Overview/index.html"><strong aria-hidden="true">2.</strong> Overview</a></li><li><ol class="section"><li class="expanded "><a href="Overview/collections_overview.html"><strong aria-hidden="true">2.1.</strong> Collections Overview</a></li><li class="expanded "><a href="Overview/features_overview.html"><strong aria-hidden="true">2.2.</strong> Features Overview</a></li></ol></li><li class="expanded "><a href="cor/index.html"><strong aria-hidden="true">3.</strong> cor</a></li><li><ol class="section"><li class="expanded "><a href="cor/callbacks/index.html"><strong aria-hidden="true">3.1.</strong> Callbacks</a></li><li class="expanded "><a href="cor/custom_allocation/index.html"><strong aria-hidden="true">3.2.</strong> Custom allocation</a></li><li class="expanded "><a href="cor/functions_table/index.html"><strong aria-hidden="true">3.3.</strong> Functions Table</a></li><li class="expanded "><a href="cor/iterators/index.html"><strong aria-hidden="true">3.4.</strong> Iterators</a></li></ol></li><li class="expanded "><a href="cmc/index.html"><strong aria-hidden="true">4.</strong> cmc</a></li><li><ol class="section"><li class="expanded "><a href="cmc/deque.h/index.html"><strong aria-hidden="true">4.1.</strong> deque.h</a></li></ol></li><li class="expanded "><a href="dev/index.html"><strong aria-hidden="true">5.</strong> dev</a></li><li class="expanded "><a href="sac/index.html"><strong aria-hidden="true">6.</strong> sac</a></li><li class="expanded "><a href="utl/index.html"><strong aria-hidden="true">7.</strong> utl</a></li><li><ol class="section"><li class="expanded "><a href="utl/assert.h/index.html"><strong aria-hidden="true">7.1.</strong> assert.h</a></li><li><ol class="section"><li class="expanded "><a href="utl/assert.h/overview.html"><strong aria-hidden="true">7.1.1.</strong> Overview</a></li><li class="expanded "><a href="utl/assert.h/valued_assertions.html"><strong aria-hidden="true">7.1.2.</strong> Valued Assertions</a></li><li class="expanded "><a href="utl/assert.h/generic_assertions.html"><strong aria-hidden="true">7.1.3.</strong> Generic Assertions</a></li></ol></li><li class="expanded "><a href="utl/foreach.h/index.html"><strong aria-hidden="true">7.2.</strong> foreach.h</a></li><li class="expanded "><a href="utl/futils.h/index.html"><strong aria-hidden="true">7.3.</strong> futils.h</a></li><li class="expanded "><a href="utl/log.h/index.html"><strong aria-hidden="true">7.4.</strong> log.h</a></li><li><ol class="section"><li class="expanded "><a href="utl/log.h/log_functions.html"><strong aria-hidden="true">7.4.1.</strong> Log Functions</a></li><li class="expanded "><a href="utl/log.h/configuration.html"><strong aria-hidden="true">7.4.2.</strong> Configuration</a></li><li class="expanded "><a href="utl/log.h/meanings.html"><strong aria-hidden="true">7.4.3.</strong> Meanings</a></li></ol></li><li class="expanded "><a href="utl/test.h/index.html"><strong aria-hidden="true">7.5.</strong> test.h</a></li><li class="expanded "><a href="utl/timer.h/index.html"><strong aria-hidden="true">7.6.</strong> timer.h</a></li></ol></li><li class="expanded "><a href="Examples/examples.html"><strong aria-hidden="true">8.</strong> Examples</a></li></ol>
<ol class="chapter"><li class="expanded "><a href="Introduction/introduction.html"><strong aria-hidden="true">1.</strong> Introduction</a></li><li><ol class="section"><li class="expanded "><a href="Introduction/why_this_library.html"><strong aria-hidden="true">1.1.</strong> Why this library</a></li><li class="expanded "><a href="Introduction/how_to_install.html"><strong aria-hidden="true">1.2.</strong> How to install</a></li><li class="expanded "><a href="Introduction/library_structure.html"><strong aria-hidden="true">1.3.</strong> Library structure</a></li><li class="expanded "><a href="Introduction/understanding_the_library.html"><strong aria-hidden="true">1.4.</strong> Understanding the library</a></li><li class="expanded "><a href="Introduction/how_to_use_the_library.html"><strong aria-hidden="true">1.5.</strong> How to use the library</a></li></ol></li><li class="expanded "><a href="Overview/index.html"><strong aria-hidden="true">2.</strong> Overview</a></li><li><ol class="section"><li class="expanded "><a href="Overview/collections_overview.html"><strong aria-hidden="true">2.1.</strong> Collections Overview</a></li><li class="expanded "><a href="Overview/features_overview.html"><strong aria-hidden="true">2.2.</strong> Features Overview</a></li></ol></li><li class="expanded "><a href="cor/index.html"><strong aria-hidden="true">3.</strong> cor</a></li><li><ol class="section"><li class="expanded "><a href="cor/callbacks/index.html"><strong aria-hidden="true">3.1.</strong> Callbacks</a></li><li class="expanded "><a href="cor/custom_allocation/index.html"><strong aria-hidden="true">3.2.</strong> Custom allocation</a></li><li class="expanded "><a href="cor/error_codes/index.html"><strong aria-hidden="true">3.3.</strong> Error Codes</a></li><li class="expanded "><a href="cor/functions_table/index.html"><strong aria-hidden="true">3.4.</strong> Functions Table</a></li><li class="expanded "><a href="cor/iterators/index.html"><strong aria-hidden="true">3.5.</strong> Iterators</a></li></ol></li><li class="expanded "><a href="cmc/index.html"><strong aria-hidden="true">4.</strong> cmc</a></li><li><ol class="section"><li class="expanded "><a href="cmc/deque.h/index.html"><strong aria-hidden="true">4.1.</strong> deque.h</a></li></ol></li><li class="expanded "><a href="dev/index.html"><strong aria-hidden="true">5.</strong> dev</a></li><li class="expanded "><a href="sac/index.html"><strong aria-hidden="true">6.</strong> sac</a></li><li class="expanded "><a href="utl/index.html"><strong aria-hidden="true">7.</strong> utl</a></li><li><ol class="section"><li class="expanded "><a href="utl/assert.h/index.html"><strong aria-hidden="true">7.1.</strong> assert.h</a></li><li><ol class="section"><li class="expanded "><a href="utl/assert.h/overview.html"><strong aria-hidden="true">7.1.1.</strong> Overview</a></li><li class="expanded "><a href="utl/assert.h/valued_assertions.html"><strong aria-hidden="true">7.1.2.</strong> Valued Assertions</a></li><li class="expanded "><a href="utl/assert.h/generic_assertions.html"><strong aria-hidden="true">7.1.3.</strong> Generic Assertions</a></li></ol></li><li class="expanded "><a href="utl/foreach.h/index.html"><strong aria-hidden="true">7.2.</strong> foreach.h</a></li><li class="expanded "><a href="utl/futils.h/index.html"><strong aria-hidden="true">7.3.</strong> futils.h</a></li><li class="expanded "><a href="utl/log.h/index.html"><strong aria-hidden="true">7.4.</strong> log.h</a></li><li><ol class="section"><li class="expanded "><a href="utl/log.h/log_functions.html"><strong aria-hidden="true">7.4.1.</strong> Log Functions</a></li><li class="expanded "><a href="utl/log.h/configuration.html"><strong aria-hidden="true">7.4.2.</strong> Configuration</a></li><li class="expanded "><a href="utl/log.h/meanings.html"><strong aria-hidden="true">7.4.3.</strong> Meanings</a></li></ol></li><li class="expanded "><a href="utl/test.h/index.html"><strong aria-hidden="true">7.5.</strong> test.h</a></li><li class="expanded "><a href="utl/timer.h/index.html"><strong aria-hidden="true">7.6.</strong> timer.h</a></li></ol></li><li class="expanded "><a href="Examples/examples.html"><strong aria-hidden="true">8.</strong> Examples</a></li></ol>
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
@@ -271,6 +271,7 @@ struct SNAME##_iter *PFX##_iter_new(struct SNAME *target);
<table><thead><tr><th>Feature</th><th>Description</th></tr></thead><tbody>
<tr><td><a href="Overview/../cor/callbacks/index.html">Callbacks</a></td><td>Callbacks are functions that are called when an operation is successful. These operations are divided in 5 categories (create, read, update, delete, resize).</td></tr>
<tr><td><a href="Overview/../cor/custom_allocation/index.html">Custom Allocation</a></td><td>Allows you to use your own custom dynamic memory allocation functions inside the collections.</td></tr>
<tr><td><a href="Overview/../cor/error_codes/index.html">Error Codes</a></td><td>Error codes that can be used to treat certain common errors when operating on a collection.</td></tr>
<tr><td><a href="Overview/../cor/functions_table/index.html">Functions Table</a></td><td>A standard way to access required behaviors from the custom data types. Things like hash, comparison, freeing from memory if needed, etc.</td></tr>
<tr><td><a href="Overview/../cor/iterators/index.html">Iterators</a></td><td>Iterators are a simplified access to the values of a collection.</td></tr>
</tbody></table>
@@ -406,6 +407,68 @@ int main(void)
printf(&quot;Total bytes allocated : %&quot; PRIuMAX &quot;\n&quot;, total);
}
</code></pre>
<h1><a class="header" href="#error-codes" id="error-codes">Error Codes</a></h1>
<p>Error codes are ways to signal errors or success. It is accessed through the <code>flag</code> component of a <code>struct</code> or through a function that is present in every collection:</p>
<pre><code class="language-c">int PFX##_flag(struct SNAME *_collection_);
</code></pre>
<p>Some functions have a return type of <code>bool</code> indicating if it exited successfully or not. These error codes can be used for further error handling.</p>
<h2><a class="header" href="#cmc_flags" id="cmc_flags">cmc_flags</a></h2>
<p>It is a global <code>struct</code> with default values for error codes.</p>
<pre><code class="language-c">static struct
{
int OK;
int ALLOC;
int EMPTY;
int NOT_FOUND;
int INVALID;
int RANGE;
int DUPLICATE;
int ERROR;
} cmc_flags = { 0, 1, 2, 3, 4, 5, 6, 7 };
</code></pre>
<ul>
<li><code>OK</code> - No errors. The operation exited successfully.</li>
<li><code>ALLOC</code> - Allocation failed.</li>
<li><code>EMPTY</code> - The collection is empty when it shouldn't.</li>
<li><code>NOT_FOUND</code> - Key or value not found.</li>
<li><code>INVALID</code> - Invalid argument or operation given the collection's state</li>
<li><code>RANGE</code> - Index out of range.</li>
<li><code>DUPLICATE</code> - Duplicate key or value.</li>
<li><code>ERROR</code> - Generic error. Usually caused by algorithm errors.</li>
</ul>
<h2><a class="header" href="#cmc_flags_to_str" id="cmc_flags_to_str">cmc_flags_to_str</a></h2>
<p>Maps the integer representation of error codes to their character representation.</p>
<pre><code class="language-c">const char *cmc_flags_to_str[8] = { &quot;OK&quot;, &quot;ALLOC&quot;, &quot;EMPTY&quot;,
&quot;NOT_FOUND&quot;, &quot;INVALID&quot;, &quot;RANGE&quot;,
&quot;DUPLICATE&quot;, &quot;ERROR&quot; };
</code></pre>
<h2><a class="header" href="#example-2" id="example-2">Example</a></h2>
<pre><code class="language-c">#include &quot;cmc/treeset.h&quot;
#include &quot;utl/futils.h&quot; // cmc_i32_cmp
// Generate a sorted set of integers
CMC_GENERATE_TREESET(tset, sortedset, int)
int main(void)
{
struct sortedset *set =
tset_new(&amp;(struct sortedset_fval){ .cmp = cmc_i32_cmp });
if (!tset_insert(set, 10))
printf(&quot;Error! %s\n&quot;, cmc_flags_to_str[tset_flag(set)]);
if (!tset_insert(set, 10))
printf(&quot;Error! %s\n&quot;, cmc_flags_to_str[tset_flag(set)]);
if (!tset_remove(set, 10))
printf(&quot;Error! %s\n&quot;, cmc_flags_to_str[tset_flag(set)]);
if (!tset_remove(set, 10))
printf(&quot;Error! %s\n&quot;, cmc_flags_to_str[tset_flag(set)]);
tset_free(set);
}
</code></pre>
<h1><a class="header" href="#functions-table" id="functions-table">Functions Table</a></h1>
<p>Functions Table is a <code>struct</code> with function pointers that are used to extract behavior from a custom data type. This exists because an <code>int</code> or a <code>char *</code> or <code>struct my_data_type</code> don't have default hash functions or ways to compare between them. This could be achieved with <a href="https://en.wikipedia.org/wiki/Operator_overloading">operator overloading</a> but C doesn't have that. Hence, Functions Table was created to provide a single access point to extract these behaviors for <strong>any</strong> data type.</p>
<p>Some functions are optional and others are needed in order for a collection to operate. Say you want a HashMap. There are two required functions: <code>hash</code> and <code>cmp</code> (comparator). Without them it is impossible to know how to hash your custom that type (it could be anything). This means you can also customize the collection by using different hash functions.</p>
@@ -911,7 +974,7 @@ int main(void)
<li><code>ITERNAME</code> - Iterator variable name</li>
<li><code>TARGET</code> - Target collection variable name</li>
</ul>
<h2><a class="header" href="#example-2" id="example-2">Example</a></h2>
<h2><a class="header" href="#example-3" id="example-3">Example</a></h2>
<pre><code class="language-c">#include &quot;cmc/list.h&quot;
#include &quot;utl/foreach.h&quot;
@@ -1192,7 +1255,7 @@ int main(void)
</code></pre>
<h2><a class="header" href="#cmc_test_color" id="cmc_test_color">CMC_TEST_COLOR</a></h2>
<p>Define this macro if you wish to have color output from the messages printed by each test. Note that a Unit Test need to have <code>VERBOSE</code> equal to <code>true</code>.</p>
<h2><a class="header" href="#example-3" id="example-3">Example</a></h2>
<h2><a class="header" href="#example-4" id="example-4">Example</a></h2>
<pre><code class="language-c">#include &quot;utl/test.h&quot;
CMC_CREATE_UNIT(check_math, true, {
@@ -1252,7 +1315,7 @@ int main(void)
<ul>
<li><code>timer</code> - A <code>struct cmc_timer</code> variable</li>
</ul>
<h2><a class="header" href="#example-4" id="example-4">Example</a></h2>
<h2><a class="header" href="#example-5" id="example-5">Example</a></h2>
<pre><code class="language-c">#include &lt;stdio.h&gt;
#include &quot;utl/timer.h&quot;