burkey.co /docs/libflint/math
index math
~/docs/libflint/math.md
libflint

Math

libflint·Utilities

Integer helpers, checked int32_t arithmetic, a 2D LfPoint, Bresenham line generation, and square-grid queries.

Usage#

lf_point builds a point by value. bresenham_p allocates the line from start through end, including both ends. The caller frees that array.

LfPoint start = lf_point(0, 0);
LfPoint end = lf_point(3, 2);
size_t count = 0;
LfPoint *line = bresenham_p(start, end, &count);
if (line != NULL) {
    for (size_t i = 0; i < count; i++) {
        printf("%d,%d\n", line[i].x, line[i].y);
    }
    free(line);
}

A NULL sz returns NULL and is not written. Any other failure sets *sz to 0. Identical endpoints produce one point.

Structs#

LfPoint#

x and y are the coordinates. Callers may read and write them.

typedef struct {
    int x;
    int y;
} LfPoint;

Functions#

lf_point / LfPoint_eq / LfPoint_eq_p / LfPoint_match#

lf_point returns a point by value.

LfPoint_eq returns 1 when both coordinates match, and 0 otherwise. It is not a qsort comparator. There is no less-than result.

LfPoint_eq_p returns 1 when both pointers are NULL, or when both are non-NULL and the points are equal. One NULL returns 0.

LfPoint_match returns 0 when LfPoint_eq_p would return 1, and 1 otherwise. That is the List and Set match convention: 0 means equal. The same NULL cases apply.

LfPoint lf_point(int x, int y);
int LfPoint_eq(LfPoint a, LfPoint b);
int LfPoint_eq_p(const LfPoint *a, const LfPoint *b);
int LfPoint_match(const void *a, const void *b);

abs_int#

Returns the absolute value. INT_MIN has no positive int value, so the result is INT_MAX.

int abs_int(int a);

max_int / min_int#

max_int returns the greater argument. min_int returns the lesser. Equal arguments return that value.

int max_int(int a, int b);
int min_int(int a, int b);

clamp_int#

Returns i limited to the closed range. If low > high, the bounds are swapped first.

int clamp_int(int i, int low, int high);

binstr_to_int#

Parses a binary integer. '_' may appear anywhere and is not a digit. At least one '0' or '1' is required, so an empty string or a string of only underscores returns -1. Any other character returns -1. NULL returns -1.

The value is accumulated without signed overflow. A result that does not fit in int returns -1. A successful result is in 0 .. INT_MAX. -1 is only the error code.

int binstr_to_int(const char *s);

lf_gcd#

Euclidean magnitude. Each argument is taken as an absolute value in unsigned arithmetic, so negatives are accepted and INT_MIN does not overflow. The result is that magnitude when it fits in int. lf_gcd(0, 0) returns 0. lf_gcd(0, n) returns the magnitude of n when that magnitude fits. |INT_MIN| does not fit, so lf_gcd(INT_MIN, 0) and lf_gcd(INT_MIN, INT_MIN) return -1. lf_gcd(INT_MIN, 2) returns 2.

int lf_gcd(int a, int b);

lf_lcm#

Returns a nonnegative least common multiple, or -1 when the result does not fit in int. If either argument is 0, the result is 0, including lf_lcm(0, INT_MIN). If either nonzero argument is INT_MIN, the result is -1. Other negatives use the same magnitude as lf_gcd. Signs are not preserved.

int lf_lcm(int a, int b);

lf_i32_add / lf_i32_sub / lf_i32_mul#

Checked int32_t addition, subtraction, and multiplication. Nothing is allocated. The caller supplies out.

Returns 0 and writes *out on success. Returns -1 if out is NULL or the mathematical result does not fit in int32_t. On failure *out is unchanged. INT32_MIN * -1 and INT32_MIN - 1 do not fit.

int lf_i32_add(int32_t a, int32_t b, int32_t *out);
int lf_i32_sub(int32_t a, int32_t b, int32_t *out);
int lf_i32_mul(int32_t a, int32_t b, int32_t *out);

lf_lerp#

Linear blend from a at t == 0 to b at t == 1. Those two inputs return the endpoint with no further arithmetic, so the result is exact. t is not clamped. Other values extrapolate.

If a and b are both strictly positive or both strictly negative, the result is a + t * (b - a). Otherwise, including when either is zero or the signs differ, the result is (1 - t) * a + t * b.

float lf_lerp(float a, float b, float t);

lf_isqrt#

Returns the greatest integer whose square is at most n. Returns -1 if n < 0. 0 and 1 return themselves. The value for INT_MAX fits in int. When int is 32 bits, lf_isqrt(INT_MAX) is 46340.

int lf_isqrt(int n);

lf_grid_in_bounds#

Returns 1 when 0 <= x < width and 0 <= y < height, and 0 otherwise. width <= 0 or height <= 0 returns 0. The origin is (0, 0). A negative coordinate is outside. Nothing is allocated.

int lf_grid_in_bounds(int x, int y, int width, int height);

lf_manhattan#

Writes |x1 - x0| + |y1 - y0| to *out. Returns 0 on success. Returns -1 if out is NULL, if either absolute difference does not fit in int, or if the sum does not fit. On failure *out is unchanged. Differences are computed without signed overflow.

INT_MIN and INT_MAX do not fit as a difference. |INT_MIN - 0| does not fit either. Two differences that each fit can still overflow the sum, as with (0, 0) and (INT_MAX, INT_MAX).

int lf_manhattan(int x0, int y0, int x1, int y1, int *out);

lf_chebyshev#

Writes the greater of |x1 - x0| and |y1 - y0| to *out. Returns 0 on success. Returns -1 if out is NULL or either absolute difference does not fit in int. On failure *out is unchanged. A pair whose sum would overflow lf_manhattan still succeeds here when each difference fits.

int lf_chebyshev(int x0, int y0, int x1, int y1, int *out);

bresenham / bresenham_p#

Allocates the raster line from the first endpoint through the second, including both. On success *sz is max(|x1 - x0|, |y1 - y0|) + 1. Identical endpoints produce one point. The caller frees the array with free.

Returns NULL if sz is NULL, and does not write through it. Returns NULL, after setting *sz to 0, if that point count does not fit in size_t or the array cannot be allocated. Endpoint subtraction uses a wider type, so the coordinates may be any int. bresenham_p unpacks two points and calls bresenham.

LfPoint *bresenham(int x0, int y0, int x1, int y1, size_t *sz);
LfPoint *bresenham_p(LfPoint p1, LfPoint p2, size_t *sz);

lf_neighbors4#

Writes each in-bounds orthogonal neighbor of (x, y) into caller storage. Nothing is allocated. Returns 0 and sets *n to the number written. Entries at index *n and after are not written. Returns -1 if dest is NULL, n is NULL, or cap is too small for every in-bounds neighbor. On failure dest and *n are unchanged. A too-small cap writes nothing. A NULL dest returns -1 even when no neighbor is in bounds. cap 0 succeeds only when no neighbor is in bounds and both dest and n are non-NULL.

(x, y) need not lie in the grid. Only neighbors that pass lf_grid_in_bounds are written. A non-positive width or height writes nothing and returns 0 when dest and n are non-NULL. +x is east and +y is north. Order is east (x+1, y), north (x, y+1), west (x-1, y), south (x, y-1). At (1, 1) in a 3 by 3 grid those four are (2, 1), (1, 2), (0, 1), (1, 0). A step to INT_MAX + 1 or INT_MIN - 1 is omitted. The grid does not wrap.

int lf_neighbors4(int x, int y, int width, int height,
                  LfPoint *dest, size_t cap, size_t *n);

lf_neighbors8#

Same contract as lf_neighbors4, including unchanged dest and *n on failure. Order is those four orthogonal neighbors, then northeast (x+1, y+1), northwest (x-1, y+1), southwest (x-1, y-1), southeast (x+1, y-1). Out-of-bounds steps are skipped and the rest keep this order. At (1, 1) in a 3 by 3 grid, lf_neighbors8 writes the four orthogonal points above, then (2, 2), (0, 2), (0, 0), (2, 0).

int lf_neighbors8(int x, int y, int width, int height,
                  LfPoint *dest, size_t cap, size_t *n);