Update page '2.5. vtype_set'

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)