Q_INI(3)

💖 NAME 💖

okay bestie, this is the Q_INI(3) page from the Library Functions Manual, and it’s giving fixed-point math miscellaneous functions/variables. The whole squad is: Q_INI, Q_NCBITS, Q_BT, Q_TC, Q_NTBITS, Q_NFCBITS, Q_MAXNFBITS, Q_NFBITS, Q_NIBITS, Q_RPSHFT, Q_ABS, Q_MAXSTRLEN, Q_TOSTR, Q_SHL, Q_SHR, Q_DEBUG.

---

✨ SYNOPSIS ✨

Here’s the cast in code form, no edits, periodt:

#include <sys/qmath.h>

QTYPE
Q_INI(QTYPE *q, ITYPE iv, ITYPE dfv, int rpshft);

Q_NCBITS

__typeof(q)
Q_BT(QTYPE q);

ITYPE
Q_TC(QTYPE q, ITYPE v);

uint32_t
Q_NTBITS(QTYPE q);

uint32_t
Q_NFCBITS(QTYPE q);

uint32_t
Q_MAXNFBITS(QTYPE q);

uint32_t
Q_NFBITS(QTYPE q);

uint32_t
Q_NIBITS(QTYPE q);

uint32_t
Q_RPSHFT(QTYPE q);

NTYPE
Q_ABS(NTYPE n);

uint32_t
Q_MAXSTRLEN(QTYPE q, int base);

char *
Q_TOSTR(QTYPE q, int prec, int base, char *s, int slen);

ITYPE
Q_SHL(QTYPE q, ITYPE iv);

ITYPE
Q_SHR(QTYPE q, ITYPE iv);

char *, ...
Q_DEBUG(QTYPE q, char *prefmt, char *postfmt, incfmt);

ITYPE
Q_DFV2BFV(ITYPE dfv, int nfbits);

---

💅 DESCRIPTION 💅

• Q_INI() — initialises a Q number with the integral value iv and decimal fractional value dfv, and sets appropriate control bits based on the requested radix shift point rpshft. Tiny but crucial detail: dfv must be passed as a preprocessor literal to preserve leading zeroes. no cap, it matters.
• Q_NCBITS — this defined constant is the number of reserved control bits, and currently it’s 3. slay.
• Q_NTBITS(), Q_NFCBITS(), Q_MAXNFBITS(), Q_NFBITS(), and Q_NIBITS() — return the q-specific count of total, control-encoded fractional, maximum fractional, effective fractional, and integer bits applicable to q, respectively. yes, that whole lineup, each with its own job.
• Q_BT() — returns the C data type of q.
• Q_TC() — returns v type casted to the C data type of q.
• Q_RPSHFT() — returns the bit position of q’s binary radix point relative to bit zero.
• Q_ABS() — returns the absolute value of any standard numeric type passed in as n — one of those types that uses the MSB as a sign bit, but not Q numbers. This function is signed/unsigned type safe.
• Q_SHL() and Q_SHR() — return the integral value v (the iv argument) left or right shifted by the appropriate amount for q.
• Q_MAXSTRLEN() — calculates the maximum number of characters that may be required to render the C-string representation of q with numeric base base.
• Q_TOSTR() — renders the C-string representation of q with numeric base base and fractional precision prec into s, which has an available capacity of slen characters. base must be in range [2,16]. Specifying prec as -1 renders the number’s fractional component with maximum precision. If slen is greater than zero but insufficient to hold the complete C-string, the '\0' C-string terminator will be written to *s, thereby returning a zero length C-string.
• Q_DEBUG() — returns a format string and associated data suitable for printf-like rendering of debugging information pertaining to q. If either prefmt and/or postfmt are specified, they are prepended and appended to the resulting format string respectively. The incfmt boolean specifies whether to include (true) or exclude (false) the raw format string itself in the debugging output.
• Q_DFV2BFV() — converts decimal fractional value dfv to its binary-encoded representation with nfbits of binary precision. Again, dfv must be passed as a preprocessor literal to preserve leading zeroes. The returned value can be used to set a Q number’s fractional bits, for example using Q_SFVAL().

All of those functions operate on the following data types: s8q_t, u8q_t, s16q_t, u16q_t, s32q_t, u32q_t, s64q_t, and u64q_t, which are referred to generically as QTYPE. The ITYPE refers to the stdint(7) integer types. NTYPE is used to refer to any numeric type and is therefore a superset of QTYPE and ITYPE.

For more details, see qmath(3). 🫶

---

🎀 RETURN VALUES 🎀

• Q_INI() — returns the initialised Q number, which can be used to chain initialise additional Q numbers. cute, efficient, iconic.
• Q_TOSTR() — returns a pointer to the '\0' C-string terminator appended to s after the rendered numeric data, or NULL on buffer overflow.
• Q_DFV2BFV() — returns the binary-encoded representation of decimal fractional value dfv with nfbits of binary precision.

---

🦋 SEE ALSO 🦋

errno(2), qmath(3), stdint(7) — go peek, bestie.

---

⭐ HISTORY ⭐

The qmath(3) functions first appeared in FreeBSD 13.0. a moment of silence for the lore.

---

👑 AUTHORS 👑

The qmath(3) functions and this manual page were written by Lawrence Stewart <lstewart@FreeBSD.org> and sponsored by Netflix, Inc.

---

and that’s the whole vibe — footer says Debian, July 8, 2018, Q_INI(3). you’re so welcome, bestie 💅✨