Add a slew of manual pages.

[mLib] / man / str.3

diff --git a/man/str.3 b/man/str.3
new file mode 100644 (file)
index 0000000..16e859d
--- /dev/null
+++ b/man/str.3
@@ -0,0 +1,136 @@
+.\" -*-nroff-*-
+.de VS
+.sp 1
+.in +5n
+.ft B
+.nf
+..
+.de VE
+.ft R
+.in -5n
+.sp 1
+.fi
+..
+.TH str 3mLib "20 June 1999" mLib
+.SH NAME
+str \- small string utilities
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/str.h>"
+
+.BI "char *str_getword(char **" pp );
+.BI "size_t str_split(char *" p ", char *" v "[], size_t " c ", char **" rest );
+.BI "void str_sanitize(char *" d ", const char *" p ", size_t " sz );
+.fi
+.SH DESCRIPTION
+The header file
+.B <mLib/str.h>
+contains a few small utility functions for manipulating null-terminated
+strings.  
+.PP
+The function
+.B str_getword
+extracts the next whitespace-delimited word from a string.  The
+function's argument,
+.IR pp ,
+is the address of a pointer into the string: this pointer is updated by
+.B str_getword
+so that it can extract the following word on the next call and so on.
+The return value is the address of the next word, appropriately null
+terminated.  A null pointer is returned if the entire remainder of the
+string is whitespace.  Note that
+.B str_getword
+modifies the string as it goes, to null-terminate the individual words.
+.PP
+The function
+.B str_split
+divides a string into whitespace-separated words.  The arguments are as
+follows:
+.TP
+.I p
+The address of the string to split.  The string is modified by having
+null terminators written after each word extracted.
+.TP
+.I v
+The address of an array of pointers to characters.  This array will be
+filled in by
+.BR str_split :
+the first entry will point to the first word extracted from the string,
+and so on.  If there aren't enough words in the string, the remaining
+array elements are filled with null pointers.
+.TP
+.I c
+The maxmimum number of words to extract; also, the number of elements in
+the array
+.IR v .
+.TP
+.I rest
+The address of a pointer in which to store the address of the remainder
+of the string.  Leading whitespace is removed from the remainder before
+storing.  If the remainder string is empty, a null pointer is stored
+instead.  If
+.I rest
+is null, the remainder pointer is discarded.
+.PP
+The return value of
+.B str_split
+is the number of words extracted from the input string.
+.PP
+The function
+.B str_sanitize
+copies at most
+.I sz \- 1
+characters from the string
+.I p
+to
+.IR d .
+The result string is null terminated.  Any nonprinting characters in
+.I p
+are replaced by an underscore
+.RB ` _ '
+when written to
+.IR d .
+.SH EXAMPLES
+Given the code
+.VS
+char p[] = " alpha  beta gamma   delta ";
+char *v[3];
+size_t n;
+char *q;
+
+n = str_split(p, v, 3, &q);
+.VE
+following the call to
+.BR str_split ,
+.B n
+will have the value 3,
+.B v[0]
+will point to
+.RB ` alpha ',
+.B v[1]
+will point to
+.RB ` beta ',
+.B v[2]
+will point to
+.RB ` gamma '
+and
+.B rest
+will point to
+.RB ` delta\  '
+(note the trailing space).
+.PP
+Similarly, given the string
+.B """\ alpha\ \ beta\ """
+instead,
+.B n
+will be assigned the value 2,
+.B v[0]
+and
+.B v[1]
+will have the same values as last time, and
+.B v[2]
+and
+.B rest
+will be null.
+.SH AUTHOR
+Mark Wooding, <mdw@nsict.org>