add a few examples

examples/buffer_getline.c

@@ -0,0 +1,27 @@
+#include <stralloc.h>
+#include <buffer.h>
+#include <io.h>
+#include <errmsg.h>
+#include <unistd.h>
+
+int main() {
+  static stralloc line;
+  buffer in;
+  char buf[4096];
+  int64 fd;
+  char* home;
+  long r;
+
+  errmsg_iam("buffer_getline");
+
+  if (!(home=getenv("HOME"))) die(1,"no $HOME");
+  if (!stralloc_copys(&line,home) || !stralloc_cats(&line,"/.slrnrc") || !stralloc_0(&line))
+    die(1,"out of memory");
+  if (!io_readfile(&fd,line.s))
+    diesys(1,"could not open ~/.slrnrc");
+  buffer_init(&in,read,fd,buf,sizeof buf);
+
+  while ((r=buffer_getnewline_sa(&in,&line))>0) {
+    write(1,line.s,line.len);
+  }
+}

examples/byte.c

@@ -0,0 +1,102 @@
+#include <byte.h>
+#include <buffer.h>
+
+/*
+ * The functions that are beginning with byte_ offer some handy functions, to
+ * manipulate with raw bytes.
+ */
+
+int
+main()
+{	/* The indices:     0123456 */
+	char memory1[42] = "foo bar";
+	char memory2[23] = "fnord";
+	unsigned int pos;
+	int diff;
+	
+	/* First we want to search forward for a certain char - we can achieve it
+	 * by using:
+	 *
+	 * unsigned int  byte_chr(const  char  *haystack,unsigned int len,char
+	 * needle);
+	 *
+	 * which returns the _first_ position of the searched char ("needle") or
+	 * the supplied length ("len") if the search fails.
+	 */
+
+	pos = byte_chr(memory1, 7, 'b'); /* Returns 4. */
+
+	buffer_puts(buffer_1, "byte_chr(memory1, 7, 'b'): ");
+	buffer_putulong(buffer_1, pos);
+	buffer_putnlflush(buffer_1);
+
+	/* Now let's focus on the opposite: we want to search backward in a
+	 * mem-region:
+	 *
+	 * unsigned int byte_rchr(const void* haystack,unsigned int len,char
+	 * needle);
+	 *
+	 * now it returns the _last_ position of the "needle" or len.
+	 */
+
+	pos = byte_rchr(memory1, 7, 'o'); /* Returns 2.*/
+
+	buffer_puts(buffer_1, "byte_rchr(memory1, 7, 'o'): ");
+	buffer_putulong(buffer_1, pos);
+	buffer_putnlflush(buffer_1);
+
+	/* Enough of searching for now -- another important task is copying of
+	 * memory. Of course, libowfat helps you also in this point:
+	 *
+	 * void byte_copy(void* out, unsigned int len, const void* in);
+	 *
+	 * It simply copies len bytes from in to out -- starting at in[0] and
+	 * out[0].  Please recog that it has an another API than memcpy() that has
+	 * the last two parameters swapped.
+	 */
+
+	byte_copy(memory1, 2, memory2); /* Makes memory1 look: "fno bar" */
+
+	buffer_puts(buffer_1, "byte_copy(memory1, 2, memory2): ");
+	buffer_puts(buffer_1, memory1);
+	buffer_putnlflush(buffer_1);
+
+	/* There is also a function byte_copyr() that does exactly the same except
+	 * of starting at the _end_ of the strings, i.e. in[len-1] and out[len-1].
+	 * I won't dicuss it in detail as only the internals has changed.
+	 */
+
+	/* Another point is the comparing between memory regions -- in the libowfat
+	 * is
+	 *
+	 * int byte_diff(const void* a, unsigned int len, const void* b);
+	 *
+	 * the utility of choice. It returns 0 if the regions are equal, <0 if
+	 * a[0]...a[len] is lexicographically smaller and >0 if it is greater than
+	 * b. After the first difference is found, no further reading beyond this
+	 * difference is done. Beware of checking only for 1 and -1!
+	 */
+
+	diff = byte_diff(memory1, 5, memory2);
+
+	buffer_puts(buffer_1, "byte_diff(memory1, 5, memory2): ");
+	buffer_putlong(buffer_1, diff);
+	buffer_putnlflush(buffer_1);
+
+	/* For convience, there is also a macro called byte_equal() for checking
+	 * for equality -- in fact it is just a !byte_diff().
+	 */
+
+	/* Last but not feast a quite simple yet useful function that make it
+	 * possible to ban the BSD-legacy-crap called bzero() from your code w/o
+	 * having to use memset() that confused even Rich Stevens:
+	 *
+	 * void byte_zero(char *out,unsigned int len);
+	 *
+	 * fills the specified block of memory with 0.
+	 */
+
+	byte_zero(memory1, 42);
+
+	return 0;
+}

examples/str.c

@@ -0,0 +1,109 @@
+#include <str.h>
+#include <buffer.h>
+
+/*
+ * The str_* functions have a pretty similar functionality to the byte_* ones
+ * -- the most important enhacement is the recognition of \0.
+ */
+
+int
+main()
+{
+	char *string1 = "foo bar";
+	char string2[42] = "fnord";
+	unsigned int len;
+	unsigned int amm;
+	unsigned int pos;
+	int diff;
+	int start;
+
+	/* For determinating the difference between two strings, thew libowfat
+	 * offers two functions:
+	 * 
+	 * int str_diff(const char *a,const char *b);
+	 *
+	 * and
+	 *
+	 * int str_diffn(const char *a,const char *b,unsigned int limit);
+	 *
+	 * They both return <0 if a is lexicographically smaller than b, 0 if they
+	 * are equal and >0 if b is greater than a. The only difference is that
+	 * str_diff compares everytime until a \0 is encountered and str_diffn
+	 * compares max. until limit. Beware of checking just for 1 and -1!
+	 */
+
+	diff = str_diff(string1, string2);
+	
+	buffer_puts(buffer_1, "str_diff(string1, string2): ");
+	buffer_putlong(buffer_1, diff);
+	buffer_putnlflush(buffer_1);
+
+
+	/* As in byte_diff(), there is a macro str_equal(a,b) for convience. */
+
+	/* For the frequent task of testing whether a string starts with an another
+	 * is the following function:
+	 *
+	 * int str_start(const char *a,const char *b);
+	 *
+	 * It simply returns 1 if a starts with b and 0 otherwise.
+	 */
+
+	start = str_start(string1, "foo");
+
+	buffer_puts(buffer_1, "str_start(string1, \"foo\"): ");
+	buffer_putlong(buffer_1, start);
+	buffer_putnlflush(buffer_1);
+ 
+
+	/* Determinating the length of a string is also easy with the libowfat:
+	 *
+	 * unsigned int str_len(const char *s);
+	 * 
+	 * returns the index of \0 in the string and that's also the length.
+	 */
+
+	len = str_len(string1);
+
+	buffer_puts(buffer_1, "str_len(buffer_1): ");
+	buffer_putulong(buffer_1, len);
+	buffer_putnlflush(buffer_1);
+
+
+	/* One of the most used ANSI-C-functions is strcpy() and the libowfat has
+	 * an own version:
+	 *
+	 * unsigned int str_copy(char *out,const char *in);
+	 *
+	 * It copies "in" into "out" until the first \0 is copied and returns the
+	 * number of bytes copied.
+	 */
+
+	amm = str_copy(string2, string1); /* Returns 7, string2 now begins with "foo bar\0". */
+
+	buffer_puts(buffer_1, "str_copy(string1, string2): ");
+	buffer_putulong(buffer_1, amm);
+	buffer_putnlflush(buffer_1);
+
+
+	/* Similar to byte_* there are:
+	 *  
+	 * unsigned int str_chr(const char *haystack,char needle);
+	 * 
+	 * and
+	 *
+	 * unsigned int str_rchr(const char *haystack,char needle);
+	 *
+	 * The first one returns the index of the _first_ occurency of "needle" in
+	 * "haystack" and the second returns the last one. Both return the index of
+	 * \0 if the "needle" hasn't been found.
+	 */
+
+	pos = str_chr(string1, 'b'); /* Returns 4. */
+
+	buffer_puts(buffer_1, "str_chr(string1, 'b'): ");
+	buffer_putulong(buffer_1, pos);
+	buffer_putnlflush(buffer_1);
+
+	return 0;
+}