libs/dbprim/ll_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 /** \ingroup dbprim_link
  27  * \brief Find an element in a linked list.
  28  *
  29  * This function iterates through a linked list looking for an element
  30  * that matches the given \p key.
  31  *
  32  * \param list  A pointer to a #link_head_t.
  33  * \param elem_p
  34  *              A pointer to a pointer to a #link_elem_t.  This is a
  35  *              result parameter.  \c NULL is an invalid value.
  36  * \param comp_func
  37  *              A pointer to a comparison function used to compare the
  38  *              key to a particular element.  See the documentation
  39  *              for #link_comp_t for more information.
  40  * \param start A pointer to a #link_elem_t describing where in the
  41  *              linked list to start.  If \c NULL is passed, the
  42  *              beginning of the list will be assumed.
  43  * \param key   A key to search for.
  44  *
  45  * \retval DB_ERR_BADARGS       An argument was invalid.
  46  * \retval DB_ERR_WRONGTABLE    \p start is not in this linked list.
  47  * \retval DB_ERR_NOENTRY       No matching entry was found.
  48  */
  49 unsigned long
  50 ll_find(link_head_t *list, link_elem_t **elem_p, link_comp_t comp_func,
  51         link_elem_t *start, db_key_t *key)
  52 {
  53   link_elem_t *elem;
  54
  55   initialize_dbpr_error_table(); /* initialize error table */
  56
  57   /* Verify arguments */
  58   if (!ll_verify(list) || !elem_p || !comp_func || !key ||
  59       (start && !le_verify(start)))
  60     return DB_ERR_BADARGS;
  61
  62   /* Verify that the start element is in this list */
  63   if (start && list != start->le_head)
  64     return DB_ERR_WRONGTABLE;
  65
  66   /* search the list... */
  67   for (elem = start ? start : list->lh_first; elem; elem = elem->le_next)
  68     if (!(*comp_func)(key, elem->le_object)) { /* Compare... */
  69       *elem_p = elem; /* comparison function must return "0" on match */
  70       return 0;
  71     }
  72
  73   return DB_ERR_NOENTRY; /* Couldn't find the element */
  74 }