nuttx/include/search.h

/****************************************************************************
 * include/search.h
 *
 * SPDX-License-Identifier: LicenseRef-NuttX-PublicDomain
 *
 * Written by J.T. Conklin <jtc@netbsd.org>
 * Public domain.
 *
 ****************************************************************************/

#ifndef __INCLUDE_SEARCH_H
#define __INCLUDE_SEARCH_H

/****************************************************************************
 * Included Files
 ****************************************************************************/

#include <sys/types.h>

/****************************************************************************
 * Pre-processor Definitions
 ****************************************************************************/

/****************************************************************************
 * Public Type Definitions
 ****************************************************************************/

typedef struct entry
{
  FAR char *key;
  FAR void *data;
} ENTRY;

typedef enum
{
  FIND,
  ENTER,
  DELETE
} ACTION;

struct hsearch_data
{
  FAR struct internal_head *htable;
  size_t htablesize;
  CODE void (*free_entry)(FAR ENTRY *entry);
};

/* This is the callback type used by hforeach() */

typedef CODE void (*hforeach_t)(FAR ENTRY *entry, FAR void *data);

/****************************************************************************
 * Public Function Prototypes
 ****************************************************************************/

/****************************************************************************
 * Name: hcreate
 *
 * Description:
 *   The hcreate() function creates a new hashing table with nel elements.
 *   The hashing table will be used by subsequent calls to hsearch() with
 *   the same htab argument.  The hashing table is initialized with nel
 *   hashing buckets.
 *
 *   The hcreate_r() function is the reentrant version of hcreate().
 *
 * Returned Value:
 *   If successful, hcreate() and hcreate_r() return 1; otherwise, they
 *   return 0.
 *
 ****************************************************************************/

int hcreate(size_t);

/****************************************************************************
 * Name: hdestroy
 *
 * Description:
 *   The hdestroy() function destroys the hashing table specified by htab.
 *   The hashing table is destroyed only if there are no entries in the
 *   table.  The hashing table cannot be used again until hcreate() or
 *   hcreate_r() is called.
 *
 *   The hdestroy_r() function is the reentrant version of hdestroy().
 *
 * Returned Value:
 *   None
 *
 ****************************************************************************/

void hdestroy(void);

/****************************************************************************
 * Name: hsearch
 *
 * Description:
 *   The hsearch() function searches the hashing table specified by htab
 *   for an entry with a key matching that of item.  If such an entry is
 *   found, hsearch() returns a pointer to the entry's data object.  If
 *   such an entry is not found, hsearch() creates a new entry using the
 *   key and data objects specified by item and returns a pointer to the
 *   new entry's data object.
 *
 *   The hsearch_r() function is the reentrant version of hsearch().
 *
 * Returned Value:
 *   If successful, hsearch() and hsearch_r() return a pointer to the data
 *   object of the matching or newly created entry.  Otherwise, they return
 *   NULL.
 *
 ****************************************************************************/

FAR ENTRY *hsearch(ENTRY, ACTION);

/****************************************************************************
 * Name: hforeach
 *
 * Description:
 *   The hforeach() function iterates over the entries in the hashing table
 *   specified by htab.  The function is called for each entry in the
 *   table.  The function fn is called with the entry and the data argument.
 *   The data argument is passed to the function.
 *
 *   The hforeach_r() function is the reentrant version of hforeach().
 *
 * Returned Value:
 *   None
 *
 ****************************************************************************/

void hforeach(hforeach_t, FAR void *);

/****************************************************************************
 * Name: hcreate_r
 *
 * Description:
 *   Create a new hash table.
 *
 * Input Parameters:
 *   nel - The number of elements in the hash table.
 *   htab - The location to return the hash table reference.
 *
 * Returned Value:
 *   1 on success; 0 on failure with errno set appropriately.
 *
 ****************************************************************************/

int hcreate_r(size_t, FAR struct hsearch_data *);

/****************************************************************************
 * Name: hdestroy_r
 *
 * Description:
 *   Destroy a hash table.
 *
 * Input Parameters:
 *   htab - The hash table to be destroyed.
 *
 * Returned Value:
 *   None
 *
 ****************************************************************************/

void hdestroy_r(FAR struct hsearch_data *);

/****************************************************************************
 * Name: hsearch_r
 *
 * Description:
 *   Search a hash table.
 *
 * Input Parameters:
 *   item - The search key.
 *   action - The action to take.
 *   result - The location to return the search result.
 *   htab - The hash table to be searched.
 *
 * Returned Value:
 *   1 on success; 0 on failure with errno set appropriately.
 *
 ****************************************************************************/

int hsearch_r(ENTRY, ACTION, FAR ENTRY **, FAR struct hsearch_data *);

/****************************************************************************
 * Name: hforeach_r
 *
 * Description:
 *   Iterate over the entries in a hash table.
 *
 * Input Parameters:
 *   handle - The function to call for each entry.
 *   data - The data to pass to the function.
 *   htab - The hash table to be iterated.
 *
 * Returned Value:
 *   None
 *
 ****************************************************************************/

void hforeach_r(hforeach_t, FAR void *, FAR struct hsearch_data *);

#endif /* __INCLUDE_SEARCH_H */