.TH STRING 3
.UC 4
.SH NAME
string \- procedures for manipulating strings in libmagicutils.a

.SH SYNOPSIS
.nf
.B #include "magic.h"
.B #include "utils.h"
.PP
.B "typedef struct { char *d_str; } LookupTable;"
.PP
.B "int Lookup(str, table)"
.B char *str;
.B char *table[];
.PP
.B "int LookupStruct(str, table, size)"
.B char *str;
.B LookupTable *table;
.B int size;
.PP
.B "int LookupAny(c, table)"
.B char c;
.B char *table[];
.PP
.B "int LookupFull(name, table)"
.B char *name;
.B char *table[];
.PP
.B "char *StrDup(oldstr, str)"
.B char **oldstr, *str;
.PP
.B bool StrIsWhite(str, commentok)
.B char *str;
.B bool commentok;
.PP
.B bool StrIsInt(str)
.B char *str;
.PP
.B bool Match(pattern, string)
.B char *pattern, *string;
.PP
.B "char *ArgStr(pargc, pargv, argType)"
.B int *pargc;
.B char ***pargv;
.B char *argType;

.SH DESCRIPTION
This collection of procedures provide a number of useful
functions for dealing with strings.
.I Lookup
searches a table of strings to find one that matches a given string.
It's useful mostly for command lookup.
The table of strings should be terminated with a NULL string pointer,
and the entries should be alphabetical and all lower-case.
Any characters following the first white space in an entry are ignored.
If \fIstr\fR is an unambiguous abbreviation for one of the entries
in \fItable\fR, then the index of the matching entry is returned.
If \fIstr\fR is an abbreviation for more than one entry in table,
then -1 is returned.
If \fIstr\fR doesn't match any entry, then
-2 is returned.
Case differences are ignored.
.PP
.I LookupStruct
is a more general version of \fILookup\fR for dealing with tables
of structures whose first word is a string pointer.
The \fItable\fR argument should be a pointer to an array of
such structures, cast as type \fI(LookupTable *)\fR.  The
table should be terminated with an entry whose string pointer
is NULL.  As in \fILookup\fR, all entries should contain
lower-case strings and should be sorted alphabetically.
The \fIsize\fR parameter gives the size in bytes of each
structure in the table.
.PP
.I LookupAny
looks up a single character in a table of pointers to strings.
The last entry in the string table must be a NULL pointer.
The index of the first string in the table containing the indicated
character is returned, or -1 if no matching string is found.
.PP
.I LookupFull
is like \fILookup\fR, but does not allow abbreviations.
It either returns the index of the entry of \fItable\fR
matching \fIstr\fR, or -1 if no match is found.
Case is significant, and entries are considered to extend
all the way to their trailing NULL byte, instead of being
terminated by the first white space as in \fILookup\fR.
.PP
.I StrDup
can be used to replace an old string with a new one, freeing
the storage for the old one and allocating sufficient storage
for the new one.
It returns a pointer to a newly allocated character array
just large enough to hold \fIstr\fR and its trailing NULL byte.
This newly allocated array contains a copy of \fIstr\fR.
However, if \fIstr\fR is NULL, no memory is allocated and
we return NULL.
If \fIoldstr\fR is non-NULL, then if \fI*oldstr\fR is non-NULL,
\fIStrDup\fR frees the storage pointed to by \fI*oldstr\fR.
\fIStrDup\fR then sets \fI*oldstr\fR to point to the new
array of memory just allocated, or NULL if \fIstr\fR was NULL.
.PP
.I StrIsWhite
returns TRUE if \fIstr\fR is all white space, or FALSE otherwise.
If \fIcommentok\fR is TRUE, then if the first non-white character in
\fIstr\fR is a pound-sign (``\fB#\fR''), \fIstr\fR is considered
to be all white space.
.PP
.I StrIsInt
returns TRUE if \fIstr\fR is a well-formed decimal integer, or
FALSE if it isn't.
.PP
.I Match
provides a \fIcsh\fR\|(1)-like wild-card matching facility.
The string \fIpattern\fR may contain any of the \fIcsh\fR
wildcard characters: \fB*\fR, \fB?\fR, \fB\\\fR, \fB[\fR, and \fB]\fR.
If \fIpattern\fR matches \fIstring\fR, \fIMatch\fR returns TRUE;
otherwise, it returns FALSE.
.PP
.I ArgStr
is provided to allow standard processing of command-line arguments
that take parameters.
It recognizes flag-value pairs of either the form ``\fB\-\fIXvalue\fR''
(a single argument string)
or ``\fB\-\fIX\ value\fR''
(two successive argument strings)
in the argument list (\fI*pargc,\ *pargv\fR),
incrementing \fI*pargc\fR and \fI*pargv\fR by an amount sufficient
to step over the flag-value pair.  If there are no more arguments
remaining in the list,
.I ArgStr
prints an error message complaining that \fIargType\fR is required for
the flag \fI*pargv[0]\fR.

.SH SEE ALSO
magicutils\|(3)