libs/dbprim/st_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_smat
  27  * \brief Find an entry in a sparse matrix.
  28  *
  29  * This function looks up the entry matching the given \p head1 and \p
  30  * head2.
  31  *
  32  * \param table A pointer to a #smat_table_t.
  33  * \param entry_p
  34  *              A pointer to a pointer to a #smat_entry_t.  This is a
  35  *              result parameter.  If \c NULL is passed, the lookup
  36  *              will be performed and an appropriate error code
  37  *              returned.
  38  * \param head1 A pointer to a #smat_head_t initialized to
  39  *              #SMAT_LOC_FIRST.
  40  * \param head2 A pointer to a #smat_head_t initialized to
  41  *              #SMAT_LOC_SECOND.
  42  *
  43  * \retval DB_ERR_BADARGS       An argument was invalid.
  44  * \retval DB_ERR_WRONGTABLE    One or both of \p head1 or \p head2
  45  *                              are not referenced in this table.
  46  * \retval DB_ERR_NOENTRY       No matching entry was found.
  47  */
  48 unsigned long
  49 st_find(smat_table_t *table, smat_entry_t **entry_p, smat_head_t *head1,
  50         smat_head_t *head2)
  51 {
  52   hash_entry_t *ent;
  53   unsigned long retval;
  54   void *object[2];
  55   db_key_t key;
  56
  57   initialize_dbpr_error_table(); /* initialize error table */
  58
  59   /* Verify arguments */
  60   if (!st_verify(table) || !sh_verify(head1) || !sh_verify(head2) ||
  61       head1->sh_elem != SMAT_LOC_FIRST || head2->sh_elem != SMAT_LOC_SECOND)
  62     return DB_ERR_BADARGS;
  63
  64   /* If there are no entries in one of the lists, then return "no entry" */
  65   if (!head1->sh_table || !head2->sh_table || head1->sh_head.lh_count == 0 ||
  66       head2->sh_head.lh_count == 0)
  67     return DB_ERR_NOENTRY;
  68
  69   /* verify that everything's in the right tables */
  70   if (head1->sh_table != table || head2->sh_table != table)
  71     return DB_ERR_WRONGTABLE;
  72
  73   /* Build the search key */
  74   object[SMAT_LOC_FIRST] = sh_object(head1);
  75   object[SMAT_LOC_SECOND] = sh_object(head2);
  76   dk_key(&key) = object;
  77   dk_len(&key) = 0;
  78
  79   /* look up the entry */
  80   if ((retval = ht_find(&table->st_table, &ent, &key)))
  81     return retval;
  82
  83   /* If the user wants the object, return it to him */
  84   if (entry_p)
  85     *entry_p = he_value(ent);
  86
  87   return 0; /* search successful */
  88 }