.\" Copyright 2007-2008 Roy Marples
.\" All rights reserved
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd Feb 22, 2008
.Dt RC_STRLIST 3 SMM
.Os OpenRC
.Sh NAME
.Nm rc_strlist_add , rc_strlist_addu , rc_strlist_addsort ,
.Nm rc_strlist_addsortc , rc_strlist_addsortu , rc_strlist_delete ,
.Nm rc_strlist_join , rc_strlist_reverse , rc_strlist_free
.Nd RC string list functions
.Sh LIBRARY
Run Command library (librc, -lrc)
.Sh SYNOPSIS
.In rc.h
.Ft "char *" Fn rc_strlist_add "char ***list" "const char *item"
.Ft "char *" Fn rc_strlist_addu "char ***list" "const char *item"
.Ft "char *" Fn rc_strlist_addsort "char ***list" "const char *item"
.Ft "char *" Fn rc_strlist_addsortc "char ***list" "const char *item"
.Ft "char *" Fn rc_strlist_addsortu "char ***list" "const char *item"
.Ft bool Fn rc_strlist_delete "char ***list" "const char *item"
.Ft "char *" Fn rc_strlist_join "char ***list1" "const char **list2"
.Ft void Fn rc_strlist_reverse "char **list"
.Ft void Fn rc_strlist_free "char **list"
.Sh DESCRIPTION
These functions provide an easy means of manipulating string lists without
the need for custom structures or non standard macros.
.Pp
.Fn rc_strlist_add
adds a malloced copy of
.Fa item
to
.Fa list ,
realloced to accomodate the new item. It returns a pointer to the new item on
success, or NULL on failure and sets
.Va errno
accordingly.
.Fn rc_strlist_addu
and
.Fn rc_strlist_addsortu
only work if
.Fa list
does not already contain
.Fa item .
.Fn rc_strlist_addsort
adds the item to the list in a lexically sorted position, using
.Nm strcoll ,
whereas
.Fn rc_strlist_addsortc
uses
.Nm strcmp .
.Pp
.Fn rc_strlist_delete
removes and frees
.Fa item
from
.Fa list ,
retuning true on success, otherwise false.
.Pp
.Fn rc_strlist_join
appends
.Fa list2
to the end of
.Fa list1
and returns a pointer to the last item on the new list.
.Pp
.Fn rc_strlist_reverse
reverses the items on
.Fa list .
.Pp
.Fn rc_strlist_free
frees each item on
.Fa list
and the
.Fa list
itself.
.Sh SEE ALSO
.Xr malloc 3 ,
.Xr free 3 ,
.Xr strcmp 3 ,
.Xr strcoll 3
.Sh AUTHORS
.An "Roy Marples" Aq roy@marples.name