libs/src/pset/pset.3

   1 .\"(c) Copyright 1992, 1993 by Panagiotis Tsirigotis
   2 .\"All rights reserved.  The file named COPYRIGHT specifies the terms
   3 .\"and conditions for redistribution.
   4 .\"
   5 .\" $Id: pset.3,v 1.1.1.1 2003/02/19 17:29:27 bbraun Exp $
   6 .TH PSET 3X "23 April 1993"
   7 .SH NAME
   8 pset_create, pset_destroy, pset_add, pset_insert, pset_remove, pset_delete, pset_remove_index, pset_clear, pset_count, pset_pointer, pset_compact, pset_sort, pset_apply - routines that handle pointer sets
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 .ft B
  13 #include "pset.h"
  14 .LP
  15 .ft B
  16 pset_h pset_create( alloc_start, alloc_step )
  17 unsigned alloc_start, alloc_step ;
  18 .LP
  19 .ft B
  20 void pset_destroy( pset )
  21 pset_h pset ;
  22 .LP
  23 .ft B
  24 ANY_TYPE *pset_add( pset, ptr )
  25 pset_h pset ;
  26 ANY_TYPE *ptr ;
  27 .LP
  28 .ft B
  29 void *pset_insert( pset, ptr )
  30 pset_h pset ;
  31 void *ptr ;
  32 .LP
  33 .ft B
  34 void pset_remove( pset, ptr )
  35 pset_h pset ;
  36 ANY_TYPE *ptr ;
  37 .LP
  38 .ft B
  39 void pset_delete( pset, ptr )
  40 pset_h pset ;
  41 void *ptr ;
  42 .LP
  43 .ft B
  44 void pset_remove_index( pset, index )
  45 pset_h pset ;
  46 unsigned index ;
  47 .LP
  48 .ft B
  49 void pset_clear( pset )
  50 pset_h pset ;
  51 .LP
  52 .ft B
  53 unsigned pset_count( pset )
  54 pset_h pset ;
  55 .LP
  56 .ft B
  57 void *pset_pointer( pset, index )
  58 pset_h pset ;
  59 unsigned index ;
  60 .LP
  61 .ft B
  62 void pset_compact( pset )
  63 pset_h pset ;
  64 .LP
  65 .ft B
  66 void pset_sort( pset, compfunc )
  67 pset_h pset ;
  68 int (*compfunc)() ;
  69 .LP
  70 .ft B
  71 void pset_apply( pset, func, arg )
  72 pset_h pset ;
  73 void (*func)() ;
  74 void *arg ;
  75 .SH DESCRIPTION
  76 This library provides functions that handle sets of pointers. Pointers
  77 can be inserted and deleted from sets and the sets can be enumerated.
  78 Pointers are inserted in sets in no particular order. However it is
  79 guaranteed
  80 that a sequence of insertions will result in a set which if enumerated
  81 will provide the pointers in the same order in which they were inserted
  82 (assuming no intervening deletions).
  83 .LP
  84 .B pset_create()
  85 creates a pointer set.
  86 .I alloc_start
  87 determines the initial table size, and
  88 .I alloc_step
  89 determines the amount by which the set size is increased in case of
  90 overflow. If any of these parameters is 0, a default value is used.
  91 .LP
  92 .B pset_destroy()
  93 destroys the specified pointer set.
  94 .LP
  95 .B pset_add()
  96 is a macro that adds a pointer to the specified set.
  97 The pointer can be of any type.
  98 .LP
  99 .B pset_insert()
 100 inserts a pointer to the specified set.
 101 This is the same operation as
 102 .B pset_add().
 103 .LP
 104 .B pset_remove()
 105 removes a pointer from the specified set.
 106 .LP
 107 .B pset_delete()
 108 deletes a pointer from the specified set.
 109 This is the same operation as
 110 .B pset_remove().
 111 .LP
 112 .B pset_remove_index()
 113 removes the pointer that is at position
 114 .I index
 115 in the set.
 116 .I index
 117 should be in the range [0, \fBpset_count(pset)\fP) (but there is no
 118 check to enforce this).
 119 After this operation, the
 120 .I index
 121 position will be occupied by another pointer.
 122 .LP
 123 .B pset_clear()
 124 removes all pointers from the specified set.
 125 .LP
 126 .B pset_count()
 127 returns the number of pointers in the specified set.
 128 .LP
 129 .B pset_pointer()
 130 returns the pointer at position
 131 .I index
 132 in the specified set.
 133 .I index
 134 must be between 0 and
 135 .B "pset_count(pset)."
 136 .B pset_pointer()
 137 is a macro and it can also be used in the left-hand side of assignments.
 138 .LP
 139 .B pset_compact()
 140 removes all NULL pointers from
 141 .I pset.
 142 .LP
 143 .B pset_sort()
 144 sorts the pointers in
 145 .I pset
 146 using the specified function.
 147 .I compfunc
 148 is invoked with 2 arguments that are pointers pointing to pointers stored in
 149 .I pset.
 150 For example, if the pset holds pointers to objects of type T, then
 151 the function F whose address is in
 152 .I compfunc
 153 should be defined as:
 154 F( T **p1, T **p2 ).
 155 .br
 156 .I compfunc
 157 should return a negative, zero or positive value
 158 if its first argument is less than, equal to, or greater than its
 159 second argument.
 160 .LP
 161 .B pset_apply()
 162 applies
 163 .I func
 164 to all pointers in
 165 .I pset.
 166 If
 167 .I arg
 168 is not
 169 .SM NULL
 170 the function is invoked as:
 171 .RS
 172 (*func)( arg, p )
 173 .RE
 174 where
 175 .I p
 176 is a pset pointer.  If
 177 .I arg
 178 is
 179 .SM NULL
 180 the function is invoked as:
 181 .RS
 182 (*func)( p )
 183 .RE
 184 .SH EXAMPLE
 185 The following code fragment reads lines from standard input
 186 and places them in a pset. Then it sorts the pset, prints the
 187 sorted contents to standard output and then it eliminates duplicate
 188 lines (which it also prints to standard output).
 189 .RS
 190 .sp 1
 191 .ft B
 192 .nf
 193 pset_h ph ;
 194 char buf[ 80 ] ;
 195 unsigned u ;
 196 int compstr() ;
 197 void printstr() ;
 198 .sp 1
 199 ph = pset_create( 0, 0 ) ;
 200 while ( gets( buf ) )
 201 .RS
 202 pset_add( strcpy( malloc( strlen( buf ) + 1 ), buf ) ) ;
 203 .RE
 204 pset_sort( ph, compstr ) ;
 205 for ( u = 0 ; u < pset_count( ph ) ; u++ )
 206 .RS
 207 printf( "%s\\n", (char *) pset_pointer( ph, u ) ) ;
 208 .RE
 209 .RE
 210 .fi
 211 .ft R
 212 .LP
 213 The function
 214 .I compstr()
 215 follows:
 216 .sp 1
 217 .RS
 218 .ft B
 219 .nf
 220 int compstr( p1, p2 )
 221 .RS
 222 char **p1, **p2 ;
 223 .RE
 224 {
 225 .RS
 226 return( strcmp( *p1, *p2 ) ) ;
 227 .RE
 228 }
 229 .RE
 230 .SH "RETURN VALUES"
 231 .LP
 232 .I pset_h
 233 is a pointer type. Functions that return
 234 .I pset_h
 235 will return
 236 .SM NULL
 237 to indicate an error.
 238 .LP
 239 .B pset_create()
 240 returns a pointer set handle or
 241 .SM NULL
 242 if it fails.
 243 .LP
 244 .B pset_add()
 245 returns its second argument if successful or
 246 .SM NULL
 247 if it fails.
 248 .LP
 249 .B pset_insert()
 250 returns its second argument if successful or
 251 .SM NULL
 252 if it fails.
 253 .LP
 254 .B pset_count()
 255 always returns the number of pointers in the set.
 256 .LP
 257 .B pset_pointer()
 258 always returns a pointer. There is no check if the specified index is within
 259 range.
 260 .SH BUGS
 261 .LP
 262 .B pset_add(),
 263 .B pset_remove(),
 264 .B pset_remove_index(),
 265 .B pset_count(),
 266 .B pset_clear(),
 267 .B pset_pointer()
 268 and
 269 .B pset_sort()
 270 are macros, therefore the \fI&\fR operator cannot be applied to them.