util.h - Man Page
Вспомогательные функции и макросы
Synopsis
#include 'bee2/defs.h'
Макросы
#define COUNT_OF(a)
Число элементов в массиве a.
#define LAST_OF(a)
Число элементов в массиве a.
#define CASSERT(e)
Компиляция с проверкой условия
#define VERIFY(e)
Проверяется выполнение условия
#define EXPECT(a)
Ожидается выполнение условия
#define SWAP(a, b)
Поменять местами значения переменных a и b.
#define SWAP_PTR(a, b)
Поменять местами значения указателей a и b.
#define CLEAN(a)
Очистить переменную
#define CLEAN2(a, b)
Очистить две переменные
#define CLEAN3(a, b, c)
Очистить три переменные
Функции
void utilAssert (int e, const char *file, int line)
Предполагается выполнение условия
const char * utilVersion ()
Версия
bool_t utilOnExit (void(*fn)())
Регистрация деструктора
size_t utilMin (size_t n,...)
Минимум
size_t utilMax (size_t n,...)
Максимум
size_t utilAlign (size_t size, size_t alignment)
Ближайшее сверху кратное
u32 utilCRC32 (const void *buf, size_t count, u32 state)
Контрольная сумма CRC32.
u32 utilFNV32 (const void *buf, size_t count, u32 state)
Контрольная сумма FNV32.
u32 utilNonce32 ()
32-разрядный нонс
Макросы
#define CASSERT( e)
Макроопределение:
((void)sizeof(char[1 - 2 * !(e)]))
Для отладочной версии вычислить e и завершить компиляцию, если e == 0.
#define CLEAN3( a, b, c)
Макроопределение:
CLEAN2(a, b), CLEAN(c)
Предусловие
Целевые переменные допускают присваивание нуля.
Прим.
Макросы CLEANx предназначены для очистки критических переменных по завершении функций. После очистки переменная приводится к типу void, что потенциально подавляет предупреждения статических анализаторов о неиспользуемых участках кода (см. напр. https://clang.llvm.org/docs/analyzer/user-docs/FAQ.html#dead-store).
#define EXPECT( a)
Ожидать выполнения a, ничего не предпринимая.
Прим.
Макрос EXPECT указывает на условия, которые ожидаются, но все таки могут быть нарушены. Примеры условий: простота числа, неприводимость многочлена, корректность эллиптической кривой.
Ожидаемые условия могут быть труднопроверяемыми. Поэтому программы не могут полагаться на безусловное выполнение этих условий и должны устойчиво работать даже при их нарушении. Например, программа сложения точек эллиптической кривой над простым полем GF(p) должна завершать сложение даже если p -- составное.
Следует четко разграничивать ASSERT (как правило, самоконтроль программиста) и EXPECT (как правило, контроль входных данных).
Некоторые ожидаемые условия могут частично проверяться. Например, EXPECT(p -- нечетное простое) может быть поддержано проверкой ASSERT(p -- нечетное). Безусловные проверки, поддерживающие ожидаемые условия, должны по возможности документироваться.
#define LAST_OF( a)
Макроопределение:
((a)[COUNT_OF(a) - 1])
Предусловие
Массив непустой.
#define SWAP( a, b)
Макроопределение:
(a) ^= (b), (b) ^= (a), (a) ^= (b)
Предусловие
Переменные имеют один тип.
Переменные являются целочисленными, допускающими операцию ^.
Переменные a и b различны.
Прим.
Если a и b --- это одна и та же переменная, то она будет обнулена. Безопасный код:
a != b ? SWAP(a, b) : 0;
#define SWAP_PTR( a, b)
Макроопределение:
*((octet**)&(a)) = (octet*)(a) - ((octet*)(b) - (octet*)0),\
*((octet**)&(b)) = (octet*)(b) + ((octet*)(a) - (octet*)0),\
*((octet**)&(a)) = (octet*)(b) - ((octet*)(a) - (octet*)0)Предусловие
Переменные a и b различны.
#define VERIFY( e)
Макроопределение:
{if (!(e)) ASSERT(0);}Вычислить e (всегда) и завершить выполнение, если a == 0 (при отладке).
Функции
size_t utilAlign (size_t size, size_t alignment)
Определяется ближайшее к size сверху число, кратное alignment.
Возвращает
Искомое число.
Прим.
Функция используется при выравнивании фрагментов памяти на границы блоков из alignment октетов.
- Аргументы
size размер
alignment кратность
void utilAssert (int e, const char * file, int line) [extern]
Для отладочной версии вычислить e и завершить выполнение, если e == 0.
Прим.
Используется собственная редакция макроса assert(). В стандартной редакции есть проверка условия. При правильной работе программы условие никогда не выполняется, и анализаторы покрытия тестами могут показывать только частичное покрытие.
u32 utilCRC32 (const void * buf, size_t count, u32 state)
Определяется контрольная сумма буфера [count]buf. При расчете контрольной суммы используется состояние state. Контрольная сумма рассчитывается по алгоритму CRC32 из стандарта ISO 3309.
Прим.
Контрольную сумму большого фрагмента данных можно определять последовательно путем многократных обращений к функции. При первом обращении состояние state должно быть нулевым.
Возвращает
Контрольная сумма.
- Аргументы
buf буфер
count число октетов
state состояние
u32 utilFNV32 (const void * buf, size_t count, u32 state)
Определяется контрольная сумма буфера [count]buf. При расчете контрольной суммы используется состояние state. Контрольная сумма рассчитывается по алгоритму FNV-1a с размерностью 32 (http://isthe.com/chongo/tech/comp/fnv/).
Прим.
Контрольную сумму большого фрагмента данных можно определять последовательно путем многократных обращений к функции. При первом обращении state должно равняться 2166136261 = 0x811C9DC5.
Возвращает
Контрольная сумма.
- Аргументы
buf буфер
count число октетов
state состояние
size_t utilMax (size_t n, ...)
Определяется максимум из n чисел типа size_t, переданных как дополнительные параметры.
- Предусловие
n > 0.
Возвращает
Максимум.
- Аргументы
n количество чисел
... числа
size_t utilMin (size_t n, ...)
Определяется минимум из n чисел типа size_t, переданных как дополнительные параметры.
- Предусловие
n > 0.
Возвращает
Минимум.
- Аргументы
n количество чисел
... числа
u32 utilNonce32 ()
По уникальным системным данным (дата, время) строится 32-разрядный нонс.
Возвращает
Нонс.
Прим.
Нонс (калька с англ. nonce) --- "слабо" повторяющееся значение, которое используется в криптографических протоколах. С помощью нонсов можно инициализовать генераторы псевдослучайных чисел (см. prngCOMBOStart()).
bool_t utilOnExit (void(* fn )())
Регистрируется функция fn, которая будет вызвана при завершении работы программы / выгрузке динамической библиотеки.
Возвращает
Признак успеха.
Прим.
Зарегистрированные функции вызываются в порядке LIFO (last-in-first-out).
Одна и та же функция может быть зарегистрирована несколько раз.
- Аргументы
fn функция
const char * utilVersion ()
Определяется версия библиотеки bee2.
Возвращает
Версия в виде строки major.minor.patch.
Автор
Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.