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 sets in no particular order. However it is guaranteed that a sequence of insertions will result in a set which if enumerated will provide the pointers in the same order in which they were inserted (assuming no intervening deletions).

pset_create() creates a pointer set. alloc_start determines the initial table size, and alloc_step determines the amount by which the set size is increased in 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 the set. index should be in 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 the specified set.

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

pset_compact() removes all NULL pointers from pset.

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

pset_apply() applies func to all pointers in 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 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( buf ) )
        pset_add( strcpy( malloc( strlen( buf ) + 1 ), buf ) ) ;
    pset_sort( ph, compstr ) ;
    for ( u = 0 ; u < pset_count( ph ) ; u++ )
        printf( "%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 handle or NULL if it fails.

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

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

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

pset_pointer() always returns a pointer. There is no check if the specified 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.