HSEARCH(3)

BEZEICHNUNG
hcreate, hdestroy, hsearch - hash table management

ÜBERSICHT
#include <search.h>

ENTRY *hsearch(ENTRY item, ACTION action);

int     hcreate (unsigned nel);

void    hdestroy (void);

BESCHREIBUNG
Diese drei Funktionen erlauben dem Anwender eine Hashtabelle anzulegen, die einen Schlüssel mit irgendwelchen Daten verbindet. Zuerst muß die Tabelle mit hcreate() erzeugt werden. nel ist die geschätzte Größe der Tabelle. hcreate() kann diesen Wert nach oben korrigieren, um die Performance des Algorithmusses zu verbessern. Die GNU-Implementierung von hsearch() wird die Tabelle ebenfalls verlängern, wenn sie fast voll ist. malloc(3) wird verwendet, um Speicherplatz zu alloziieren. Die entsprechende Funktion hdestroy() gibt den Speicher wieder frei, der von der Hashtabelle belegt wurde, um so Platz für eine neue Tabelle zu schaffen. item ist vom Typ ENTRY, der in <search.h> definiert wurde und folgende Elemente enthält:

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

key zeigt auf eine null-terminierte ASCII-Zeichenkette, die den Suchschlüssel repräsentiert. data zeigt auf das Datum, das mit dem Schlüssel verbunden ist. (Ein Zeiger auf einen anderen Typ als char sollte auf einen char * gecastet werden.) hsearch() sucht nach item in der Hashtabelle und gibt bei Erfolg einen Zeiger darauf zurück, ansonsten NULL. action bestimmt, wie sich hsearch() nach erfolgloser Suche verhält. Der Wert ENTER bewirkt, daß item in die Tabelle eingefügt wird, während der Wert FIND hsearch() anweist NULL zurückzugeben.

RÜCKGABEWERT
hcreate() gibt NULL zurück, wenn die Hashtabelle nicht erfolgreich angelegt werden konnte. hsearch() gibt NULL zurück, wenn action ENTER ist und nicht ausreichend Speicher zur Verfügung steht, um die Hashtabelle zu erweitern, oder wenn action FIND ist und item nicht in der Tabelle gefunden werden konnte.

KONFORM ZU
SVID, außer, daß die Tabelle bei SysV nicht wachsen kann.

FEHLER
Diese Implementierung kann nur eine Hashtabelle zur gleichen Zeit verwalten. Einzelne Einträge können inzugefügt, jedoch nicht gelöscht werden.

BEISPIEL

Das folgende Programm fügt 24 Einträge in die Hashtabelle ein und zeigt dann einige.
    #include <stdio.h>
    #include <search.h>

    char *data[]={ "alpha", "bravo", "charley", "delta",
         "echo", "foxtrot", "golf", "hotel", "india", "juliette",
         "kilo", "lima", "mike", "november", "oscar", "papa",
         "quebec", "romeo", "sierra", "tango", "uniform",
         "victor", "whiskey", "x-ray", "yankee", "zulu"
     };
    int main()
    {
      ENTRY e, *ep;
      int i;

      /* Fang mit einer kleinen Tabelle an und laß sie wachsen */
      hcreate(3);
      for (i = 0; i < 24; i++)
        {
          e.key = data[i];
          /* Datum ist nur eine Ganzzahl anstelle eines Zeigers auf
             irgendetwas */
          e.data = (char *)i;
          ep = hsearch(e, ENTER);
          /* Es sollte keine Fehler geben */
          if(ep == NULL) {fprintf(stderr, "entry failed\n"); exit(1);}
        }
      for (i = 22; i < 26; i++)
        /* Gib zwei Einträge der Tabelle aus und zeige, daß zwei nicht
           in der Tabelle enthalten sind */
        {
          e.key = data[i];
          ep = hsearch(e, FIND);
          printf("%9.9s -> %9.9s:%d\n", e.key, ep?ep->key:"NULL",
                 ep?(int)(ep->data):0);
        }
      return 0;
    }

SIEHE AUCH
bsearch(3), lsearch(3), tsearch(3), malloc(3).