HSEARCH(3)

名前
hcreate, hdestroy, hsearch - ハッシュテーブルの管理

書式
#include <search.h>

ENTRY *hsearch(ENTRY item, ACTION action);

int hcreate(unsigned nel);

void hdestroy(void);

説明
これら３つの関数を利用すると、ユーザはキーと任意のデータを関連づけるハッ シュテーブルを作成することができる。

最初に、関数 hcreate() によってテーブルを作成しなければならない。 nel は、テーブルのエントリー数の予想される値である。 hcreate() は、作成されるハッシュテーブルの性能を向上させるために この値を増やす場合もある。GNUの実装では、 テーブルがほとんど一杯になっ た場合、hsearch() によってもテーブルが拡張される。テーブルのため の領域を割り当てるためにmalloc(3) が用いられる。

これに対応する hdestroy() 関数は、ハッシュテーブルによって占有さ れていたメモリを開放し、新しいテーブルを作成できるようにする。

item は ENTRY 型であり、これは <search.h> の中で typedefされており、次の要素を含んでいる:

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

key は、サーチキーとなる0で終端されたASCII文字列を指す。 data は、このキーに対応するデータを指す。(文字型(char)以外の型へ のポインタは、文字型へのポインタにキャストすべきである) hsearch() は、item と同じキーを持つ項目をハッシュテーブル の中から探し、成功すればその項目へのポインタを返す。探索が失敗した場合、 action によって hsearch() の動作が決まる。値 ENTER は新しい項目を挿入し、値 FIND は NULL を返すことを意味する。

返り値
hcreate() は、ハッシュテーブルがうまく作成できない場合 NULL を返す。

hsearch() は、action が ENTER でしかもハッシュテーブ ルを拡張するのに十分なメモリが存在しない場合、または action が FIND でしかも item がハッシュテーブル内に見つからない場合 NULL を返す。

準拠

SysVにおいてはハッシュテーブルは拡張できないことを除き、SVID準拠。

バグ
このインプリメンテーションでは、一時に一つのハッシュテーブルしか管理で きない。 個々のハッシュテーブルエントリーを追加できるが、削除できない。

例

次のプログラムは、ハッシュテーブルに24個の項目を挿入し、それからそのう ちのいくつかを表示する。
    #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;

      /* start with small table, and let it grow */
      hcreate(3);
      for (i = 0; i < 24; i++)
        {
          e.key = data[i];
          /* data is just an integer, instead of a pointer
             to something */
          e.data = (char *)i;
          ep = hsearch(e, ENTER);
          /* there should be no failures */
          if(ep == NULL) {fprintf(stderr, "entry failed\n"); exit(1);}
        }
      for (i = 22; i < 26; i++)
        /* print two entries from the table, and show that
           two are not in the table */
        {
          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;
    }

関連項目
bsearch(3), lsearch(3), tsearch(3), malloc(3)