hcreate, hdestroy, hsearch - операции над ассоциативными массивами

НАЗВАНИЕ
hcreate, hdestroy, hsearch - операции над ассоциативными
массивами

СИНТАКСИС
#include

int hcreate(size_t nel);

ENTRY *hsearch(ENTRY item, ACTION action);

void hdestroy(void);

#define _GNU_SOURCE
#include

int hcreate_r(size_t nel, struct hsearch_data *tab);

int *hsearch_r(ENTRY item, ACTION action, ENTRY **ret,
struct hsearch_data *tab);

void hdestroy_r(struct hsearch_data *tab);

ОПИСАНИЕ
Функции hcreate, hsearch и hdestroy позволяют пользователю
создать (только один) ассоциативный массив (хэш), который
связывает ключ с любыми данными. Функции hcreate_r,
hsearch_r и hdestroy_r являются реентрантными версиями,
позволяющими создание более одной таблицы.

Во-первых, хэш должен быть создан с помощью функции hcre-
ate(). Аргумент nel указывает предполагаемое максимальное
количество элементов в хэше. Функция hcreate() может
увеличить этот параметр для повышения быстродействия
таблицы.

Соответствующая функция hdestroy() освобождает память,
занимаемую таблицей.

Аргумент item имеет тип ENTRY, который определен в
следующим образом:

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

Поле key указывает на оканчивающуюся NUL строку,
используемую в качестве ключа для поиска. Поле data
указывает на данные, связанные с ключом. Функция
hsearch() ищет в хэше элемент с ключом, равным item
(равенство определяется функцией strcmp(3)), и в случае
удачного завершения операции возвращает указатель на него.
Аргумент action определяет действие, вызываемое из
hsearch() после неудачного поиска. Значение ENTER
указывает, что копия item будет вставляться в хэш до того
момента, пока FIND не перестанет возвращать NULL.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функции hcreate() и hcreate_r() возвращают 0 в случае
ошибки при выделении памяти, иначе они возвращают
ненулевое значение. Функция hsearch() возвращает NULL,
если action равен ENTER и таблица полна, или если action
равен FIND и item не может быть найден в хэше.

Функция hsearch_r() возвращает 0, если action равен ENTER
и хэш полон, иначе возвращается ненулевое значение.

КОДЫ ОШИБОК
ENOMEM Недостаточно памяти.

СООТВЕТСТВИЕ СТАНДАРТАМ
Функции hcreate, hsearch и hdestroy взяты из SVID и
описаны в POSIX 1003.1-2001. Функции hcreate_r, hsearch_r
и hdestroy_r являются расширениями GNU.

ЗАМЕЧЕННЫЕ ОШИБКИ
SVID и POSIX 1003.1-2001 указывают, что action имеет
значение только при неудачном поиске, поэтому ENTER не
должно ничего делать при удачном поиске. Однако библитеки
libc и glibc обновляют data для указанного key в этом
случае.

Отдельные записи в хэше могут быть добавлены, но не
удалены.

ПРИМЕР
Следующая программа вставляет в таблицу 24 элемента, а
затем выводит на печать некоторые из них:
char *data[] = { "alpha", "bravo", "charlie", "delta",
"echo", "foxtrot", "golf", "hotel", "india", "juliet",
"kilo", "lima", "mike", "november", "oscar", "papa",
"quebec", "romeo", "sierra", "tango", "uniform",
"victor", "whisky", "x-ray", "yankee", "zulu"
};
int main() {
ENTRY e, *ep;
int i;
/* начать с небольшой таблицы и позволить ей увеличиваться не получится */
hcreate(30);
for (i = 0; i key : "NULL",
ep ? (int)(ep->data) : 0);
}
return 0;
}