10 2.2. vtype_dict

Gregory Lirent edited this page 2022-08-18 03:24:09 +03:00

Unescape Escape

Table of Contents

• vtype_dict
• include/dict.h
• Интерфейс callback-функции доступа к элементу (далее CallbackT)
• Базовый блок
• Макросы
• include/extra/dict.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_dict

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

include/dict.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 dict_init(vtype_dict* x)

  • Принимает указатель на область памяти, содержащую инициализируемый контейнер x.
  • Инициализирует контейнер, оставляя его пустым, позволяя использовать его в дальнейшей логике приложения.

Макросы

• int dict_pop(vtype_dict* x, T value, void* data, CallbackT callback)

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict x.
  • Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
  • Принимает указатель на произвольные пользовательские данные data
  • Принимает указатель на функцию-callback (см. начало текущего документа)
  • Вызывает callback-функцию cо значением найденной ячейки, ключ которой равен key, в качестве аргумента. После чего удаляет найденный объект из контейнера.
  • Возвращает -1, если ячейка со значением ключа, равным key, не была найдена внутри контейнера. В противном случае возвращает значение возвращенное пользовательской callback-функцией.

• int dict_get(vtype_dict* x, T value, void* data, CallbackT callback)

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict x.
  • Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
  • Принимает указатель на произвольные пользовательские данные data
  • Принимает указатель на функцию-callback (см. начало текущего документа)
  • Вызывает callback-функцию cо значением найденной ячейки, ключ которой равен key, в качестве аргумента.
  • Возвращает -1, если ячейка со значением ключа, равным key, не была найдена внутри контейнера. В противном случае возвращает значение возвращенное пользовательской callback-функцией.

• int dict_update(vtype_dict* x, T key, T value)

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict x.
  • Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
  • Добавляет полученное значение key в последовательность элементов контейнера.
  • Возвращает true, в случае, если вставка прошла успешно и false если аналогичное значение уже имеется внутри контейнера.

• int dict_remove(vtype_dict* x, T key)

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict x.
  • Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
  • Возвращает 0, в случае успешного удаления элемента, или -1 в случае, если значение key не было найдено.

• bool in_dict(vtype_dict* x, T key)

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict x.
  • Принимает числовое значение, указатель на C-строку или указатель на область памяти, содержащую один из контейнеров, поставляемых вместе с данным проектом.
  • Возвращает true если значение key найдено в контейнере, в противном случае, возвращает false.

include/extra/dict.h

Макросы

• int dict_foreach(vtype_dict* x, void* data, CallbackT callback)

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict x.
  • Принимает указатель на произвольные пользовательские данные data.
  • Принимает указатель на функцию-callback (см. начало текущего документа).
  • Вызывает callback-функцию последовательно, с каждым элементом контейнера, в качестве аргумента. Если callback возвращает значение отличное от 0, то перебор будет прерван.
  • Возвращает 0, в случае успеха, или любое другое значение, возвращенное пользовательской callback-функцией.

• vtype_list dict_copy_keys(const vtype_dict* s)

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict s.
  • Возвращает глубокую копию полного набора ключей, использованных внутри контейнера s.

• vtype_list* dict_duplicate_keys(const vtype_dict* s)

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict s.
  • Возвращает выделенный блок памяти, содержащий глубокую копию полного набора ключей, использованных внутри контейнера s.

• void dict_copy_init_keys(vtype_list* x, const vtype_dict* s)

  • Принимает указатель на область памяти, содержащую инициализируемый контейнер x.
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict s.
  • Инициализирует область памяти x глубокой копией полного набора ключей, использованных внутри контейнера s.

Дополнительный блок

• bool libcdsb_dict_update(vtype_dict* x, const void* key, vtype key_type, const void* value, vtype value_type)

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict x.
  • Принимает указатель на передаваемый ключ key.
  • Принимает константу идентификатора типа ключа key_type.
  • Принимает указатель на передаваемые данные value.
  • Принимает константу идентификатора типа данных value_type.
  • Обновляет значение ячейки с ключом равным key внутри контейнера и присваивает данным значение равное value. В случае, если ячейки с ключом равным key в контейнере не существует, она будет создана.
  • Возвращает true, в случае, если была произвена замена существующей ячейки и false если была произведена вставка новой ячейки.

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

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict x.
  • Принимает указатель на передаваемые данные key.
  • Принимает константу идентификатора типа данных key_type.
  • Принимает указатель на произвольные пользовательские данные data.
  • Принимает указатель на функцию-callback (см. начало текущего документа).
  • Принимает bool значение cut, указывающее на необходимость удаление найденного элемента.
  • Вызывает callback-функцию cо значением найденной ячейки, ключ которой равен key, в качестве аргумента.
  • Возвращает -1, если ячейка со значением ключа, равным key, не была найдена внутри контейнера. В противном случае возвращает значение возвращенное пользовательской callback-функцией.

• int libcdsb_dict_foreach(vtype_dict* x, void* data, CallbackT callback, bool flush)

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict x.
  • Принимает указатель на произвольные пользовательские данные data.
  • Принимает указатель на функцию-callback (см. начало текущего документа).
  • Принимает bool значение flush, указывающее на необходимость очистки контейнера после выполнения перебора.
  • Вызывает callback-функцию последовательно, с каждым элементом контейнера, в качестве аргумента. Если callback возвращает значение отличное от 0, то перебор будет прерван. Если установлен флаг flush, то очистка контейнера произойдет в любом случае, вне зависимости от того, было ли прерывание перебора со стороны пользователя.
  • Возвращает 0, в случае успеха, или любое другое значение, возвращенное пользовательской callback-функцией.

• bool libcdsb_dict_shrink_to_fit(vtype_dict* x)

  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict x.
  • Усекает размер выделенной памяти до приемлемого уровня так, чтобы в выделенный блок помещались все содержащиеся данные в контейнере данные, без критического увеличения уровня коллизий.
  • Возвращает true, если усечение было произведено и false в противном случае.

Далее: 2.3. vtype_list