21 2. Заголовочные файлы

Gregory Lirent edited this page 2022-08-17 13:59:08 +03:00

Unescape Escape

Table of Contents

• Заголовочные файлы
• Система Generics и принципы именования
• include/vtype.h
• 1. Определение размера контейнера
• 2. Сравнение контейнеров между собой (также см. 1.1. Система типов)
• 3. Глубокое копирование контейнера
• 4. Глубокое копирование области памяти, содержащей контейнер
• 5. Инициализация контейнера значением другого контейнера
• 6. Высвобождение ресурсов контейнера
• 7. Подсчет хэша контейнера

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.

Заголовочные файлы

Структура пользовательских заголовочных файлов состоит из трех уровней:

• Декларация используемых типов и базовых методов для работы с ними: include/vtype.h
• Описание базовых методов для работы с содержимым контейнеров
  • include/array.h
  • include/dict.h
  • include/list.h
  • include/map.h
  • include/set.h
  • include/string.h
• Методы, предоставляющие расширенные возможности для работы с содержимым контейнеров:
  • include/extra/array.h
  • include/extra/dict.h
  • include/extra/list.h
  • include/extra/map.h
  • include/extra/set.h
  • include/extra/string.h

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

Отдельно следует выделить заголовочные файлы

• include/extra/cstring.h
• include/extra/memory.h
• include/extra/vtype.h

Где первые два предоставляют доступ к внутренним реализациям работы с памятью для пользовательского кода (в том числе повторяя или являясь оберткой над функционалом стандартной библиотеки), а последний - предоставляет методы для генерации C-строк (с основанием на значении vtype).

Система Generics и принципы именования

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

Например в файле include/array.h можно увидеть, что там присутствует набор символов libcdsb_array_push_, каждый из которых имеет свой уникальный постфикс. Постфикс всегда соответсвует типу, для которого создается вариант метода, а также никогда не изменяется в пределах проекта, при соответсвтии аналогичному типу, но в рамках иных методов.

Полная таблица соответствия выглядит так:

• const vtype_pointer -> pointer
• const char* -> cstring
• const vtype_string* -> string
• const vtype_array* -> array
• const vtype_list* -> list
• const vtype_map* -> map
• const vtype_vset* -> vset
• const vtype_dict* -> dict
• vtype_bool -> boolean
• vtype_uint8 -> uint8
• vtype_uint16 -> uint16
• vtype_uint32 -> uint32
• vtype_uint64 -> uint64
• vtype_int8 -> int8
• vtype_int16 -> int16
• vtype_int32 -> int32
• vtype_int64 -> int64
• vtype_float -> float
• vtype_double -> double
• vtype_ldouble -> ldouble

Тем не менее, предполагается, что подобные варианты методов не будут использоваться напрямую, так как для каждого метода, предполагающего возможность использования с несколькими вариантами типов, предоставляется _Generic макрос. В случае с libcdsb_array_push_ таковым макросом является array_push_back. Только подобные макросы будут рассмотрены в следующих подпунктах данного материала, при описании интерфейсов метода, так как, за исключением принимаемого типа, они не различимы, с точки зрения своего поведения.

Префиксом libcdsb_ помечаются те методы (и, потенциально, макросы), использование которых, в рамках пользовательского кода, требует большего внимания и глубины понимания происходящих процессов от пользователя. Так, в эту категорию, попадают практически все методы из блока extra.

include/vtype.h

Помимо декларации типов и перечисления vtype, предоставляющего функционал их идентификации, в файле задекларировано 7 базовых групп методов для работы с контейнерами.

1. Определение размера контейнера

• size_t string_size(const vtype_string* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_string.
  • Возвращает подсчитанное количество символов в строке (с поддержкой юникода).
• size_t string_nmemb(const vtype_string* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_string.
  • Возвращает подсчитанный размер строки в байтах (также как это сделал бы strlen)
• size_t array_size(const vtype_array* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_array.
  • Возвращает количество элементов находящихся внутри контейнера.
• size_t array_nmemb(const vtype_array* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_array.
  • Возвращает размер блока памяти контейнера в байтах.
• size_t list_size(const vtype_list* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_list.
  • Возвращает подсчитанное количество элементов, находящихся внутри контейнера.
• size_t map_size(const vtype_map* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_map.
  • Возвращает подсчитанное количество элементов, находящихся внутри контейнера.
• size_t vset_size(const vtype_set* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_set.
  • Возвращает подсчитанное количество элементов, находящихся внутри контейнера.
• size_t dict_size(const vtype_dict* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict.
  • Возвращает количество элементов, находящихся внутри контейнера.
• size_t dict_capacity(const vtype_dict* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict.
  • Возвращает текущий размер таблицы, доступной для вставки значений.

2. Сравнение контейнеров между собой (также см. 1.1. Система типов)

• int string_compare(const vtype_string* s0, const vtype_string* s1)
  • Принимает два указателя на области памяти, содержащие инициализированные значения vtype_string.
  • Возвращает 0 если строки равны, значения < 0 и > 0, если значение s0 меньше или больше значения s1 соответственно.
• int array_compare(const vtype_array* s0, const vtype_array* s1)
  • Принимает два указателя на области памяти, содержащие инициализированные значения vtype_array.
  • Возвращает 0 если значения контейнеров равны, значения < 0 и > 0, если значения s0 меньше или больше значений s1 соответственно.
• int list_compare(const vtype_list* s0, const vtype_list* s1)
  • Принимает два указателя на области памяти, содержащие инициализированные значения vtype_list.
  • Возвращает 0 если значения контейнеров равны, значения < 0 и > 0, если значения s0 меньше или больше значений s1 соответственно.
• int map_compare(const vtype_map* s0, const vtype_map* s1)
  • Принимает два указателя на области памяти, содержащие инициализированные значения vtype_map.
  • Возвращает 0 если значения контейнеров равны, значения < 0 и > 0, если значения s0 меньше или больше значений s1 соответственно.
• int vset_compare(const vtype_set* s0, const vtype_set* s1)
  • Принимает два указателя на области памяти, содержащие инициализированные значения vtype_set.
  • Возвращает 0 если значения контейнеров равны, значения < 0 и > 0, если значения s0 меньше или больше значений s1 соответственно.
• int dict_compare(const vtype_dict* s0, const vtype_dict* s1)
  • Принимает два указателя на области памяти, содержащие инициализированные значения vtype_dict.
  • Возвращает 0 если значения контейнеров равны, значения < 0 и > 0, если значения s0 меньше или больше значений s1 соответственно.

3. Глубокое копирование контейнера

• vtype_string string_copy(const vtype_string* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_string.
  • Возвращает новое инициализированное значение строки, равное содержимому s.
• vtype_array array_copy(const vtype_array* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_array.
  • Возвращает новое инициализированное значение контейнера, равное содержимому s.
• vtype_list list_copy(const vtype_list* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_list.
  • Возвращает новое инициализированное значение контейнера, равное содержимому s.
• vtype_map map_copy(const vtype_map* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_map.
  • Возвращает новое инициализированное значение контейнера, равное содержимому s.
• vtype_set vset_copy(const vtype_set* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_set.
  • Возвращает новое инициализированное значение контейнера, равное содержимому s.
• vtype_dict dict_copy(const vtype_dict* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict.
  • Возвращает новое инициализированное значение контейнера, равное содержимому s.

4. Глубокое копирование области памяти, содержащей контейнер

• vtype_string* string_duplicate(const vtype_string* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_string.
  • Возвращает новый выделенный блок памяти (равный sizeof(vtype_string)), инициализированный значением строки, равным содержимому s.
• vtype_array* array_duplicate(const vtype_array* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_array.
  • Возвращает новый выделенный блок памяти (равный sizeof(vtype_array)), инициализированный значением контейнера, равным содержимому s.
• vtype_list* list_duplicate(const vtype_list* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_list.
  • Возвращает новый выделенный блок памяти (равный sizeof(vtype_list)), инициализированный значением контейнера, равным содержимому s.
• vtype_map* map_duplicate(const vtype_map* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_map.
  • Возвращает новый выделенный блок памяти (равный sizeof(vtype_map)), инициализированный значением контейнера, равным содержимому s.
• vtype_set* vset_duplicate(const vtype_set* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_set.
  • Возвращает новый выделенный блок памяти (равный sizeof(vtype_set)), инициализированный значением контейнера, равным содержимому s.
• vtype_dict* dict_duplicate(const vtype_dict* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict.
  • Возвращает новый выделенный блок памяти (равный sizeof(vtype_dict)), инициализированный значением контейнера, равным содержимому s.

5. Инициализация контейнера значением другого контейнера

• void string_copy_init(vtype_string* x, const vtype_string* s)
  • Принимает указатель на область памяти, содержащую инициализируемую строку x.
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_string s.
  • Инициализирует область памяти x значением строки, равным содержимому s.
• void array_copy_init(vtype_array* x, const vtype_array* s)
  • Принимает указатель на область памяти, содержащую инициализируемый контейнер x.
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_array s.
  • Инициализирует область памяти x значением контейнера, равным содержимому s.
• void list_copy_init(vtype_list* x, const vtype_list* s)
  • Принимает указатель на область памяти, содержащую инициализируемый контейнер x.
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_list s.
  • Инициализирует область памяти x значением контейнера, равным содержимому s.
• void map_copy_init(vtype_map* x, const vtype_map* s)
  • Принимает указатель на область памяти, содержащую инициализируемый контейнер x.
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_map s.
  • Инициализирует область памяти x значением контейнера, равным содержимому s.
• void vset_copy_init(vtype_set* x, const vtype_set* s)
  • Принимает указатель на область памяти, содержащую инициализируемый контейнер x.
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_set s.
  • Инициализирует область памяти x значением контейнера, равным содержимому s.
• void dict_copy_init(vtype_dict* x, const vtype_dict* s)
  • Принимает указатель на область памяти, содержащую инициализируемый контейнер x.
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict s.
  • Инициализирует область памяти x значением контейнера, равным содержимому s.

6. Высвобождение ресурсов контейнера

• void string_free(vtype_string* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_string.
  • Высвобождает все используемые строкой ресурсы.
• void array_free(vtype_array* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_array.
  • Высвобождает все используемые контейнером ресурсы.
• void list_free(vtype_list* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_list.
  • Высвобождает все используемые контейнером ресурсы.
• void map_free(vtype_map* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_map.
  • Высвобождает все используемые контейнером ресурсы.
• void vset_free(vtype_set* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_set.
  • Высвобождает все используемые контейнером ресурсы.
• void dict_free(vtype_dict* x)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict.
  • Высвобождает все используемые контейнером ресурсы.

7. Подсчет хэша контейнера

• vtype_hash string_hash(const vtype_string* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_string.
  • Возвращает подсчтианное целочисленное значение хэша строки, подверженное коллизиям.
• vtype_hash array_hash(const vtype_array* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_array.
  • Возвращает подсчтианное целочисленное значение хэша контейнера, подверженное коллизиям.
• vtype_hash list_hash(const vtype_list* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_list.
  • Возвращает подсчтианное целочисленное значение хэша контейнера, подверженное коллизиям.
• vtype_hash map_hash(const vtype_map* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_map.
  • Возвращает подсчтианное целочисленное значение хэша контейнера, подверженное коллизиям.
• vtype_hash vset_hash(const vtype_set* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_set.
  • Возвращает подсчтианное целочисленное значение хэша контейнера, подверженное коллизиям.
• vtype_hash dict_hash(const vtype_dict* s)
  • Принимает указатель на область памяти, содержащую инициализированное значение vtype_dict.
  • Возвращает подсчтианное целочисленное значение хэша контейнера, подверженное коллизиям.

Далее: 2.1. vtype_array