ww.h(3)

📦
version 2.2.0 · 2 versions
, in fedora 44

🎀 NAME 🎀

ww.h — Слова конечной длины (words of finite length). It's the header from the bee2 library, manual section 3, and it's literally the whole vibe for working with binary words of arbitrary finite length. Bestie, this is your one-stop shop 💅

✨ SYNOPSIS ✨

#include 'bee2/defs.h'
#include 'bee2/core/mem.h'
#include 'bee2/core/safe.h'
#include 'bee2/core/u32.h'

🌸 Макросы 🌸

#define wwIsValid(a,  n)
#define wwIsDisjoint(a,  b,  n)
#define wwIsSameOrDisjoint(a,  b,  n)
#define wwIsDisjoint2(a,  n,  b,  m)
#define wwIsDisjoint3(a,  n,  b,  m,  c,  k)

🦋 Функции 🦋

  • void wwCopy (word b[], const word a[], size_t n) — Копирование слов (copy the words, duh)
  • void wwSwap (word a[], word b[], size_t n) — Перестановка слов (swap 'em)
  • bool_t wwEq (const word a[], const word b[], size_t n) — Проверка совпадения слов (are they the same? 👀)
  • int wwCmp (const word a[], const word b[], size_t n) — Сравнение слов (compare)
  • int wwCmp2 (const word a[], size_t n, const word b[], size_t m) — Сравнение слов разной длины (compare words of different length)
  • int wwCmpW (const word a[], size_t n, register word w) — Сравнение слова c машинным словом (compare a word against a machine word)
  • void wwXor (word c[], const word a[], const word b[], size_t n) — Cложение слов по модулю 2. (XOR, the moment)
  • void wwXor2 (word b[], const word a[], size_t n) — Добавление слова по модулю 2. (in-place XOR)
  • void wwSetZero (word a[], size_t n) — Обнуление слова (zero it out)
  • void wwSetW (word a[], size_t n, register word w) — Присвоение слову значения -- машинного слова (set the word to a machine word)
  • void wwRepW (word a[], size_t n, register word w) — Заполнение слова машинным словом (fill with a machine word)
  • bool_t wwIsZero (const word a[], size_t n) — Нулевое слово? (is it zero?)
  • bool_t wwIsW (const word a[], size_t n, register word w) — Принимает значение -- машинное слово? (does it equal a machine word?)
  • bool_t wwIsRepW (const word a[], size_t n, register word w) — Повтор машинного слова? (is it a repeat of a machine word?)
  • size_t wwWordSize (const word a[], size_t n) — Размер значащей части слова в машинных словах (size of the significant part, in machine words)
  • size_t wwOctetSize (const word a[], size_t n) — Размер значащей части слова в октетах (size of the significant part, in octets)
  • bool_t wwTestBit (const word a[], size_t pos) — Проверить разряд слова (peek at a bit)
  • word wwGetBits (const word a[], size_t pos, size_t width) — Получить разряды слова (grab some bits)
  • void wwSetBit (word a[], size_t pos, register bool_t val) — Установить разряд слова (set a bit)
  • void wwSetBits (word a[], size_t pos, size_t width, register word val) — Установить разряды слова (set a whole run of bits)
  • void wwFlipBit (word a[], size_t pos) — Инвертировать разряд слова (flip a bit)
  • size_t wwLoZeroBits (const word a[], size_t n) — Количество первых (младших) нулевых битов (how many low zero bits)
  • size_t wwHiZeroBits (const word a[], size_t n) — Количество последних (старших) нулевых битов (how many high zero bits)
  • size_t wwBitSize (const word a[], size_t n) — Размер значащей части слова в битах (significant size, in bits)
  • size_t wwNAF (word naf[], const word a[], size_t n, size_t w) — Расчет NAF. (compute the NAF)
  • void wwShLo (word a[], size_t n, size_t shift) — Сдвиг в сторону первых (младших) разрядов (shift toward the low bits)
  • word wwShLoCarry (word a[], size_t n, size_t shift, word carry) — Сдвиг в сторону первых (младших) разрядов с заемом (shift low, with carry)
  • void wwShHi (word a[], size_t n, size_t shift) — Сдвиг в сторону последних (старших) разрядов (shift toward the high bits)
  • word wwShHiCarry (word a[], size_t n, size_t shift, word carry) — Сдвиг в сторону последних (старших) разрядов с заемом (shift high, with carry)
  • void wwTrimLo (word a[], size_t n, size_t pos) — Отбросить первые (младшие) разряды слова (chop off the low bits)
  • void wwTrimHi (word a[], size_t n, size_t pos) — Отбросить последние (старшие) разряды слова (chop off the high bits)

💜 Подробное описание 💜

OK so here's the whole deal, bestie. This header implements operations on binary words of arbitrary finite length, i.e. elements of {0,1}*. Periodt. 💅

A binary word is given by an array of machine words: word w[n].

The bits of w[0] are numbered from 0 (the low one) up to B_PER_W - 1 (the high one), the bits of w[1] go from B_PER_W (low) up to 2 * B_PER_W - 1 (high), and so on forever, you get the pattern ✨

The notation [n]w means that the word w is made of n machine words. Iconic shorthand, honestly.

🫶 Предусловие (Precondition)

All input pointers must be valid.

In the word functions, the number of machine words reserved at the memory addresses for the words is either clear from context or spelled out in the function descriptions. So like, read the description, don't guess 🙈

🌈 Макросы 🌈

💖 #define wwIsDisjoint( a, b, n)

Макроопределение:

memIsDisjoint(a, b, O_OF_W(n))

Буферы слов [n]a и [n]b не пересекаются? (Do the word buffers [n]a and [n]b not overlap? Vibe check on overlap 🚫)

💖 #define wwIsDisjoint2( a, n, b, m)

Макроопределение:

memIsDisjoint2(a, O_OF_W(n), b, O_OF_W(m))

Буферы слов [n]a и [m]b не пересекаются? (Do the buffers [n]a and [m]b not overlap?)

💖 #define wwIsDisjoint3( a, n, b, m, c, k)

Макроопределение:

memIsDisjoint3(a, O_OF_W(n), b, O_OF_W(m), c, O_OF_W(k))

Буферы слов [n]a, [m]b и [k]c не пересекаются? (Do all three buffers stay out of each other's business? the way that these three just don't overlap 😌)

💖 #define wwIsSameOrDisjoint( a, b, n)

Макроопределение:

memIsSameOrDisjoint(a, b, O_OF_W(n))

Буферы слов [n]a и [n]b совпадают или не пересекаются? (Are [n]a and [n]b either identical or non-overlapping? no in-between nonsense allowed 💀)

💖 #define wwIsValid( a, n)

Макроопределение:

(memIsValid((a), O_OF_W(n)) && memIsAligned((a), O_PER_W))

Корректное слово [n]a? (Is [n]a a valid word? valid and aligned, both boxes checked ✅)

🌟 Функции 🌟

👑 size_t wwBitSize (const word a[], size_t n)

Определяется размер значащей части слова [n]a. Размер полагается равным индексу последнего ненулевого разряда, увеличенному на единицу. So like, the significant size = index of the last nonzero bit, plus one. That's it, that's the whole function 🎀

Прим. (Notes, bestie 📝)

  • Размер пустого (n == 0) или нулевого слов равняется 0. (Empty or zero words → size is 0.)
  • Если wwBitSize(a, n) == m > 0, то для a как числа выполняется 2^{m - 1} < a <= 2^m - 1.

Возвращает

Размер значащей части. (The significant size.)

Регулярность

Функция нерегулярна. (This one is NOT regular, no cap.)

Аргументы

  • a — слово
  • n — длина a в машинных словах

👑 int FAST wwCmp (const word a[], const word b[], size_t n)

Cлова [n]a и [n]b сравниваются обратно-лексикографически. (Compared reverse-lexicographically, high word first, main character energy.)

Прим.

a > b, если a[n - 1] == b[n - 1],..., a[i] == b[i], a[i] > b[i].

Возвращает

1, если a > b, или -1, если a < b, или 0, если a == b.

Регулярность

Имеется ускоренная нерегулярная редакция. (There's a fast irregular edition 💨)

Аргументы

  • a — первое слово
  • b — второе слово
  • n — длина a и b в машинных словах

Перекрестные ссылки wwCmp().

Используется в wwCmp().

👑 int FAST wwCmp2 (const word a[], size_t n, const word b[], size_t m)

Cлова [n]a и [m]b сравниваются обратно-лексикографически (см. wwCmp()) после дополнения нулями до слов одинаковой длины. (Same reverse-lexicographic comparison, but first both get zero-padded to the same length. Besties of different sizes, still comparable 🫶)

Возвращает

1, если a > b, или -1, если a < b, или 0, если a == b.

Регулярность

Имеется ускоренная нерегулярная редакция.

Аргументы

  • a — первое слово
  • n — длина a в машинных словах
  • b — второе слово
  • m — длина b в машинных словах

Перекрестные ссылки wwCmp2().

Используется в wwCmp2().

👑 int FAST wwCmpW (const word a[], size_t n, register word w)

Слово [n]a сравнивается с машинным словом w. (A whole word vs. a single machine word — underdog matchup, honestly.)

Возвращает

1, если a > w, или -1, если a < w, или 0, если a == w.

Регулярность

Имеется ускоренная нерегулярная редакция.

Аргументы

  • a — сравниваемое слово
  • n — длина a в машинных словах
  • w — машинное слово

Перекрестные ссылки wwCmpW().

Используется в wwCmpW().

👑 void wwCopy (word b[], const word a[], size_t n)

Cлово [n]a переписывается в [n]b:

b <- a.

Предусловие

Буфер b либо не пересекается, либо совпадает с буфером a. (Buffer b either doesn't overlap a, or is exactly the same as a. No partial-overlap chaos allowed 🙅‍♀️)

Аргументы

  • b — приемник
  • a — источник
  • n — длина a в машинных словах

👑 bool_t FAST wwEq (const word a[], const word b[], size_t n)

Проверяется совпадение слов [n]a и [n]b. (Checking whether the two words match up 💞)

Возвращает

Признак сопадения. (The match flag.)

Регулярность

Имеется ускоренная нерегулярная редакция.

Аргументы

  • a — первое слово
  • b — второе слово
  • n — длина a и b в машинных словах

Перекрестные ссылки wwEq().

Используется в wwEq().

👑 void wwFlipBit (word a[], size_t pos)

В слове a инвертируется разряд с номером pos. (Flip the bit at index pos in word a — yes, just that one bit, slay ✨)

Предусловие

По адресу a зарезервировано W_OF_B(pos + 1) машинных слов.

Аргументы

  • a — слово
  • pos — номер разряда

👑 word wwGetBits (const word a[], size_t pos, size_t width)

В слове a определяется разряды с номерами pos,..., pos + width - 1. (Pulls out the bits numbered pos through pos + width - 1.)

Предусловие

По адресу a зарезервировано W_OF_B(pos + width) машинных слов.

width <= B_PER_W.

Возвращает

Машинное слово, составленное из разрядов a с номерами pos (младший), pos + 1,..., pos + width -1 (старший). (A machine word built from those bits, pos as the low one and pos + width - 1 as the high one.)

Аргументы

  • a — слово
  • pos — номер первого разряда
  • width — число разрядов

size_t wwHiZeroBits (const word a[], size_t n)

okay so bestie, this one is literally just measuring the run of zero bits chilling at the end of the word [n]a. that's the whole job description. 💅

Returns

The length of that run. the count. the number. that's it. ✨

Regularity

The function is irregular. no fast variant here, babe, it is what it is.

Arguments

  • a — the word
  • n — the length of a, counted in machine words

bool_t FAST wwIsRepW (const word a[], size_t n, register word w)

this one does a vibe check on every machine word in [n]a to see if they're all literally just w, over and over, no cap:

a[0] == w && a[1] == w && ... && a[n - 1] == w?

Note

In an empty word (n == 0), the value that repeats is 0. like… nothing repeating nothing equals 0, it's giving philosophy fr fr 😭

Returns

TRUE if a is made out of w, and FALSE if it isn't.

Regularity

There is a fast irregular version available. slay.

Arguments

  • a — the word being checked
  • n — the length of a, in machine words
  • w — the value

Cross-references

wwIsRepW().

Used in

wwIsRepW().

and yes, it cross-references itself and it's used in itself. self-referential main character energy only 👑

bool_t FAST wwIsW (const word a[], size_t n, register word w)

checks that the word [n]a takes the value w, and w is a machine word:

a[0] == w && a[1] == ... == a[n - 1] == 0?

Note

An empty word (n == 0) takes the value 0. 🌸

Returns

TRUE if a = w, and FALSE otherwise.

Regularity

A fast irregular version exists. ⚡

Arguments

  • a — the word being checked
  • n — the length of a, in machine words
  • w — the value

Cross-references

wwIsW().

Used in

wwIsW().

bool_t FAST wwIsZero (const word a[], size_t n)

is the word [n]a zero? yes or no. that's the entire plot. 💖

Returns

TRUE if a is zero, and FALSE otherwise.

Regularity

A fast irregular version exists. ✨

Arguments

  • a — the word being checked
  • n — the length of a, in machine words

Cross-references

wwIsZero().

Used in

wwIsZero().

size_t wwLoZeroBits (const word a[], size_t n)

counts the run of zero bits hanging out at the start of the word [n]a. twin sister of wwHiZeroBits, different end though. 🦋

Returns

The length of that run.

Regularity

The function is irregular.

Arguments

  • a — the word
  • n — the length of a, in machine words

size_t wwNAF (word naf[], const word a[], size_t n, size_t w)

okay bestie sit DOWN for this one, it's the big one. 🍓

into [2n + 1]naf it drops the encoded representation of the optimal non-adjacent form (NAF) of the word [n]a. it computes the windowed NAF with window size w.

Note

NAF(a, w) is a sequence of symbols (a_0, a_1,..., a_{l-1}) such that

  • a_i ∈ {0, ± 1, ± 3, ..., ± 2^{w-1} - 1};
  • if a != 0, then a_{l-1} != 0;
  • a as a number equals \sum {i=0}^{l-1} a_i 2^i;
  • among any w consecutive symbols a_i, only one is nonzero.

it's known that l — the length of the NAF — doesn't exceed wwBitSize(a) + 1. 📏

the symbol encoding goes like this (<b> is the binary notation of the number b):

  • zero a_i are represented by a single binary symbol 0;
  • positive a_i are represented by w binary symbols 0<a_i>;
  • negative a_i are represented by w binary symbols 1<|a_i|>;
  • the encoded representation is the concatenation of the code of a_{l-1} (the first symbols), ..., the code of a_1, the code of a_0 (the last symbols).

encoding w consecutive elements a_i needs no more than (w - 1) * 1 + 1 * w = 2 * w - 1 bits. so when w < B_PER_W, storing the whole coded representation needs no more than 2 * n + 1 words. math ate that. 💅

if, while computing the NAF, you end up with a suffix α, 0,..., 0, 1 that has w - 1 zeros and α < 0, then that suffix gets swapped out for β, 0,..., 0, 1, which has w - 2 zeros and β = 2^{w - 1} + α > 0. both suffixes describe the same numbers: 2^w + α = 2^{w - 1} + β. the length of the second suffix, and of the corresponding NAF, is one less. glow-up via shortening ✨

Precondition

2 <= w < B_PER_W.

the buffer naf does not overlap the buffer a.

Returns

The size of naf (the number of symbols l).

Regularity

The function is irregular.

Arguments

  • naf — the sign form
  • a — the word
  • n — the length of a, in machine words
  • w — the window length

size_t wwOctetSize (const word a[], size_t n)

figures out the size of the significant part of the word [n]a. the size is taken to be the index of the last nonzero octet, plus one. 🎀

Note

The size of an empty (n == 0) or zero word equals 0.

Regularity

The function is irregular.

Arguments

  • a — the word
  • n — the length of a, in machine words

void wwRepW (word a[], size_t n, register word w)

every single machine word in [n]a gets assigned the value w:

a[0] <- w, a[1] <- w, ..., a[n - 1] <- w.

one value, all the slots. copy-paste but make it bitwise 🫶

Precondition

n > 0 or w == 0.

Arguments

  • a — the word
  • n — the length of a, in machine words
  • w — the value

void wwSetBit (word a[], size_t pos, register bool_t val)

in the word a, the bit numbered pos gets assigned the value val. one bit. that's the task. 🌈

Precondition

At the address a, W_OF_B(pos + 1) machine words are reserved.

val == FALSE || val == TRUE.

Arguments

  • a — the word being worked on
  • pos — the bit number
  • val — the value to set

void wwSetBits (word a[], size_t pos, size_t width, register word val)

in the word a, the bits numbered pos,..., pos + width - 1 get set equal to consecutive bits of val (from least significant to most significant). a whole little squad of bits, matching val beat for beat 💜

Precondition

At the address a, W_OF_B(pos + width) machine words are reserved.

width <= B_PER_W.

Arguments

  • a — the word
  • pos — the number of the first bit
  • width — the number of bits
  • val — the value of the bits

void wwSetW (word a[], size_t n, register word w)

the word [n]a gets assigned the value w, which is a machine word:

a[0] <- w, a[1] <- 0, ..., a[n - 1] <- 0.

first slot eats, the rest get zeroed. iconic distribution honestly 👑

Precondition

n > 0 or w == 0.

Arguments

  • a — the word
  • n — the length of a, in machine words
  • w — the value

void wwSetZero (word a[], size_t n)

the word [n]a gets zeroed out:

a <- 0.

reset era. 🧚

Arguments

  • a — the word
  • n — the length of a, in machine words

void wwShHi (word a[], size_t n, size_t shift)

the word [n]a gets shifted by shift positions toward the last bits. the bits left empty get filled with zeros.

Note

when the words are interpreted as numbers, the shift means multiplying by 2^shift, with the result reduced mod 2^{n * B_PER_W}. ⭐

Arguments

  • a — the word being shifted
  • n — the length of a, in machine words
  • shift — the shift amount

word wwShHiCarry (word a[], size_t n, size_t shift, word carry)

the word [n]a gets shifted by shift positions toward the last bits. the bits left empty get filled with the bits of carry.

Returns

A machine word made up of the displaced last bits.

Arguments

  • a — the word being shifted
  • n — the length of a, in machine words
  • shift — the shift amount
  • carry — the machine word of borrow

void wwShLo (word a[], size_t n, size_t shift)

the word [n]a gets shifted by shift positions toward the first bits. the bits left empty get filled with zeros.

Note

when the words are interpreted as numbers, the shift means dividing by 2^shift, with the result reduced mod 2^{n * B_PER_W}. 🦋

Arguments

  • a — the word being shifted
  • n — the length of a, in machine words
  • shift — the shift amount

word wwShLoCarry (word a[], size_t n, size_t shift, word carry)

the word [n]a gets shifted by shift positions toward the first bits. the bits left empty get filled with the bits of carry.

Returns

A machine word made up of the displaced last bits.

Arguments

  • a — the word being shifted
  • n — the length of a, in machine words
  • shift — the shift amount
  • carry — the machine word of borrow

void wwSwap (word a[], word b[], size_t n)

okay so bestie, this one is literally just a glow-up swap: the words [n]a and [n]b trade places 💅

a <-> b.
Precondition: buffer b does not overlap with buffer a. no overlapping, periodt.

Arguments:

  • a — the first word
  • b — the second word
  • n — length of a and b in machine words

bool_t wwTestBit (const word a[], size_t pos)

This one checks out a single bit in word a — the bit with number pos gets inspected 🔍 vibe check on that bit.

Precondition: at address a, W_OF_B(pos + 1) machine words are reserved.

Returns:

  • TRUE if the bit is non-zero
  • FALSE otherwise

Arguments:

  • a — the word
  • pos — bit number

void wwTrimHi (word a[], size_t n, size_t pos)

In word [n]a, it zeroes out the bits with numbers pos, pos + 1, ..., n * B_PER_W - 1. bye bye high bits ✂️

Note:

  • If pos >= n * B_PER_W, absolutely nothing happens. no actions, no drama.
  • When words are interpreted as numbers, dropping bits means reduction mod 2^pos.

Arguments:

  • a — the word being processed
  • n — length of a in machine words
  • pos — number of the first bit to zero out

void wwTrimLo (word a[], size_t n, size_t pos)

In word [n]a, it zeroes out bits with numbers 0, 1, ..., min(pos, n * B_PER_W) - 1. low bits? gone 💨

Arguments:

  • a — the word being processed
  • n — length of a in machine words
  • pos — boundary of the bits to zero out

size_t wwWordSize (const word a[], size_t n)

It figures out the size of the significant part of word [n]a. The size is set to the index of the last non-zero machine word, plus one. main character index energy 👑

Note:

  • The size of an empty word (n == 0) or a zero word is 0.

Regularity:

  • This function is irregular.

Arguments:

  • a — the word
  • n — length of a in machine words

void wwXor (word c[], const word a[], const word b[], size_t n)

It computes the bitwise modulo 2 sum [n]c of words [n]a and [n]b:

c <- a ^ b.
Precondition: buffer c either does not overlap with, or exactly coincides with, each of buffers a and b.

Arguments:

  • c — the sum
  • a — the first term
  • b — the second term
  • n — length of a and b in machine words

void wwXor2 (word b[], const word a[], size_t n)

To word [n]b, it adds word [n]a. The addition is done bitwise modulo 2:

b <- a ^ b.
Precondition: buffer b either does not overlap with, or exactly coincides with, buffer a.

Arguments:

  • b — the second term / sum
  • a — the first term
  • n — length of a in machine words

✨ Автор (Author) ✨

Automatically created by Doxygen for the Bee2 Library from the source text.

And that's the whole page, bestie! This gem comes from the Bee2 Library, dated Вс 25 Янв 2026 00:00:00, and it's the manual for ww.h(3). Stay slaying those words 💖🦋✨

📦 where this page comes from