c/libcdsb
1
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity

Update page '2.2. vtype_dict'

Gregory Lirent 2022-08-17 20:26:36 +03:00
parent d30e4cf813
commit c62b90c2cc
1 changed files with 96 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
2.2. vtype_dict.md

@ -1,32 +1,127 @@
## vtype_dict ## vtype_dict
Набор пар ключ-значение с неизменяемыми уникальными ключами. Тип содержащихся ключей произволен, данные также могут иметь произвольный тип. Контейнер основан на хэш-таблицах (с поиском по ключу), в связи с чем, обладает всеми преимуществами и недостатками оных.
### [include/dict.h](https://gogs.lirent.ru/lirent/libcdsb/src/master/include/dict.h) ### [include/dict.h](https://gogs.lirent.ru/lirent/libcdsb/src/master/include/dict.h)
##### Интерфейс callback-функции доступа к элементу (далее CallbackT) ##### Интерфейс callback-функции доступа к элементу (далее CallbackT)
- `int callback(const void* key, vtype key_type, void* value, vtype value_type, void* data)` - `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)` - `void dict_init(vtype_dict* x)`
- Принимает указатель на область памяти, содержащую инициализируемый контейнер `x`.
- Инициализирует контейнер, оставляя его пустым, позволяя использовать его в дальнейшей логике приложения.
##### Макросы ##### Макросы
- `int dict_pop(vtype_dict* x, T value, void* data, CallbackT callback)` - `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)` - `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)` - `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)` - `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) ### [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)` - `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)` - `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)` - `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)` - `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) [Далее: 2.3. vtype_list](https://gogs.lirent.ru/lirent/libcdsb/wiki/2.3.+vtype_list)