util.h(3)

📦
version 2.2.0 · 2 versions
, in fedora 44

💖 util.h(3) — Library Functions Manual ✨

okay bestie, sit down, hydrate, because this is the header that runs the whole backstage 🫶. It's util.h, straight out of the Library Functions Manual, and it's literally just helper functions and macros — the little toolbox everyone else in the library keeps borrowing from. Not glamorous, but without it? Nothing works. It's giving main character energy in the background. 💅

🌸 NAME 🌸

util.h — helper functions and macros 💖

🦋 SYNOPSIS 🦋

#include 'bee2/defs.h'

🎀 Macros 🎀

  • #define COUNT_OF(a) — the number of elements in the array a.
  • #define LAST_OF(a) — the number of elements in the array a.
  • #define CASSERT(e) — compile with a condition check
  • #define VERIFY(e) — the condition is checked
  • #define EXPECT(a) — the condition is expected to hold
  • #define SWAP(a, b) — swap the values of the variables a and b.
  • #define SWAP_PTR(a, b) — swap the pointer values a and b.
  • #define CLEAN(a) — clean a variable
  • #define CLEAN2(a, b) — clean two variables
  • #define CLEAN3(a, b, c) — clean three variables

🌈 Functions 🌈

  • void utilAssert (int e, const char *file, int line) — the condition is assumed to hold
  • const char * utilVersion () — version
  • bool_t utilOnExit (void(*fn)()) — destructor registration
  • size_t utilMin (size_t n,...) — minimum
  • size_t utilMax (size_t n,...) — maximum
  • size_t utilAlign (size_t size, size_t alignment) — the nearest multiple above
  • u32 utilCRC32 (const void *buf, size_t count, u32 state) — CRC32 checksum.
  • u32 utilFNV32 (const void *buf, size_t count, u32 state) — FNV32 checksum.
  • u32 utilNonce32 () — 32-bit nonce

💅 MACROS 💅

#define CASSERT(e)

Macro definition:

((void)sizeof(char[1 - 2 * !(e)]))

For the debug build, evaluate e and finish the compilation if e == 0. Like, the compiler itself gets a vibe check. 🧚

#define CLEAN3(a, b, c)

Macro definition:

CLEAN2(a, b), CLEAN(c)

Precondition

  • The target variables can be assigned zero.

Note

The CLEANx macros are here to clean critical variables once a function wraps up. After cleaning, the variable gets cast to void, which potentially suppresses static analyzer warnings about unused parts of code (see for example https://clang.llvm.org/docs/analyzer/user-docs/FAQ.html#dead-store).

#define EXPECT(a)

Expect a to hold, and do absolutely nothing about it.

Note

The EXPECT macro points at conditions that are expected but can still totally be violated. Examples of such conditions: a number being prime, a polynomial being irreducible, an elliptic curve being correct.

Expected conditions can be hard to check. That's why programs cannot rely on these conditions holding unconditionally and must stay robust even when they're violated. For example, a program that adds points of an elliptic curve over a prime field GF(p) must finish the addition even if p is composite.

Keep a super clear line between ASSERT (usually the programmer's own self-check) and EXPECT (usually control over input data).

Some expected conditions can be partially checked. For example, EXPECT(p is an odd prime) can be backed up by checking ASSERT(p is odd). Unconditional checks that support expected conditions should be documented wherever possible.

#define LAST_OF(a)

Macro definition:

((a)[COUNT_OF(a) - 1])

Precondition

  • The array is non-empty.

#define SWAP(a, b)

Macro definition:

(a) ^= (b), (b) ^= (a), (a) ^= (b)

Precondition

  • The variables have the same type.
  • The variables are integer types that allow the ^ operation.
  • The variables a and b are distinct.

Note

If a and b are actually the same variable, then it gets zeroed out. 😭 Safe code:

a != b ? SWAP(a, b) : 0;

#define SWAP_PTR(a, b)

Macro definition:

*((octet**)&(a)) = (octet*)(a) - ((octet*)(b) - (octet*)0),\
*((octet**)&(b)) = (octet*)(b) + ((octet*)(a) - (octet*)0),\
*((octet**)&(a)) = (octet*)(b) - ((octet*)(a) - (octet*)0)

Precondition

  • The variables a and b are distinct.

#define VERIFY(e)

Macro definition:

{if (!(e)) ASSERT(0);}

Evaluate e (always) and terminate execution if a == 0 (when debugging).

🌟 FUNCTIONS 🌟

size_t utilAlign (size_t size, size_t alignment)

It finds the closest number above size that is a multiple of alignment.

Returns

The number you were looking for.

Note

The function is used when aligning fragments of memory to the boundaries of blocks of alignment octets.

Arguments

  • size — size
  • alignment — the multiple

void utilAssert (int e, const char *file, int line) [extern]

For the debug build, evaluate e and terminate execution if e == 0.

Note

It uses its own edition of the assert() macro. The standard edition has a condition check. When the program works correctly, the condition is never satisfied, and test-coverage analyzers may show only partial coverage.

u32 utilCRC32 (const void *buf, size_t count, u32 state)

It computes the checksum of the buffer [count]buf. The state state is used when computing the checksum. The checksum is computed with the CRC32 algorithm from the ISO 3309 standard.

Note

The checksum of a big chunk of data can be computed sequentially through repeated calls to the function. On the first call, the state state must be zero.

Returns

The checksum.

Arguments

  • buf — buffer
  • count — number of octets
  • state — state

u32 utilFNV32 (const void *buf, size_t count, u32 state)

It computes the checksum of the buffer [count]buf. The state state is used when computing the checksum. The checksum is computed with the FNV-1a algorithm with 32-bit width (http://isthe.com/chongo/tech/comp/fnv/).

Note

The checksum of a big chunk of data can be computed sequentially through repeated calls to the function. On the first call, state must equal 2166136261 = 0x811C9DC5.

Returns

The checksum.

Arguments

  • buf — buffer
  • count — number of octets
  • state — state

size_t utilMax (size_t n, ...)

It finds the maximum of n numbers of type size_t passed as additional parameters.

Precondition

  • n > 0.

Returns

The maximum.

Arguments

  • n — the number of numbers
  • ... — the numbers

size_t utilMin (size_t n, ...)

It finds the minimum of n numbers of type size_t passed as additional parameters.

Precondition

  • n > 0.

Returns

The minimum.

Arguments

  • n — the number of numbers
  • ... — the numbers

u32 utilNonce32 ()

A 32-bit nonce is built out of unique system data (date, time).

Returns

The nonce.

Note

A nonce (a calque of the English word nonce) is a "weakly" repeating value that gets used in cryptographic protocols. With nonces you can initialize pseudo-random number generators (see prngCOMBOStart()).

bool_t utilOnExit (void(*fn)())

It registers the function fn, which will be called when the program finishes working / the dynamic library is unloaded.

Returns

A success flag.

Note

Registered functions are called in LIFO order (last-in-first-out).

The very same function can be registered several times.

Arguments

  • fn — function

const char * utilVersion ()

It determines the version of the bee2 library.

Returns

The version as a major.minor.patch string.

👑 АВТОР 👑

окей bestie, эту секцию можно было бы и проскроллить, но мы тут ничего не скипаем, у нас всё по-честному 💅

Так вот, слушай: эта страничка автоматически создана Doxygen для Библиотека Bee2 — и собрана она прямо из исходного текста. Никакой ручной работы, никакого «сяду и напишу доки в пятницу вечером», чисто машинка взяла исходники и нагенерила красоту сама. it's giving «документация, которая живёт своей жизнью» 🦋

и да, человека-автора у этой странички буквально нет 🙈 так что если что-то тут смущает — смущаться некому, это всё генератор, periodt.

и на этом всё, bestie 🎀 эта страничка — util.h(3), родом она из Библиотека Bee2, а дата в футере — Вс 25 Янв 2026 00:00:00. иконично, не правда ли ✨ муа, целую 💋

📦 where this page comes from