<!DOCTYPE html>
<html>
<h1>zap</h1>
<p>A library for algorithmics.</p>
<p><i>Note: This library is still in it's early stages and is NOT anywhere near being fully optimised.</i></p>
<br />
<h2>Building and installation</h2>
<p>The provided makefile has been tested to work with both GNU Make and BSD Make.</p>
<p>The default target builds the static library file (located at <i>zap/libzap.a</i>). The target <i>clean</i> removes object files, whilst <i>purge</i> removes object files and the static library file.</p>
<p>Currently, zap doesn't support being compiled as a shared library out of the box, but the makefile could be modified to allow this.</p>
<p>The <i>install</i> target installs the headers to <i>$(HDRDIR)</i> and the library file to <i>$(LIBDIR)</i>.</p>
<p>Instructions for building the test program may be found on the first line of <i>test.c</i>.</p>
<h2>Documentation</h2>
<h3>abs</h3>
<h4>Synopsis</h4>
<code>#include <zap/math.h><br />signed char zap_abs_c(signed char val);<br />int zap_abs_i(int val);<br />long zap_abs_l(long val);<br />long long zap_abs_ll(long long val);<br />short zap_abs_s(short val);</code>
<h4>Description</h4>
<p>Returns the absolute value of <i>val</i>.</p>
<br />
<h3>fma</h3>
<h4>Synopsis</h4>
<code>#include <zap/math.h><br />signed char zap_fma_c(signed char a,signed char b,signed char c);<br/>int zap_fma_i(int a,int b,int c);<br/>long zap_fma_l(long a,long b,long c);<br/>long long zap_fma_ll(long long a,long long b,long long c);<br/>short zap_fma_s(short a,short b,short c);<br/>unsigned char zap_fma_uc(unsigned char a,unsigned char b,unsigned char c);<br/>unsigned int zap_fma_ui(unsigned int a,unsigned int b,unsigned int c);<br/>unsigned long zap_fma_ul( unsigned long a,unsigned long b,unsigned long c);<br/>unsigned long long zap_fma_ull(unsigned long long a,unsigned long long b,unsigned long long c);<br/>unsigned short zap_fma_us( unsigned short a,unsigned short b,unsigned short c);</code>
<h4>Description</h4>
<p>Returns the the fused multiply-add of <i>a</i>, <i>b</i>, and <i>c</i>.</p>
<br />
<h3>fndbyte</h3>
<h4>Synopsis</h4>
<code>#include <zap/mem.h><br />size_t zap_fndbtyte(void const * ptr,size_t num,unsigned char byte);</code>
<h4>Description</h4>
<p>Searches for the byte-value <i>byte</i> in the array pointed to by <i>ptr</i> within the bounds of <i>num</i>.</p>
<p>If <i>ptr</i> is not a valid pointer to a null-terminated string, the behaviour is undefined.</p>
<p>If <i>num</i> is larger (but not smaller) than the number of bytes in the array, the behaviour is undefined.</p>
<p>If the byte-value is found within the domain, the position of it's first occurrence (starting at zero) is returned. Otherwise, <i>SIZE_MAX</i> is returned.</p>
<br />
<h3>fndchr</h3>
<h4>Synopsis</h4>
<code>#include <zap/mem.h><br />size_t zap_fndchr(char const * str,char chr);</code>
<h4>Description</h4>
<p>Searches for the character <i>chr</i> in the string <i>str</i>.</p>
<p>If the character is found in the string, the position of it's first occurrence (starting at zero) is returned. Otherwise, <i>SIZE_MAX</i> is returned.</p>
<p>If <i>str</i> is not a valid pointer to a null-terminated string, the behaviour is undefined.</p>
<br />
<h3>foreach</h3>
<h4>Synopsis</h4>
<code>#include <zap/mem.h><br />void zap_foreach(void * ptr,size_t sz,size_t num,void (* fn)(void *),void * * rem);</code>
<h4>Description</h4>
<p>Iterates through the array pointed to by <i>ptr</i>, invoking the function <i>fn</i> with a pointer to the current element. Each pointer value after the first is equal to the previous plus <i>sz</i>.</p>
<p>If the pointed-to object of <i>rem</i> is not a null pointer, the iterations are started from that address. If <i>fn</i> throws an exception, the current position is written to the pointed-to object of <i>rem</i> (unless <i>rem</i> is a null pointer) and <i>foreach</i> returns the control-flow to the caller via this exception.</p>
<p>If the expression <code>(sz * num)</code> is not a valid object size, the behaviour is undefined.</p>
<p>If <i>fn</i> is not a valid pointer to a function with C language linkage, the behaviour is undefined.</p>
<p>If <i>rem</i> is not a null pointer and the pointed-to object is not initialised to <i>NULL</i> before the call to <i>foreach</i>, the behaviour is undefined.</p>
<br />
<h3>memcmp</h3>
<h4>Synopsis</h4>
<code>#include <zap/mem.h><br />int_least8_t zap_memcmp(void const * lptr,size_t num,void const * rptr);</code>
<h4>Description</h4>
<p>Compares <i>num</i>-bytes of the arrays pointed to by <i>lptr</i> and <i>rptr</i>.</p>
<p>The returned value is determined by the first byte found to be different in the two arrays. If the byte has a larger value in <i>lptr</i>, a negative (less than zero) value is returned. If it's the other way, a positive (greater than zero) value is returned. Otherwise (the arrays where represented the same), zero is returned.</p>
<p>If <i>lptr</i> or <i>rptr</i> (or both) are not valid pointers to arrays, the behaviour is undefined.</p>
<p>If <i>num</i> is larger (but not smaller) than the number of bytes of the smallest array, the behaviour is undefined.</p>
<br />
<h3>memcpy</h3>
<h4>Synopsis</h4>
<code>#include <zap/mem.h><br />void zap_memcpy(void const * in,size_t num,void * out);</code>
<h4>Description</h4>
<p>Copies <i>num</i>-bytes from the buffer pointed to by <i>in</i> into the same relative position in the buffer pointer to by <i>out</i>.</p>
<p>If <i>in</i> or <i>out</i> (or both) are not valid pointers to arrays, the behaviour is undefined.</p>
<p>If <i>num</i> is larger (but not smaller) than the number of bytes of the smallest array, the behaviour is undefined.</p>
<br />
<h3>memdup</h3>
<h4>Synopsis</h4>
<code>#include <zap/mem.h><br />void * zap_memdup(void const * ptr,size_t num);</code>
<h4>Description</h4>
<p>Copies <i>num</i>-bytes from the array pointed to by <i>ptr</i> into a newly-allocated array. The new array is allocated by <i>malloc</i>.</p>
<p>The returned value is a pointer to the new array.</p>
<p>If <i>num</i> is larger (but not smaller) than the number of bytes in the array, the behaviour is undefined.</p>
<br />
<h3>memeq</h3>
<h4>Synopsis</h4>
<code>#include <zap/mem.h><br />bool zap_memeq(void const * lptr,size_t num,void * rptr);</code>
<h4>Description</h4>
<p>Checks <i>num</i>-bytes of the buffers pointed to by <i>lptr</i> and <i>rptr</i> for equality.</p>
<p>If any two bytes are found to be different in the two buffers, false is returned. Otherwise, true is returned.</p>
<p>If <i>lptr</i> or <i>rptr</i> (or both) are not valid pointers to arrays, the behaviour is undefined.</p>
<p>If <i>num</i> is larger (but not smaller) than the number of bytes of the smallest array, the behaviour is undefined.</p>
<br />
<h3>memfill</h3>
<h4>Synopsis</h4>
<code>#include <zap/mem.h><br />void zap_memfill(void const * ptr,size_t num,unsigned char byte);</code>
<h4>Description</h4>
<p>Fills <i>num</i>-bytes of the buffer pointed to by <i>ptr</i> with the representation of <i>byte</i>.</p>
<p>If <i>ptr</i> is not a valid pointer to an array, the behaviour is undefined.</p>
<p>If <i>num</i> is larger (but not smaller) than the number of bytes of in the array, the behaviour is undefined.</p>
<br />
<h3>streq</h3>
<h4>Synopsis</h4>
<code>#include <zap/mem.h><br />bool zap_streq(char const * lstr,char const * rstr);</code>
<h4>Description</h4>
<p>Checks the equality of the strings <i>lstr</i> and <i>rstr</i>.</p>
<p>If one of the strings has a length different from the other, or if any character in the two strings is different from the other (at the same offset), true is returned. Otherwise, false is returned.</p>
<p>If <i>lstr</i> or <i>rstr</i> (or both) are not valid pointers to null-terminated strings, the behaviour is undefined.</p>
<br />
<h3>strfill</h3>
<h4>Synopsis</h4>
<code>#include <zap/mem.h><br />void zap_strfill(char * str,char chr);</code>
<h4>Description</h4>
<p>Writes the character <i>chr</i> to every valid position in the string <i>str</i>, excluding that of the null-terminator.</p>
<p>If <i>str</i> is not a valid pointer to a null-terminated string, the behaviour is undefined.</p>
<br />
<h3>strlen</h3>
<h4>Synopsis</h4>
<code>#include <zap/mem.h><br />size_t zap_strlen(char const * str);</code>
<h4>Description</h4>
<p>Counts the number of characters in the string <i>str</i>.</p>
<p>Returns the number of characters (excluding the null-terminator) in the string.</p>
<p>If <i>str</i> is not a valid pointer to a null-terminated string, the behaviour is undefined.</p>
</html>
