libs/dbprim/sh_find.c

   1 /*
   2 ** Copyright (C) 2002 by Kevin L. Mitchell <klmitch@mit.edu>
   3 **
   4 ** This library is free software; you can redistribute it and/or
   5 ** modify it under the terms of the GNU Library General Public
   6 ** License as published by the Free Software Foundation; either
   7 ** version 2 of the License, or (at your option) any later version.
   8 **
   9 ** This library is distributed in the hope that it will be useful,
  10 ** but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12 ** Library General Public License for more details.
  13 **
  14 ** You should have received a copy of the GNU Library General Public
  15 ** License along with this library; if not, write to the Free
  16 ** Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  17 ** MA 02111-1307, USA
  18 **
  19 ** @(#)$Id$
  20 */
  21 #include "dbprim.h"
  22 #include "dbprim_int.h"
  23
  24 RCSTAG("@(#)$Id$");
  25
  26 struct _sh_find_s {
  27   smat_comp_t   sf_comp;        /* comparison function */
  28   db_key_t     *sf_key;         /* original key */
  29 };
  30
  31 static unsigned long
  32 _sh_find_comp(db_key_t *key, void *data)
  33 {
  34   struct _sh_find_s *sf;
  35
  36   sf = dk_key(key);
  37
  38   /* Call the user's comparison function--with some translation */
  39   return (*sf->sf_comp)(sf->sf_key, data);
  40 }
  41
  42 /** \ingroup dbprim_smat
  43  * \brief Find an entry in a row or column of a sparse matrix.
  44  *
  45  * This function iterates through the given row or column of a
  46  * sparse matrix looking for an element that matches the given \p key.
  47  *
  48  * \param head  A pointer to a #smat_head_t.
  49  * \param elem_p
  50  *              A pointer to a pointer to a #smat_entry_t.  This is a
  51  *              result pramater.  \c NULL is an invalid value.
  52  * \param comp_func
  53  *              A pointer to a comparison function used to compare the
  54  *              key to a particular entry.  See the documentation for
  55  *              #smat_comp_t for more information.
  56  * \param start A pointer to a #smat_entry_t describing where in the
  57  *              row or column to start.  If \c NULL is passed, the
  58  *              beginning of the row or column will be assumed.
  59  * \param key   A key to search for.
  60  *
  61  * \retval DB_ERR_BADARGS       An argument was invalid.
  62  * \retval DB_ERR_WRONGTABLE    \p start is not in this row or column.
  63  * \retval DB_ERR_NOENTRY       No matching entry was found.
  64  */
  65 unsigned long
  66 sh_find(smat_head_t *head, smat_entry_t **elem_p, smat_comp_t comp_func,
  67         smat_entry_t *start, db_key_t *key)
  68 {
  69   unsigned long retval;
  70   link_elem_t *elem;
  71   struct _sh_find_s sf;
  72   db_key_t fkey;
  73
  74   initialize_dbpr_error_table(); /* initialize error table */
  75
  76   /* verify arguments */
  77   if (!sh_verify(head) || !elem_p || !comp_func || !key ||
  78       (start && !se_verify(start)))
  79     return DB_ERR_BADARGS;
  80
  81   /* Set up for the call to ll_find()... */
  82   sf.sf_comp = comp_func;
  83   sf.sf_key = key;
  84   dk_key(&fkey) = &sf;
  85
  86   /* call into the linked list library to find the element */
  87   if ((retval = ll_find(&head->sh_head, &elem, _sh_find_comp,
  88                         start ? &start->se_link[head->sh_elem] : 0, &fkey)))
  89     return retval;
  90
  91   *elem_p = le_object(elem); /* set the entry pointer correctly */
  92
  93   return 0;
  94 }