diff --git a/2.2. vtype_dict.md b/2.2. vtype_dict.md index 452872b..22bd3e4 100644 --- a/2.2. vtype_dict.md +++ b/2.2. vtype_dict.md @@ -1,32 +1,127 @@ ## vtype_dict +Набор пар ключ-значение с неизменяемыми уникальными ключами. Тип содержащихся ключей произволен, данные также могут иметь произвольный тип. Контейнер основан на хэш-таблицах (с поиском по ключу), в связи с чем, обладает всеми преимуществами и недостатками оных. + ### [include/dict.h](https://gogs.lirent.ru/lirent/libcdsb/src/master/include/dict.h) ##### Интерфейс callback-функции доступа к элементу (далее CallbackT) + + - `int callback(const void* key, vtype key_type, void* value, vtype value_type, void* data)` + - `key`: указатель на область памяти, в которой располагается значение ключа ячейки контейнера, доступ к которой обеспечивается данной функцией. Изменение ключа недопустимо и ведет к неопределенному поведению программы. + - `key_type`: значение типа ключа, заданное константой перечисления **vtype**, соответствующее типу данных, к которым обеспечивается доступ. + - `value`: указатель на область памяти, в которой располагается значение данных ячейки контейнера, доступ к которой обеспечивается данной функцией. + - `value_type`: значение типа данных, заданное константой перечисления **vtype**, соответствующее типу данных, к которым обеспечивается доступ. + - `data`: произвольные пользовательские данные, которые будут переданны в callback вызывающим методом. + ##### Базовый блок + + - `void dict_init(vtype_dict* x)` + - Принимает указатель на область памяти, содержащую инициализируемый контейнер `x`. + - Инициализирует контейнер, оставляя его пустым, позволяя использовать его в дальнейшей логике приложения. + ##### Макросы + - `int dict_pop(vtype_dict* x, T value, void* data, CallbackT callback)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_dict** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Принимает указатель на произвольные пользовательские данные `data` + - Принимает указатель на функцию-callback (см. начало текущего документа) + - Вызывает callback-функцию cо значением найденной ячейки, ключ которой равен `key`, в качестве аргумента. После чего удаляет найденный объект из контейнера. + - Возвращает -1, если ячейка со значением ключа, равным `key`, не была найдена внутри контейнера. В противном случае возвращает значение возвращенное пользовательской callback-функцией. + + - `int dict_get(vtype_dict* x, T value, void* data, CallbackT callback)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_dict** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Принимает указатель на произвольные пользовательские данные `data` + - Принимает указатель на функцию-callback (см. начало текущего документа) + - Вызывает callback-функцию cо значением найденной ячейки, ключ которой равен `key`, в качестве аргумента. + - Возвращает -1, если ячейка со значением ключа, равным `key`, не была найдена внутри контейнера. В противном случае возвращает значение возвращенное пользовательской callback-функцией. + + - `int dict_update(vtype_dict* x, T key, T value)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_dict** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Добавляет полученное значение `key` в последовательность элементов контейнера. + - Возвращает `true`, в случае, если вставка прошла успешно и `false` если аналогичное значение уже имеется внутри контейнера. + + - `int dict_remove(vtype_dict* x, T key)` + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_dict** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Возвращает `0`, в случае успешного удаления элемента, или `-1` в случае, если значение `key` не было найдено. + + +- `bool in_dict(vtype_dict* x, T key)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_dict** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Возвращает `true` если значение `key` найдено в контейнере, в противном случае, возвращает `false`. + ### [include/extra/dict.h](https://gogs.lirent.ru/lirent/libcdsb/src/master/include/extra/dict.h) ##### Макросы + + - `int dict_foreach(vtype_dict* x, void* data, CallbackT callback)` + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_dict** `x`. + - Принимает указатель на произвольные пользовательские данные `data`. + - Принимает указатель на функцию-callback (см. начало текущего документа). + - Вызывает callback-функцию последовательно, с каждым элементом контейнера, в качестве аргумента. Если callback возвращает значение отличное от 0, то перебор будет прерван. + - Возвращает 0, в случае успеха, или любое другое значение, возвращенное пользовательской callback-функцией. + + ##### Дополнительный блок - `bool libcdsb_dict_update(vtype_dict* x, const void* key, vtype key_type, const void* value, vtype value_type)` -- `int libcdsb_dict_get(vtype_dict* x, const void* key, vtype key_type, void* data, CallbackT callback, bool cut)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_dict** `x`. + - Принимает указатель на передаваемый ключ `key`. + - Принимает константу идентификатора типа ключа `key_type`. + - Принимает указатель на передаваемые данные `value`. + - Принимает константу идентификатора типа данных `value_type`. + - Обновляет значение ячейки с ключом равным `key` внутри контейнера и присваивает данным значение равное `value`. В случае, если ячейки с ключом равным `key` в контейнере не существует, она будет создана. + - Возвращает `true`, в случае, если была произвена замена существующей ячейки и `false` если была произведена вставка новой ячейки. + + +- `int libcdsb_dict_find(vtype_dict* x, const void* key, vtype key_type, void* data, CallbackT callback, bool cut)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_dict** `x`. + - Принимает указатель на передаваемые данные `key`. + - Принимает константу идентификатора типа данных `key_type`. + - Принимает указатель на произвольные пользовательские данные `data`. + - Принимает указатель на функцию-callback (см. начало текущего документа). + - Принимает **bool** значение `cut`, указывающее на необходимость удаление найденного элемента. + - Вызывает callback-функцию cо значением найденной ячейки, ключ которой равен `key`, в качестве аргумента. + - Возвращает -1, если ячейка со значением ключа, равным `key`, не была найдена внутри контейнера. В противном случае возвращает значение возвращенное пользовательской callback-функцией. + + - `int libcdsb_dict_foreach(vtype_dict* x, void* data, CallbackT callback, bool flush)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_dict** `x`. + - Принимает указатель на произвольные пользовательские данные `data`. + - Принимает указатель на функцию-callback (см. начало текущего документа). + - Принимает **bool** значение `flush`, указывающее на необходимость очистки контейнера после выполнения перебора. + - Вызывает callback-функцию последовательно, с каждым элементом контейнера, в качестве аргумента. Если callback возвращает значение отличное от 0, то перебор будет прерван. Если установлен флаг `flush`, то очистка контейнера произойдет в любом случае, вне зависимости от того, было ли прерывание перебора со стороны пользователя. + - Возвращает 0, в случае успеха, или любое другое значение, возвращенное пользовательской callback-функцией. + + - `bool libcdsb_dict_shrink_to_fit(vtype_dict* x)` + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_dict** `x`. + - Усекает размер выделенной памяти до приемлемого уровня так, чтобы в выделенный блок помещались все содержащиеся данные в контейнере данные, без критического увеличения уровня коллизий. + - Возвращает `true`, если усечение было произведено и `false` в противном случае. + [Далее: 2.3. vtype_list](https://gogs.lirent.ru/lirent/libcdsb/wiki/2.3.+vtype_list) \ No newline at end of file