Seth Woolley's Man Viewer

PSET(3X)                                                              PSET(3X)



NAME
       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

SYNOPSIS
       #include "pset.h"

       pset_h pset_create( alloc_start, alloc_step )
       unsigned alloc_start, alloc_step ;

       void pset_destroy( pset )
       pset_h pset ;

       ANY_TYPE *pset_add( pset, ptr )
       pset_h pset ;
       ANY_TYPE *ptr ;

       void *pset_insert( pset, ptr )
       pset_h pset ;
       void *ptr ;

       void pset_remove( pset, ptr )
       pset_h pset ;
       ANY_TYPE *ptr ;

       void pset_delete( pset, ptr )
       pset_h pset ;
       void *ptr ;

       void pset_remove_index( pset, index )
       pset_h pset ;
       unsigned index ;

       void pset_clear( pset )
       pset_h pset ;

       unsigned pset_count( pset )
       pset_h pset ;

       void *pset_pointer( pset, index )
       pset_h pset ;
       unsigned index ;

       void pset_compact( pset )
       pset_h pset ;

       void pset_sort( pset, compfunc )
       pset_h pset ;
       int (*compfunc)() ;

       void pset_apply( pset, func, arg )
       pset_h pset ;
       void (*func)() ;
       void *arg ;

DESCRIPTION
       This library provides functions that handle sets of pointers.  Pointers
       can  be  inserted and deleted from sets and the sets can be enumerated.
       Pointers are inserted in(1,8) sets in(1,8) no particular  order.  However  it  is
       guaranteed  that a sequence of insertions will result in(1,8) a set(7,n,1 builtins) which if(3,n)
       enumerated will provide the pointers in(1,8) the same order  in(1,8)  which  they
       were inserted (assuming no intervening deletions).

       pset_create()  creates  a pointer set.  alloc_start determines the ini-
       tial table size, and alloc_step determines the amount by which the  set(7,n,1 builtins)
       size is increased in(1,8) case of overflow. If any of these parameters is 0,
       a default value is used.

       pset_destroy() destroys the specified pointer set.

       pset_add() is a macro that adds a pointer to the  specified  set.   The
       pointer can be of any type.

       pset_insert() inserts a pointer to the specified set.  This is the same
       operation as pset_add().

       pset_remove() removes a pointer from the specified set.

       pset_delete() deletes a pointer from the specified set.   This  is  the
       same operation as pset_remove().

       pset_remove_index()  removes  the  pointer that is at position index in(1,8)
       the set.  index should be in(1,8) the range [0, pset_count(pset)) (but there
       is no check to enforce this).  After this operation, the index position
       will be occupied by another pointer.

       pset_clear() removes all pointers from the specified set.

       pset_count() returns the number of pointers in(1,8) the specified set.

       pset_pointer() returns the pointer at position index in(1,8)  the  specified
       set.   index must be between 0 and pset_count(pset).  pset_pointer() is
       a macro and it can also be used in(1,8) the left-hand side of assignments.

       pset_compact() removes all NULL pointers from pset.

       pset_sort() sorts the pointers in(1,8) pset using  the  specified  function.
       compfunc  is  invoked  with  2  arguments that are pointers pointing to
       pointers stored in(1,8) pset.  For example, if(3,n) the pset  holds  pointers  to
       objects  of  type  T,  then the function F whose address is in(1,8) compfunc
       should be defined as: F( T **p1, T **p2 ).
       compfunc should return a negative, zero or positive value if(3,n) its  first
       argument is less(1,3) than, equal to, or greater than its second argument.

       pset_apply()  applies func to all pointers in(1,8) pset.  If arg is not NULL
       the function is invoked as:
              (*func)( arg, p )
       where p is a pset pointer.  If arg is NULL the function is invoked as:
              (*func)( p )

EXAMPLE
       The following code fragment reads lines from standard input and  places
       them  in(1,8)  a pset. Then it sorts the pset, prints the sorted contents to
       standard output and then it eliminates duplicate lines (which  it  also
       prints to standard output).

              pset_h ph ;
              char buf[ 80 ] ;
              unsigned u ;
              int compstr() ;
              void printstr() ;

              ph = pset_create( 0, 0 ) ;
              while ( gets(3,n)( buf ) )
                     pset_add( strcpy( malloc( strlen( buf ) + 1 ), buf ) ) ;
              pset_sort( ph, compstr ) ;
              for ( u = 0 ; u < pset_count( ph ) ; u++ )
                     printf(1,3,1 builtins)( "%s\n", (char *) pset_pointer( ph, u ) ) ;

       The function compstr() follows:

              int compstr( p1, p2 )
                     char **p1, **p2 ;
              {
                     return( strcmp( *p1, *p2 ) ) ;
              }

RETURN VALUES
       pset_h is a pointer type. Functions that return pset_h will return NULL
       to indicate an error.

       pset_create() returns a pointer set(7,n,1 builtins) handle or NULL if(3,n) it fails.

       pset_add() returns its second argument if(3,n)  successful  or  NULL  if(3,n)  it
       fails.

       pset_insert()  returns  its second argument if(3,n) successful or NULL if(3,n) it
       fails.

       pset_count() always returns the number of pointers in(1,8) the set.

       pset_pointer() always returns a pointer. There is no check if(3,n) the spec-
       ified index is within range.

BUGS
       pset_add(),     pset_remove(),    pset_remove_index(),    pset_count(),
       pset_clear(), pset_pointer() and pset_sort() are macros, therefore  the
       & operator cannot be applied to them.



                                 23 April 1993                        PSET(3X)