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.\" $FreeBSD$ 27.\" 28.Dd July 8, 2018 29.Dt Q_INI 3 30.Os 31.Sh NAME 32.Nm Q_INI , 33.Nm Q_NCBITS , 34.Nm Q_BT , 35.Nm Q_TC , 36.Nm Q_NTBITS , 37.Nm Q_NFCBITS , 38.Nm Q_MAXNFBITS , 39.Nm Q_NFBITS , 40.Nm Q_NIBITS , 41.Nm Q_RPSHFT , 42.Nm Q_ABS , 43.Nm Q_MAXSTRLEN , 44.Nm Q_TOSTR , 45.Nm Q_SHL , 46.Nm Q_SHR , 47.Nm Q_DEBUG 48.Nd fixed-point math miscellaneous functions/variables 49.Sh SYNOPSIS 50.In sys/qmath.h 51.Ft QTYPE 52.Fn Q_INI "QTYPE *q" "ITYPE iv" "ITYPE dfv" "int rpshft" 53.Fd Q_NCBITS 54.Ft __typeof(q) 55.Fn Q_BT "QTYPE q" 56.Ft ITYPE 57.Fn Q_TC "QTYPE q" "ITYPE v" 58.Ft uint32_t 59.Fn Q_NTBITS "QTYPE q" 60.Ft uint32_t 61.Fn Q_NFCBITS "QTYPE q" 62.Ft uint32_t 63.Fn Q_MAXNFBITS "QTYPE q" 64.Ft uint32_t 65.Fn Q_NFBITS "QTYPE q" 66.Ft uint32_t 67.Fn Q_NIBITS "QTYPE q" 68.Ft uint32_t 69.Fn Q_RPSHFT "QTYPE q" 70.Ft NTYPE 71.Fn Q_ABS "NTYPE n" 72.Ft uint32_t 73.Fn Q_MAXSTRLEN "QTYPE q" "int base" 74.Ft char * 75.Fn Q_TOSTR "QTYPE q" "int prec" "int base" "char *s" "int slen" 76.Ft ITYPE 77.Fn Q_SHL "QTYPE q" "ITYPE iv" 78.Ft ITYPE 79.Fn Q_SHR "QTYPE q" "ITYPE iv" 80.Ft char *, ... 81.Fn Q_DEBUG "QTYPE q" "char *prefmt" "char *postfmt" "incfmt" 82.Ft ITYPE 83.Fn Q_DFV2BFV "ITYPE dfv" "int nfbits" 84.Sh DESCRIPTION 85.Fn Q_INI 86initialises a Q number with the supplied integral value 87.Fa iv 88and decimal fractional value 89.Fa dfv , 90with appropriate control bits based on the requested radix shift point 91.Fa rpshft . 92.Fa dfv 93must be passed as a preprocessor literal to preserve leading zeroes. 94.Pp 95The 96.Dv Q_NCBITS 97defined constant specifies the number of reserved control bits, currently 3. 98.Pp 99.Fn Q_NTBITS , 100.Fn Q_NFCBITS , 101.Fn Q_MAXNFBITS , 102.Fn Q_NFBITS 103and 104.Fn Q_NIBITS 105return the 106.Fa q Ns -specific 107count of total, control-encoded fractional, maximum fractional, effective 108fractional, and integer bits applicable to 109.Fa q 110respectively. 111.Pp 112.Fn Q_BT 113returns the C data type of 114.Fa q , 115while 116.Fn Q_TC 117returns 118.Fa v 119type casted to the C data type of 120.Fa q . 121.Pp 122.Fn Q_RPSHFT 123returns the bit position of 124.Fa q Ap s 125binary radix point relative to bit zero. 126.Pp 127.Fn Q_ABS 128returns the absolute value of any standard numeric type 129.Pq that uses the MSB as a sign bit, but not Q numbers 130passed in as 131.Fa n . 132The function is signed/unsigned type safe. 133.Pp 134.Fn Q_SHL 135and 136.Fn Q_SHR 137return the integral value 138.Fa v 139left or right shifted by the appropriate amount for 140.Fa q . 141.Pp 142.Fn Q_MAXSTRLEN 143calculates the maximum number of characters that may be required to render the 144C-string representation of 145.Fa q 146with numeric base 147.Fa base . 148.Pp 149.Fn Q_TOSTR 150renders the C-string representation of 151.Fa q 152with numeric base 153.Fa base 154and fractional precision 155.Fa prec 156into 157.Fa s 158which has an available capacity of 159.Fa slen 160characters. 161.Fa base 162must be in range 163.Bq 2,16 . 164Specifying 165.Fa prec 166as -1 renders the number's fractional component with maximum precision. 167If 168.Fa slen 169is greater than zero but insufficient to hold the complete C-string, the '\\0' 170C-string terminator will be written to 171.Fa *s , 172thereby returning a zero length C-string. 173.Pp 174.Fn Q_DEBUG 175returns a format string and associated data suitable for printf-like rendering 176of debugging information pertaining to 177.Fa q . 178If either 179.Fa prefmt 180and/or 181.Fa postfmt 182are specified, they are prepended and appended to the resulting format string 183respectively. 184The 185.Fa incfmt 186boolean specifies whether to include 187.Pq Vt true 188or exclude 189.Pq Vt false 190the raw format string itself in the debugging output. 191.Pp 192.Fn Q_DFV2BFV 193converts decimal fractional value 194.Fa dfv 195to its binary-encoded representation with 196.Fa nfbits 197of binary precision. 198.Fa dfv 199must be passed as a preprocessor literal to preserve leading zeroes. 200The returned value can be used to set a Q number's fractional bits, for example 201using 202.Fn Q_SFVAL . 203.Pp 204All of those functions operate on 205the following data types: 206.Vt s8q_t , 207.Vt u8q_t , 208.Vt s16q_t , 209.Vt u16q_t , 210.Vt s32q_t , 211.Vt u32q_t , 212.Vt s64q_t , 213and 214.Vt u64q_t , 215which are referred to generically as 216.Fa QTYPE . 217The 218.Fa ITYPE 219refers to the 220.Xr stdint 7 221integer types. 222.Fa NTYPE 223is used to refer to any numeric type and is therefore a superset of 224.Fa QTYPE 225and 226.Fa ITYPE . 227.Pp 228For more details, see 229.Xr qmath 3 . 230.Sh RETURN VALUES 231.Fn Q_INI 232returns the initialised Q number which can be used to chain initialise 233additional Q numbers. 234.Pp 235.Fn Q_TOSTR 236returns a pointer to the '\\0' C-string terminator appended to 237.Fa s 238after the rendered numeric data, or NULL on buffer overflow. 239.Pp 240.Fn Q_DFV2BFV 241returns the binary-encoded representation of decimal fractional value 242.Fa dfv 243with 244.Fa nfbits 245of binary precision. 246.Sh SEE ALSO 247.Xr errno 2 , 248.Xr qmath 3 , 249.Xr stdint 7 250.Sh HISTORY 251The 252.Xr qmath 3 253functions first appeared in 254.Fx 13.0 . 255.Sh AUTHORS 256.An -nosplit 257The 258.Xr qmath 3 259functions and this manual page were written by 260.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org 261and sponsored by Netflix, Inc. 262