@@@ much mess, mostly manpages

[mLib] / utils / str.3.in

.\" -*-nroff-*-
.\"
.\" Manual for string utilities
.\"
.\" (c) 1999--2001, 2005--2007, 2009, 2019, 2024 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the mLib utilities library.
.\"
.\" mLib is free software: you can redistribute it and/or modify it under
.\" the terms of the GNU Library General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or (at
.\" your option) any later version.
.\"
.\" mLib is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
.\" License for more details.
.\"
.\" You should have received a copy of the GNU Library General Public
.\" License along with mLib.  If not, write to the Free Software
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
.\" USA.
.
.\"--------------------------------------------------------------------------
.so ../defs.man \" @@@PRE@@@
.
.\"--------------------------------------------------------------------------
.TH str 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @str_qword
.\" @str_qsplit
.\" @str_getword
.\" @str_split
.\" @str_matchx
.\" @str_match
.\" @str_sanitize
.
.\"--------------------------------------------------------------------------
.SH NAME
str \- small string utilities
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
.nf
.B "#include <mLib/str.h>"
.PP
.BI "char *str_qword(char **" pp ", unsigned " f );
.BI "size_t str_qsplit(char *" p ", char *" v "[], size_t " c ,
.BI "                  char **" rest ", unsigned " f );
.BI "char *str_getword(char **" pp );
.BI "size_t str_split(char *" p ", char *" v "[], size_t " c ", char **" rest );
.BI "int str_matchx(const char *" p ", const char *" s ", unsigned " f );
.BI "int str_match(const char *" p ", const char *" s );
.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_qword
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_qword
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_qword
modifies the string as it goes, to null-terminate the individual words.
If the flag
.B STRF_QUOTE
is passed, the single- and double-quote characters may be used to quote
whitespace within words, and the backslash can escape quote characters
and whitespace.
.PP
The function
.B str_qsplit
divides a string into whitespace-separated words.  The arguments are as
follows:
.TP
.BI "char *" p
The address of the string to split.  The string is modified by having
null terminators written after each word extracted.
.TP
.BI "char *" 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
.BI "size_t " c
The maximum number of words to extract; also, the number of elements in
the array
.IR v .
.TP
.BI "char **" 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.
.TP
.BI "unsigned " f
Flags, as for
.BR str_qsplit .
.PP
The return value of
.B str_qsplit
is the number of words extracted from the input string.
.PP
The functions
.B str_getword
and
.B str_split
are veneers over
.B str_qword
and
.B str_qsplit
respectively; they are equivalent to calls to the latter functions with
flags words of zero.
.PP
The
.B str_matchx
function does simple wildcard matching.  The first argument is a
pattern, which may contain metacharacters:
.RB ` * '
matches zero or more arbitrary characters;
.RB ` ? '
matches exactly one arbitrary characters; and
.RB ` [ ... ] '
matches one of the characters listed.  The backslash
.RB ` \e '
escapes the following character.  Within square brackets, the
hyphen
.RB ` \- '
may be used to designate ranges of characters.  If the initial character
is
.RB ` ! '
or
.RB ` ^ '
then the sense of the match is reversed.  To literally match a
.RB ` ] '
character, list it first; to literally match a
.RB ` \- '
character, list it immediately after a range, or at the beginning or end
of the set.  The return value is nonzero if the pattern
.I p
matches the given string
.IR s ,
or zero if the pattern doesn't match.  If the flag
.B STRF_PREFIX
is passed,
.B str_matchx
returns true if it reaches the end of the target string before finding a
mismatch \(en i.e., if the target string is a prefix of a string which
might match the pattern.  The function
.B str_match
is a convenient wrapper for
.B str_matchx
with a zero flags word, which is the normal case.
.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;
.VP
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@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------