9 2.4. vtype_map

Gregory Lirent edited this page 2022-08-17 20:20:30 +03:00

Unescape Escape

Table of Contents

• vtype_map
• include/map.h
• Интерфейс callback-функции доступа к элементу (далее CallbackT)
• Базовый блок
• Макросы
• include/extra/map.h
• Макросы
• Дополнительный блок

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

vtype_map

Набор пар ключ-значение с неизменяемыми уникальными ключами. Тип содержащихся ключей должен быть определен при инициализации контейнера, данные могут иметь произвольный тип. Контейнер основан на красно-черном дереве (с поиском по ключу), в связи с чем, обладает всеми преимуществами и недостатками оного.

include/map.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 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. Система типов), будет вызван системный вызов 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

Макросы

• 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. Система типов), будет вызван системный вызов abort().
  • Возвращает true, в случае, если была произвена замена существующей ячейки и false если была произведена вставка новой ячейки.

• int libcdsb_map_find(vtype_map* x, const void* key, vtype key_type, void* data, CallbackT callback, bool cut)

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_map x.
  • Принимает указатель на передаваемые данные key.
  • Принимает константу идентификатора типа данных key_type.
  • Принимает указатель на произвольные пользовательские данные data.
  • Принимает указатель на функцию-callback (см. начало текущего документа).
  • Принимает 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