diff --git a/2.4. vtype_map.md b/2.4. vtype_map.md index ab95d47..4309df8 100644 --- a/2.4. vtype_map.md +++ b/2.4. vtype_map.md @@ -19,15 +19,125 @@ ##### Базовый блок +- `void map_init(vtype_map* x, vtype key_type)` + + - Принимает указатель на область памяти, содержащую инициализируемый контейнер `x`. + - Принимает значение типа `key_type`, определяющий тип содержащихся ключей внутри инициализируемого контейнера. + - Инициализирует контейнер, оставляя его пустым, позволяя использовать его в дальнейшей логике приложения. + + ##### Макросы +- `int map_pop(vtype_map* x, T key, void* data, CallbackT callback)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_map** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Принимает указатель на произвольные пользовательские данные `data` + - Принимает указатель на функцию-callback (см. начало текущего документа) + - Вызывает callback-функцию cо значением найденной ячейки, ключ которой равен `key`, в качестве аргумента. После чего удаляет найденный объект из контейнера. + - Возвращает -1, если ячейка со значением ключа, равным `key`, не была найдена внутри контейнера. В противном случае возвращает значение возвращенное пользовательской callback-функцией. + + +- `int map_get(vtype_map* x, T key, void* data, CallbackT callback)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_map** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Принимает указатель на произвольные пользовательские данные `data` + - Принимает указатель на функцию-callback (см. начало текущего документа) + - Вызывает callback-функцию cо значением найденной ячейки, ключ которой равен `key`, в качестве аргумента. + - Возвращает -1, если ячейка со значением ключа, равным `key`, не была найдена внутри контейнера. В противном случае возвращает значение возвращенное пользовательской callback-функцией. + + +- `bool map_update(vtype_map* x, T key)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_map** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Добавляет полученное значение `key` в последовательность элементов контейнера. В случае, если производится попытка добавить значение, с несравнимым типом относительно типа, которым был инициализирован контейнер, находящийся в области памяти `x` (см. [1.1. Система типов](https://gogs.lirent.ru/lirent/libcdsb/wiki/1.1.+%D0%A1%D0%B8%D1%81%D1%82%D0%B5%D0%BC%D0%B0+%D1%82%D0%B8%D0%BF%D0%BE%D0%B2)), будет вызван системный вызов `abort()`. + - Возвращает `true`, в случае, если вставка прошла успешно и `false` если аналогичное значение уже имеется внутри контейнера. + + +- `int map_remove(vtype_map* x, T key)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_map** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Возвращает `0`, в случае успешного удаления элемента, или `-1` в случае, если значение `key` не было найдено. + + +- `bool in_map(vtype_map* x, T key)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_map** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Возвращает `true` если значение `key` найдено в контейнере, в противном случае, возвращает `false`. + + ### [include/extra/map.h](https://gogs.lirent.ru/lirent/libcdsb/src/master/include/extra/map.h) ##### Макросы +- `int map_foreach(vtype_map* x, void* data, CallbackT callback)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_map** `x`. + - Принимает указатель на произвольные пользовательские данные `data`. + - Принимает указатель на функцию-callback (см. начало текущего документа). + - Вызывает callback-функцию последовательно, с каждым элементом контейнера, в качестве аргумента. Если callback возвращает значение отличное от 0, то перебор будет прерван. + - Возвращает 0, в случае успеха, или любое другое значение, возвращенное пользовательской callback-функцией. + + +- `vtype_set map_copy_keys(const vtype_map* s)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_map** `s`. + - Возвращает глубокую копию полного набора ключей, использованных внутри контейнера `s`. + + +- `vtype_set* map_duplicate_keys(const vtype_map* s)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_map** `s`. + - Возвращает выделенный блок памяти, содержащий глубокую копию полного набора ключей, использованных внутри контейнера `s`. + +- `void map_copy_init_keys(vtype_set* x, const vtype_map* s)` + + - Принимает указатель на область памяти, содержащую инициализируемый контейнер `x`. + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_map** `s`. + - Инициализирует область памяти `x` глубокой копией полного набора ключей, использованных внутри контейнера `s`. + + ##### Дополнительный блок +- `ssize_t libcdsb_map_update(vtype_map* x, const void* key, vtype key_type, const void* value, vtype value_type)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_set** `x`. + - Принимает указатель на передаваемый ключ `key`. + - Принимает константу идентификатора типа ключа `key_type`. + - Принимает указатель на передаваемые данные `value`. + - Принимает константу идентификатора типа данных `value_type`. + - Обновляет значение ячейки с ключом равным `key` внутри контейнера и присваивает данным значение равное `value`. В случае, если ячейки с ключом равным `key` в контейнере не существует, она будет создана. Если производится попытка добавить значение, с несравнимым типом ключа относительно типа, которым был инициализирован контейнер, находящийся в области памяти `x` (см. [1.1. Система типов](https://gogs.lirent.ru/lirent/libcdsb/wiki/1.1.+%D0%A1%D0%B8%D1%81%D1%82%D0%B5%D0%BC%D0%B0+%D1%82%D0%B8%D0%BF%D0%BE%D0%B2)), будет вызван системный вызов `abort()`. + - Возвращает `true`, в случае, если была произвена замена существующей ячейки и `false` если была произведена вставка новой ячейки. + + +- `int libcdsb_map_find(vtype_map* x, const void* key, vtype key_type, void* data, CallbackT callback, bool reverse, bool cut)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_map** `x`. + - Принимает указатель на передаваемые данные `key`. + - Принимает константу идентификатора типа данных `key_type`. + - Принимает указатель на произвольные пользовательские данные `data`. + - Принимает указатель на функцию-callback (см. начало текущего документа). + - Принимает **bool** значение `reverse` указывающее на необходимость поиска значения с конца. + - Принимает **bool** значение `cut`, указывающее на необходимость удаление найденного элемента. + - Вызывает callback-функцию cо значением найденной ячейки, ключ которой равен `key`, в качестве аргумента. + - Возвращает -1, если ячейка со значением ключа, равным `key`, не была найдена внутри контейнера. В противном случае возвращает значение возвращенное пользовательской callback-функцией. + + +- `int libcdsb_map_foreach(vtype_map* x, void* data, CallbackT callback, bool flush)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_map** `x`. + - Принимает указатель на произвольные пользовательские данные `data`. + - Принимает указатель на функцию-callback (см. начало текущего документа). + - Принимает **bool** значение `flush`, указывающее на необходимость очистки контейнера после выполнения перебора. + - Вызывает callback-функцию последовательно, с каждым элементом контейнера, в качестве аргумента. Если callback возвращает значение отличное от 0, то перебор будет прерван. Если установлен флаг `flush`, то очистка контейнера произойдет в любом случае, вне зависимости от того, было ли прерывание перебора со стороны пользователя. + - Возвращает 0, в случае успеха, или любое другое значение, возвращенное пользовательской callback-функцией. + + [Далее: 2.5. vtype_set](https://gogs.lirent.ru/lirent/libcdsb/wiki/2.5.+vtype_set) \ No newline at end of file