From 0b37a8c1995d53ecb981a005b8cfaaed8d19ea3c Mon Sep 17 00:00:00 2001 From: Gregory Lirent Date: Wed, 17 Aug 2022 19:19:45 +0300 Subject: [PATCH] Update page '2.5. vtype_set' --- 2.5. vtype_set.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) diff --git a/2.5. vtype_set.md b/2.5. vtype_set.md index b7bd9d5..a10e354 100644 --- a/2.5. vtype_set.md +++ b/2.5. vtype_set.md @@ -1,22 +1,115 @@ ## vtype_set +Набор неизменяемых уникальных данных, с заранее обозначенным типом значений. Контейнер основан на красно-черном дереве, в связи с чем, обладает всеми преимуществами и недостатками оного. + ### [include/set.h](https://gogs.lirent.ru/lirent/libcdsb/src/master/include/set.h) ##### Интерфейс callback-функции доступа к элементу (далее CallbackT) +- `int callback(const void* value, ssize_t index, vtype type, void* data)` + + - `value`: указатель на область памяти, в которой располагается объект, доступ к которому обеспечивается данной функцией. Изменение данных недопустимо и ведет к неопределенному поведению программы. + - `index`: индекс элемента, к которому обеспечивается доступ, в рамках контейнера. + - `type`: значение типа, заданное константой перечисления **vtype**, соответствующее типу данных, к которым обеспечивается доступ. + - `data`: произвольные пользовательские данные, которые будут переданны в callback вызывающим методом. + + ##### Базовый блок +- `void vset_init(vtype_set* x, vtype type)` + + - Принимает указатель на область памяти, содержащую инициализируемый контейнер `x`. + - Принимает значение типа `type`, определяющий содержащиеся данные внутри инициализируемого контейнера. + - Инициализирует контейнер, оставляя его пустым, позволяя использовать его в дальнейшей логике приложения. + + ##### Макросы +- `int vset_pop(vtype_set* x, T value, void* data, CallbackT callback)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_set** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Принимает указатель на произвольные пользовательские данные `data` + - Принимает указатель на функцию-callback (см. начало текущего документа) + - Вызывает callback-функцию c найденным значением, равным `value`, в качестве аргумента. После чего удаляет найденный объект из контейнера. + - Возвращает -1, если значение равное `value` не было найдено внутри контейнера. В противном случае возвращает значение возвращенное callback-функцией. + + +- `int vset_get(vtype_set* x, T value, void* data, CallbackT callback)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_set** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Принимает указатель на произвольные пользовательские данные `data` + - Принимает указатель на функцию-callback (см. начало текущего документа) + - Вызывает callback-функцию c найденным значением, равным `value`, в качестве аргумента. + - Возвращает -1, если значение равное `value` не было найдено внутри контейнера. В противном случае возвращает значение возвращенное callback-функцией. + + +- `bool vset_push(vtype_set* x, T value)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_set** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Добавляет полученное значение `value` в последовательность элементов контейнера. В случае, если производится попытка добавить значение, с несравнимым типом относительно типа, которым был инициализирован контейнер, находящийся в области памяти `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` если аналогичное значение уже имеется внутри контейнера. + + +- `bool in_vset(vtype_set* x, T value)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_set** `x`. + - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом. + - Возвращает `true` если значение `value` найдено в контейнере, в противном случае, возвращает `false`. + + ### [include/extra/set.h](https://gogs.lirent.ru/lirent/libcdsb/src/master/include/extra/set.h) ##### Макросы +- `int vset_foreach(vtype_set* x, void* data, CallbackT callback)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_set** `x`. + - Принимает указатель на произвольные пользовательские данные `data`. + - Принимает указатель на функцию-callback (см. начало текущего документа). + - Вызывает callback-функцию последовательно, с каждым элементом контейнера, в качестве аргумента. Если callback возвращает значение отличное от 0, то перебор будет прерван. + - Возвращает 0, в случае успеха, или любое другое значение, возвращенное пользовательской callback-функцией. + + ##### Дополнительный блок +- `ssize_t libcdsb_vset_insert(vtype_set* x, const void* value, vtype value_type)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_set** `x`. + - Принимает указатель на передаваемые данные `value`. + - Принимает константу идентификатора типа данных `value_type`. + - Добавляет полученное значение `value` в последовательность элементов контейнера. В случае, если производится попытка добавить значение, с несравнимым типом относительно типа, которым был инициализирован контейнер, находящийся в области памяти `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_vset_find(vtype_set* x, const void* value, vtype type, void* data, CallbackT callback, bool reverse, bool cut)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_set** `x`. + - Принимает указатель на передаваемые данные `value`. + - Принимает константу идентификатора типа данных `value_type`. + - Принимает указатель на произвольные пользовательские данные `data`. + - Принимает указатель на функцию-callback (см. начало текущего документа). + - Принимает **bool** значение `reverse` указывающее на необходимость поиска значения с конца. + - Принимает **bool** значение `cut`, указывающее на необходимость удаление найденного элемента. + - Вызывает callback-функцию c найденным значением, равным `value`, в качестве аргумента. + - Возвращает -1, если значение равное `value` не было найдено внутри контейнера. В противном случае возвращает значение возвращенное callback-функцией. + + +- `int libcdsb_vset_foreach(vtype_set* x, void* data, CallbackT callback, bool flush)` + + - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_set** `x`. + - Принимает указатель на произвольные пользовательские данные `data`. + - Принимает указатель на функцию-callback (см. начало текущего документа). + - Принимает **bool** значение `flush`, указывающее на необходимость очистки контейнера после выполнения перебора. + - Вызывает callback-функцию последовательно, с каждым элементом контейнера, в качестве аргумента. Если callback возвращает значение отличное от 0, то перебор будет прерван. Если установлен флаг `flush`, то очистка контейнера произойдет в любом случае, вне зависимости от того, было ли прерывание перебора со стороны пользователя. + - Возвращает 0, в случае успеха, или любое другое значение, возвращенное пользовательской callback-функцией. + + [Далее: 2.6. vtype_string](https://gogs.lirent.ru/lirent/libcdsb/wiki/2.6.+vtype_string) \ No newline at end of file