Update page '2.3. vtype_list'

2.3. vtype_list.md

@@ -1,45 +1,146 @@
 ## vtype_list
 
+Двунаправленный связанный список, позволяющий размещать внутри себя значения с произвольным типом.
+
 ### [include/list.h](https://gogs.lirent.ru/lirent/libcdsb/src/master/include/list.h)
 
 ##### Интерфейс callback-функции доступа к элементу (далее CallbackT)
-- ``
+
+
+- `int callback(void* value, ssize_t index, vtype type, void* data)`
+
+    - `value`: указатель на область памяти, в которой располагается объект, доступ к которому обеспечивается данной функцией.
+    - `index`: индекс элемента, к которому обеспечивается доступ, в рамках контейнера.
+    - `type`: значение типа, заданное константой перечисления **vtype**, соответствующее типу данных, к которым обеспечивается доступ.
+    - `data`: произвольные пользовательские данные, которые будут переданны в callback вызывающим методом. 
+
 
 
 ##### Базовый блок
-- ``
+
-- ``
+
-- ``
+- `void list_init(vtype_list* x, vtype type)`
-- ``
+
-- ``
+  - Принимает указатель на область памяти, содержащую инициализируемый контейнер `x`.
-- ``
+  - Принимает значение типа `type`, определяющий содержащиеся данные внутри инициализируемого контейнера.
-- ``
+  - Инициализирует контейнер, оставляя его пустым, позволяя использовать его в дальнейшей логике приложения.
-- ``
+
-- ``
+
-- ``
+- `void list_extend(vtype_list* x, const vtype_list* s)`
-- ``
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
-- ``
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `s`.
-- ``
+  - Производит глубокое копирование всех элементов `s` в конец контейнера `x`.
-- ``
+
+
+- `size_t list_slice(vtype_list* x, vtype_array* src, ssize_t index, size_t count, bool cut)`
+
+  - Принимает указатель на область памяти, содержащую инициализируемый контейнер `x`.
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `src`.
+  - Принимает значение индекса данных `index`, начиная с которого, требуется начать "срез" данных. Отрицательные значения индекса указывают на элементы, начианая с последнего (где индекс -1 указывает на последний элемент контейнера). Если отрицательное значение индекса по модулю превышает размерность контейнера, то будет считаться, что запрос сделан с индексом равным нулю.
+  - Принимает значение количества элементов `count`, которым необходимо инициализировать `x` в рамках "среза" данных `src`, начиная с `index`. В случае, если количество элементов, начиная с `index` меньше `count`, вместо `count` будет использовано количество оставшихся элементов.
+  - Принимает булевое значение `cut`, сообщающее о необходимости вырезать полученный "срез" данных из `src`.
+  - Возвращает итоговое количество элементов, вошедших в "срез".
+
+
+- `void list_sort(vtype_list* x)`
+
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
+  - Производит быструю сортировку значений в контейнере (от меньшего к большему).
+
+
+- `void list_reverse(vtype_list* x)`
+
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
+  - Переворачивает последовательность элементов в контейнере.
 
 
 ##### Макросы
-- ``
-- ``
-- ``
-- ``
-- ``
-- ``
-- ``
-- ``
-- ``
-- ``
-- ``
-- ``
-- ``
-- ``
 
 
+- `int list_pop(vtype_list* x, T value, void* data, CallbackT callback)`
+
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
+  - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
+  - Принимает указатель на произвольные пользовательские данные `data`
+  - Принимает указатель на функцию-callback (см. начало текущего документа)
+  - Вызывает callback-функцию c первым найденным значением, равным `value`, в качестве аргумента. После чего удаляет найденный объект из контейнера.
+  - Возвращает -1, если значение равное `value` не было найдено внутри контейнера. В противном случае возвращает значение возвращенное callback-функцией.
+
+
+- `int vtype_list(vtype_array* x, T value, void* data, CallbackT callback)`
+
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
+  - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
+  - Принимает указатель на произвольные пользовательские данные `data`
+  - Принимает указатель на функцию-callback (см. начало текущего документа)
+  - Вызывает callback-функцию c первым найденным значением, равным `value`, в качестве аргумента.
+  - Возвращает -1, если значение равное `value` не было найдено внутри контейнера. В противном случае возвращает значение возвращенное callback-функцией.
+
+
+- `int vtype_list(vtype_list* x, T value, void* data, CallbackT callback)`
+
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
+  - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
+  - Принимает указатель на произвольные пользовательские данные `data`
+  - Принимает указатель на функцию-callback (см. начало текущего документа)
+  - Вызывает callback-функцию c последним найденным значением, равным `value`, в качестве аргумента.
+  - Возвращает -1, если значение равное `value` не было найдено внутри контейнера. В противном случае возвращает значение возвращенное callback-функцией.
+
+
+- `size_t list_countof(vtype_list* x, T value)`
+
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
+  - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
+  - Возвращает количество элементов, равных `value` (см. [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)).
+
+
+- `int list_remove(vtype_list* x, T value)`
+
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
+  - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
+  - Возвращает `0`, в случае успешного удаления элемента, или `-1` в случае, если значение `value` не было найдено.
+
+
+- `bool in_list(vtype_list* x, T value)`
+
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
+  - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
+  - Возвращает `true` если значение `value` найдено в контейнере, в противном случае, возвращает `false`.
+
+
+- `bool list_insert(vtype_list* x, ssize_t index, T value)`
+
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
+  - Принимает значение индекса данных `index`, которые следует вставить. Отрицательные значения индекса указывают на элементы, начианая с последнего (где индекс -1 указывает на последний элемент массива). Если отрицательное значение индекса по модулю превышает размерность массива, то будет считаться, что запрос сделан с индексом равным нулю.
+  - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
+  - Вставляет `value` по указанному индексу, сдвигая уже существующие данные, в следующую ячейку. Если индекс выходит за границы области памяти, принадлежащей контейнеру, вставка производится в конец контейнера.
+  - Возвращает `true`.
+
+
+- `bool list_replace(vtype_list* x, ssize_t index, T value)`
+
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
+  - Принимает значение индекса данных `index`, которые следует заменить. Отрицательные значения индекса указывают на элементы, начианая с последнего (где индекс -1 указывает на последний элемент массива). Если отрицательное значение индекса по модулю превышает размерность массива, то будет считаться, что запрос сделан с индексом равным нулю.
+  - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
+  - Производит замену данных, находящихся по заданному индексу, на `value`.
+  - Возвращает `true`, если замена произведена успешно и `false`, если индекс выходит за границы области памяти, принадлежащей контейнеру.
+
+
+- `bool list_push_back(vtype_list* x, T value)`
+
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
+  - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
+  - Добавляет полученное значение `value` в конец последовательности элементов контейнера.
+  - Возвращает `true`.
+
+
+- `bool list_push_front(vtype_list* x, T value)`
+
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
+  - Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
+  - Добавляет полученное значение `value` в начало последовательности элементов контейнера.
+  - Возвращает `true`.
+
 
 ### [include/extra/list.h](https://gogs.lirent.ru/lirent/libcdsb/src/master/include/extra/list.h)
 
@@ -49,7 +150,7 @@
 - `int list_get_by_index(vtype_list* x, ssize_t index, void* data, CallbackT callback)`
 
   - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
-  - Принимает значение индекса данных `index`, которые следует вернуть. Отрицательные значения индекса указывают на элементы, начианая с последнего (где индекс -1 указывает на последний элемент массива). Если отрицательное значение индекса по модулю превышает размерность массива, то будет считаться, что запрос сделан с индексом равным нулю.
+  - Принимает значение индекса данных `index`, которые следует вернуть. Отрицательные значения индекса указывают на элементы, начианая с последнего (где индекс -1 указывает на последний элемент контейнера). Если отрицательное значение индекса по модулю превышает размерность контейнера, то будет считаться, что запрос сделан с индексом равным нулю.
   - Принимает указатель на произвольные пользовательские данные `data`.
   - Принимает указатель на функцию-callback (см. начало текущего документа).
   - Вызывает callback-функцию cо значением находящимся по запрошенному индексу, в качестве аргумента.
@@ -59,7 +160,7 @@
 - `int list_pop_by_index(vtype_list* x, ssize_t index, void* data, CallbackT callback)`
 
   - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
-  - Принимает значение индекса данных `index`, которые следует вернуть. Отрицательные значения индекса указывают на элементы, начианая с последнего (где индекс -1 указывает на последний элемент массива). Если отрицательное значение индекса по модулю превышает размерность массива, то будет считаться, что запрос сделан с индексом равным нулю.
+  - Принимает значение индекса данных `index`, которые следует вернуть. Отрицательные значения индекса указывают на элементы, начианая с последнего (где индекс -1 указывает на последний элемент контейнера). Если отрицательное значение индекса по модулю превышает размерность контейнера, то будет считаться, что запрос сделан с индексом равным нулю.
   - Принимает указатель на произвольные пользовательские данные `data`.
   - Принимает указатель на функцию-callback (см. начало текущего документа).
   - Вызывает callback-функцию cо значением находящимся по запрошенному индексу, в качестве аргумента. После чего удаляет данный объект из контейнера.
@@ -69,7 +170,7 @@
 - `int list_remove_by_index(vtype_list* x, ssize_t index)`
 
   - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
-  - Принимает значение индекса данных `index`, которые следует вернуть. Отрицательные значения индекса указывают на элементы, начианая с последнего (где индекс -1 указывает на последний элемент массива). Если отрицательное значение индекса по модулю превышает размерность массива, то будет считаться, что запрос сделан с индексом равным нулю.
+  - Принимает значение индекса данных `index`, которые следует вернуть. Отрицательные значения индекса указывают на элементы, начианая с последнего (где индекс -1 указывает на последний элемент контейнера). Если отрицательное значение индекса по модулю превышает размерность контейнера, то будет считаться, что запрос сделан с индексом равным нулю.
   - Возвращает `0`, в случае успешного удаления элемента, или `-1` в случае, если индекс выходит за границы области памяти, принадлежащей контейнеру.
 
 
@@ -86,11 +187,15 @@
 ##### Дополнительный блок
 
 
-- `bool libcdsb_list_update(vtype_list*  x, ssize_t index, const void* value, vtype type, int ins_direction)`
+- `bool libcdsb_list_update(vtype_list* x, ssize_t index, const void* value, vtype type, int ins_direction)`
 
-  - ..
+  - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
-  - ..
+  - Принимает значение индекса "якорных" данных `index`, определяющих место, отталкиваясь от которого, будет произведено дальнейшее изменение контейнера. Отрицательные значения индекса указывают на элементы, начианая с последнего (где индекс -1 указывает на последний элемент контейнера). Если отрицательное значение индекса по модулю превышает размерность контейнера, то будет считаться, что запрос сделан с индексом равным нулю.
-  - ..
+  - Принимает указатель на передаваемые данные `value`.
+  - Принимает константу идентификатора типа данных `value_type`.
+  - Принимает значение `ins_direction` которое определяет то, будут ли данные по указанному индексу заменены (значение `ins_direction == 0`), или будет произведена вставка `value`: в ячейку перед индексом (значение `ins_direction < 0`) или в ячейку после (значение `ins_direction > 0`)
+  - Производит вставку или замену данных в контейнере, на оснавнии значения `ins_direction` и `index`
+  - Возвращает `true` при успехе и `false`, если индекс выходит за границы области памяти, принадлежащей контейнеру (только в случае, если `ins_direction == 0`.
 
 
 - `size_t libcdsb_list_count(const vtype_list* s, const void* value, vtype type)`
@@ -117,7 +222,7 @@
 - `int libcdsb_list_get(vtype_list* x, ssize_t index, void* data, CallbackT callback, bool cut)`
 
   - Принимает указатель на область памяти, содержащую инициализированное значение **vtype_list** `x`.
-  - Принимает значение индекса данных `index`, которые следует вернуть. Отрицательные значения индекса указывают на элементы, начианая с последнего (где индекс -1 указывает на последний элемент массива). Если отрицательное значение индекса по модулю превышает размерность массива, то будет считаться, что запрос сделан с индексом равным нулю.
+  - Принимает значение индекса данных `index`, которые следует вернуть. Отрицательные значения индекса указывают на элементы, начианая с последнего (где индекс -1 указывает на последний элемент контейнера). Если отрицательное значение индекса по модулю превышает размерность контейнера, то будет считаться, что запрос сделан с индексом равным нулю.
   - Принимает указатель на произвольные пользовательские данные `data`.
   - Принимает указатель на функцию-callback (см. начало текущего документа).
   - Принимает **bool** значение `cut`, указывающее на необходимость удаление элемента по указанному индексу.