.\" -*-nroff-*-
.de VS
.sp 1
.in +5n
.ft B
.nf
..
.de VE
.ft R
.in -5n
.sp 1
.fi
..
.TH str 3 "20 June 1999" mLib
.SH NAME
str \- small string utilities
.\" @str_getword
.\" @str_split
.\" @str_sanitize
.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 "SEE ALSO"
.BR mLib (3).
.SH AUTHOR
Mark Wooding, <mdw@nsict.org>