|
|
<!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>fndbyte</h3>
<h4>Synopsis</h4>
<code>#include <zap/base.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>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/base.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/base.h><br />void zap_foreach(void * ptr,size_t sz,size_t num,void (* fn)(void *));</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 is equal to the laster pointer plus <i>sz</i>.</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 function pointer, the behaviour is undefined.</p>
<br />
<h3>memcmp</h3>
<h4>Synopsis</h4>
<code>#include <zap/base.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>memdup</h3>
<h4>Synopsis</h4>
<code>#include <zap/base.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>streq</h3>
<h4>Synopsis</h4>
<code>#include <zap/base.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/base.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/base.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>
|
