1.\" 2.\" Copyright (c) 2018 Netflix, Inc. 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions, and the following disclaimer, 10.\" without modification, immediately at the beginning of the file. 11.\" 2. The name of the author may not be used to endorse or promote products 12.\" derived from this software without specific prior written permission. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR 18.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd July 8, 2018 27.Dt Q_INI 3 28.Os 29.Sh NAME 30.Nm Q_INI , 31.Nm Q_NCBITS , 32.Nm Q_BT , 33.Nm Q_TC , 34.Nm Q_NTBITS , 35.Nm Q_NFCBITS , 36.Nm Q_MAXNFBITS , 37.Nm Q_NFBITS , 38.Nm Q_NIBITS , 39.Nm Q_RPSHFT , 40.Nm Q_ABS , 41.Nm Q_MAXSTRLEN , 42.Nm Q_TOSTR , 43.Nm Q_SHL , 44.Nm Q_SHR , 45.Nm Q_DEBUG 46.Nd fixed-point math miscellaneous functions/variables 47.Sh SYNOPSIS 48.In sys/qmath.h 49.Ft QTYPE 50.Fn Q_INI "QTYPE *q" "ITYPE iv" "ITYPE dfv" "int rpshft" 51.Fd Q_NCBITS 52.Ft __typeof(q) 53.Fn Q_BT "QTYPE q" 54.Ft ITYPE 55.Fn Q_TC "QTYPE q" "ITYPE v" 56.Ft uint32_t 57.Fn Q_NTBITS "QTYPE q" 58.Ft uint32_t 59.Fn Q_NFCBITS "QTYPE q" 60.Ft uint32_t 61.Fn Q_MAXNFBITS "QTYPE q" 62.Ft uint32_t 63.Fn Q_NFBITS "QTYPE q" 64.Ft uint32_t 65.Fn Q_NIBITS "QTYPE q" 66.Ft uint32_t 67.Fn Q_RPSHFT "QTYPE q" 68.Ft NTYPE 69.Fn Q_ABS "NTYPE n" 70.Ft uint32_t 71.Fn Q_MAXSTRLEN "QTYPE q" "int base" 72.Ft char * 73.Fn Q_TOSTR "QTYPE q" "int prec" "int base" "char *s" "int slen" 74.Ft ITYPE 75.Fn Q_SHL "QTYPE q" "ITYPE iv" 76.Ft ITYPE 77.Fn Q_SHR "QTYPE q" "ITYPE iv" 78.Ft char *, ... 79.Fn Q_DEBUG "QTYPE q" "char *prefmt" "char *postfmt" "incfmt" 80.Ft ITYPE 81.Fn Q_DFV2BFV "ITYPE dfv" "int nfbits" 82.Sh DESCRIPTION 83.Fn Q_INI 84initialises a Q number with the supplied integral value 85.Fa iv 86and decimal fractional value 87.Fa dfv , 88with appropriate control bits based on the requested radix shift point 89.Fa rpshft . 90.Fa dfv 91must be passed as a preprocessor literal to preserve leading zeroes. 92.Pp 93The 94.Dv Q_NCBITS 95defined constant specifies the number of reserved control bits, currently 3. 96.Pp 97.Fn Q_NTBITS , 98.Fn Q_NFCBITS , 99.Fn Q_MAXNFBITS , 100.Fn Q_NFBITS 101and 102.Fn Q_NIBITS 103return the 104.Fa q Ns -specific 105count of total, control-encoded fractional, maximum fractional, effective 106fractional, and integer bits applicable to 107.Fa q 108respectively. 109.Pp 110.Fn Q_BT 111returns the C data type of 112.Fa q , 113while 114.Fn Q_TC 115returns 116.Fa v 117type casted to the C data type of 118.Fa q . 119.Pp 120.Fn Q_RPSHFT 121returns the bit position of 122.Fa q Ap s 123binary radix point relative to bit zero. 124.Pp 125.Fn Q_ABS 126returns the absolute value of any standard numeric type 127.Pq that uses the MSB as a sign bit, but not Q numbers 128passed in as 129.Fa n . 130The function is signed/unsigned type safe. 131.Pp 132.Fn Q_SHL 133and 134.Fn Q_SHR 135return the integral value 136.Fa v 137left or right shifted by the appropriate amount for 138.Fa q . 139.Pp 140.Fn Q_MAXSTRLEN 141calculates the maximum number of characters that may be required to render the 142C-string representation of 143.Fa q 144with numeric base 145.Fa base . 146.Pp 147.Fn Q_TOSTR 148renders the C-string representation of 149.Fa q 150with numeric base 151.Fa base 152and fractional precision 153.Fa prec 154into 155.Fa s 156which has an available capacity of 157.Fa slen 158characters. 159.Fa base 160must be in range 161.Bq 2,16 . 162Specifying 163.Fa prec 164as -1 renders the number's fractional component with maximum precision. 165If 166.Fa slen 167is greater than zero but insufficient to hold the complete C-string, the '\\0' 168C-string terminator will be written to 169.Fa *s , 170thereby returning a zero length C-string. 171.Pp 172.Fn Q_DEBUG 173returns a format string and associated data suitable for printf-like rendering 174of debugging information pertaining to 175.Fa q . 176If either 177.Fa prefmt 178and/or 179.Fa postfmt 180are specified, they are prepended and appended to the resulting format string 181respectively. 182The 183.Fa incfmt 184boolean specifies whether to include 185.Pq Vt true 186or exclude 187.Pq Vt false 188the raw format string itself in the debugging output. 189.Pp 190.Fn Q_DFV2BFV 191converts decimal fractional value 192.Fa dfv 193to its binary-encoded representation with 194.Fa nfbits 195of binary precision. 196.Fa dfv 197must be passed as a preprocessor literal to preserve leading zeroes. 198The returned value can be used to set a Q number's fractional bits, for example 199using 200.Fn Q_SFVAL . 201.Pp 202All of those functions operate on 203the following data types: 204.Vt s8q_t , 205.Vt u8q_t , 206.Vt s16q_t , 207.Vt u16q_t , 208.Vt s32q_t , 209.Vt u32q_t , 210.Vt s64q_t , 211and 212.Vt u64q_t , 213which are referred to generically as 214.Fa QTYPE . 215The 216.Fa ITYPE 217refers to the 218.Xr stdint 7 219integer types. 220.Fa NTYPE 221is used to refer to any numeric type and is therefore a superset of 222.Fa QTYPE 223and 224.Fa ITYPE . 225.Pp 226For more details, see 227.Xr qmath 3 . 228.Sh RETURN VALUES 229.Fn Q_INI 230returns the initialised Q number which can be used to chain initialise 231additional Q numbers. 232.Pp 233.Fn Q_TOSTR 234returns a pointer to the '\\0' C-string terminator appended to 235.Fa s 236after the rendered numeric data, or NULL on buffer overflow. 237.Pp 238.Fn Q_DFV2BFV 239returns the binary-encoded representation of decimal fractional value 240.Fa dfv 241with 242.Fa nfbits 243of binary precision. 244.Sh SEE ALSO 245.Xr errno 2 , 246.Xr qmath 3 , 247.Xr stdint 7 248.Sh HISTORY 249The 250.Xr qmath 3 251functions first appeared in 252.Fx 13.0 . 253.Sh AUTHORS 254.An -nosplit 255The 256.Xr qmath 3 257functions and this manual page were written by 258.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org 259and sponsored by Netflix, Inc. 260