Update page '2.2. vtype_dict'
parent
d30e4cf813
commit
c62b90c2cc
@ -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)
|
||||
Loading…
Reference in New Issue
Block a user