libs/src/pset/psi.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: psi.3,v 1.1.1.1 2003/02/19 17:29:27 bbraun Exp $
   6 .TH PSET 3X "25 September 1992"
   7 .SH NAME
   8 psi_create, psi_destroy, psi_reset, psi_start, psi_next, psi_remove - pointer set iterator functions
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 .ft B
  13 #include "pset.h"
  14 .LP
  15 .ft B
  16 psi_h psi_create( pset )
  17 pset_h pset ;
  18 .LP
  19 .ft B
  20 void psi_destroy( iter )
  21 psi_h iter ;
  22 .LP
  23 .ft B
  24 void psi_reset( iter, pset )
  25 psi_h iter ;
  26 pset_h pset ;
  27 .LP
  28 .ft B
  29 void *psi_start( iter )
  30 psi_h iter ;
  31 .LP
  32 .ft B
  33 void *psi_next( iter )
  34 psi_h iter ;
  35 .LP
  36 .ft B
  37 void psi_remove( iter )
  38 psi_h iter ;
  39 .SH DESCRIPTION
  40 These functions provide a means to iterate over psets (pointer sets).
  41 .LP
  42 .B psi_create()
  43 creates an iterator. The only operation that should be applied to
  44 an iterator after it is created is
  45 .B psi_start().
  46 .LP
  47 .B psi_destroy()
  48 destroys the iterator.
  49 .LP
  50 .B psi_reset()
  51 changes the pset that is being iterated to
  52 .I pset.
  53 .LP
  54 .B psi_start()
  55 starts an iteration and returns the first pointer
  56 in the pointer set.
  57 .LP
  58 .B psi_next()
  59 returns the next pointer in the set.
  60 .LP
  61 .B psi_remove()
  62 removes the current pointer from the set. The current pointer is
  63 the one returned most recently from either
  64 .B psi_start()
  65 or
  66 .B psi_next().
  67 .SH "RETURN VALUES"
  68 .LP
  69 .B psi_create()
  70 returns an iterator handle on success or
  71 .SM NULL
  72 on failure.
  73 .LP
  74 .B psi_start()
  75 returns the first pointer from the set or
  76 .SM NULL
  77 if the set is empty.
  78 .LP
  79 .B psi_next()
  80 returns a pointer or
  81 .SM NULL
  82 if the end of the set is reached.
  83 .SH WARNINGS
  84 .B psi_create()
  85 is the only function in this library. The rest of the interface is macros.
  86 .LP
  87 This interface may be eliminated in a future release of the
  88 .I pset
  89 library.