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

Documentation for foreach.h, test.h, timer.h and other changes

Browse Source 
Change in timer.h. Now cmc_timer_stop will calculate the result so goodbye cmc_timer_calc
This commit is contained in:
Leonardo committed 2020-04-10 22:21:47 -03:00
1 parent aa214d179e
commit 67590790c4
12 files changed
+451 -36
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/print.html
+134 -4
View File
@@ -588,12 +588,23 @@ int main(void)
<li><code>CMC_FOREACH</code> - Goes from the beginning of a Collection to the end</li>
<li><code>CMC_FOREAC_REV</code> - Goes from the end of a Collection to the beginning</li>
</ul>
<h2><a class="header" href="#parameters" id="parameters">Parameters</a></h2>
<h2><a class="header" href="#cmc_foreach" id="cmc_foreach">CMC_FOREACH</a></h2>
<pre><code class="language-c">#define CMC_FOREACH(PFX, SNAME, ITERNAME, TARGET)
</code></pre>
<ul>
<li><code>PFX</code> - Functions prefix</li>
<li><code>SNAME</code> - Struct name</li>
<li><code>ITERNAME</code> - Iterator variable name</li>
<li><code>TARGET</code> - Target variable</li>
<li><code>TARGET</code> - Target collection variable name</li>
</ul>
<h2><a class="header" href="#cmc_foreach_rev" id="cmc_foreach_rev">CMC_FOREACH_REV</a></h2>
<pre><code class="language-c">#define CMC_FOREACH_REV(PFX, SNAME, ITERNAME, TARGET)
</code></pre>
<ul>
<li><code>PFX</code> - Functions prefix</li>
<li><code>SNAME</code> - Struct name</li>
<li><code>ITERNAME</code> - Iterator variable name</li>
<li><code>TARGET</code> - Target collection variable name</li>
</ul>
<h1><a class="header" href="#logh" id="logh">log.h</a></h1>
<p>Simple and customizable logging macros. Messages can have a custom logging level and a custom file output. This customization can be done via the global variable <a href="utl/log.h/configuration.html#cmc_log_config"><code>cmc_log_config</code></a>. Logs are outputted to <code>stderr</code>.</p>
@@ -732,9 +743,128 @@ int main(void)
<li><strong>FATAL</strong> - This will probably be the last logging message before your program crashes or goes into madness. Fatal errors are commonly attributed to dereferencing NULL pointers.</li>
</ul>
<h1><a class="header" href="#testh" id="testh">test.h</a></h1>
<p>Simple unit test utility.</p>
<p>A simple <a href="https://en.wikipedia.org/wiki/Unit_testing">Unit Test</a> utility used by the C Macro Collections Library. It has two main components: a Unit and a Test.</p>
<p>This utility uses two other libraries defined in the C Macro Collections library:</p>
<ul>
<li><a href="utl/test.h/../assert.h/index.html"><code>assert.h</code></a></li>
<li><a href="utl/test.h/../timer.h/index.html"><code>timer.h</code></a></li>
</ul>
<p>When a test is created inside a unit, it will first set the global variable <a href="utl/test.h/../assert.h/index.html#cmc_assert_state"><code>cmc_assert_state</code></a> to <code>true</code>. Then, inside the test you can use the assertions provided by the <code>assert.h</code> library to pass or fail a unit test automatically. By the end of a test the variable will be checked. If <code>false</code> it means that a certain assertion failed.</p>
<p>The runtime of each Unit Test is calculated using the <code>timer.h</code> library.</p>
<h2><a class="header" href="#cmc_create_unit" id="cmc_create_unit">CMC_CREATE_UNIT</a></h2>
<p>Creates a Unit that can contain tests.</p>
<pre><code class="language-c">#define CMC_CREATE_UNIT(UNAME, VERBOSE, BODY)
</code></pre>
<ul>
<li><code>UNAME</code> - Unit name. This needs to be a valid function name!</li>
<li><code>VERBOSE</code> - Either <code>true</code> or <code>false</code>. If <code>true</code>, prints every message of <code>PASSED</code> or <code>FAILED</code> from each test</li>
<li><code>BODY</code> - A block of code containing tests</li>
</ul>
<h2><a class="header" href="#cmc_create_test" id="cmc_create_test">CMC_CREATE_TEST</a></h2>
<p>Creates a test within a unit. This macro can only be used inside the <code>BODY</code> of a <code>CMC_CREATE_UNIT</code> since it uses local variables allocated by the latter.</p>
<pre><code class="language-c">#define CMC_CREATE_TEST(TNAME, BODY)
</code></pre>
<ul>
<li><code>TNAME</code> - Test name</li>
<li><code>BODY</code> - A block of code containing the test itself</li>
</ul>
<p>Inside a test you can use the assertions from <code>assert.h</code> to automatically pass or fail a test.</p>
<h2><a class="header" href="#cmc_test_abort" id="cmc_test_abort">CMC_TEST_ABORT</a></h2>
<p>Aborts a unit test. This will jump to a <code>goto</code> located at the end of the Unit Test.</p>
<h2><a class="header" href="#cmc_test_info" id="cmc_test_info">cmc_test_info</a></h2>
<p>Contains information about a Unit Test. Used internally.</p>
<pre><code class="language-c">struct cmc_test_info
{
uintmax_t total;
uintmax_t passed;
uintmax_t failed;
bool aborted;
bool verbose;
};
</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" id="example">Example</a></h2>
<pre><code class="language-c">#include &quot;utl/test.h&quot;
CMC_CREATE_UNIT(check_math, true, {
CMC_CREATE_TEST(summation, {
// assert.h already comes with test.h
cmc_assert_equals(int32_t, 4, 2 + 2);
});
CMC_CREATE_TEST(subtraction, {
cmc_assert_equals(int32_t, -1, 2 - 3);
});
CMC_CREATE_TEST(this will fail, {
// test names can be text as long as they don't have a comma
cmc_assert_greater(double, 1.0, 0.0);
});
CMC_CREATE_TEST(fish, {
// You can also manually fail a test
if (strcmp(&quot;2 + 2&quot;, &quot;fish&quot;) != 0)
cmc_assert_state = false;
});
});
int main(void)
{
// returns how many tests failed
return check_math();
}
</code></pre>
<h1><a class="header" href="#timerh" id="timerh">timer.h</a></h1>
<p>Simple code execution utility.</p>
<p>A very simple library that encapsulates <code>clock()</code> from <code>&lt;time.h&gt;</code>, making life easier.</p>
<h2><a class="header" href="#cmc_timer" id="cmc_timer">cmc_timer</a></h2>
<pre><code class="language-c">struct cmc_timer
{
clock_t start;
clock_t stop;
double result;
};
</code></pre>
<ul>
<li><code>clock_t start</code> - Start of timing</li>
<li><code>clock_t stop</code> - End of timing</li>
<li><code>double result</code> - Result in milliseconds</li>
</ul>
<h2><a class="header" href="#cmc_timer_start" id="cmc_timer_start">cmc_timer_start</a></h2>
<p>Starts the timer by setting <code>start</code> with <code>clock()</code>.</p>
<pre><code class="language-c">#define cmc_timer_start(timer)
</code></pre>
<ul>
<li><code>timer</code> - A <code>struct cmc_timer</code> variable</li>
</ul>
<h2><a class="header" href="#cmc_timer_stop" id="cmc_timer_stop">cmc_timer_stop</a></h2>
<p>Sets the <code>stop</code> variable with <code>clock()</code> and calculates the <code>result</code> in milliseconds.</p>
<pre><code class="language-c">#define cmc_timer_start(timer)
</code></pre>
<ul>
<li><code>timer</code> - A <code>struct cmc_timer</code> variable</li>
</ul>
<h2><a class="header" href="#example-1" id="example-1">Example</a></h2>
<pre><code class="language-c">#include &lt;stdio.h&gt;
#include &quot;utl/timer.h&quot;
int main(void)
{
struct cmc_timer t;
cmc_timer_start(t);
size_t total = 0;
for (size_t i = 0; i &lt; 1000000000; i++)
total += i;
cmc_timer_stop(t);
printf(&quot;Sum took %.0lf milliseconds to calculate\n&quot;, t.result);
}
</code></pre>
<h1><a class="header" href="#minimal-example" id="minimal-example">Minimal Example</a></h1>
<p>(TODO this example is currently outdated)</p>
<p>Lets create a list of type <code>int</code>, add some elements to it and get the sum of all the elements printed on the screen.</p>