share/man/man3/Q_INI.3

   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
  86 initialises a Q number with the supplied integral value
  87 .Fa iv
  88 and decimal fractional value
  89 .Fa dfv ,
  90 with appropriate control bits based on the requested radix shift point
  91 .Fa rpshft .
  92 .Fa dfv
  93 must be passed as a preprocessor literal to preserve leading zeroes.
  94 .Pp
  95 The
  96 .Dv Q_NCBITS
  97 defined 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
 103 and
 104 .Fn Q_NIBITS
 105 return the
 106 .Fa q Ns -specific
 107 count of total, control-encoded fractional, maximum fractional, effective
 108 fractional, and integer bits applicable to
 109 .Fa q
 110 respectively.
 111 .Pp
 112 .Fn Q_BT
 113 returns the C data type of
 114 .Fa q ,
 115 while
 116 .Fn Q_TC
 117 returns
 118 .Fa v
 119 type casted to the C data type of
 120 .Fa q .
 121 .Pp
 122 .Fn Q_RPSHFT
 123 returns the bit position of
 124 .Fa q Ap s
 125 binary radix point relative to bit zero.
 126 .Pp
 127 .Fn Q_ABS
 128 returns the absolute value of any standard numeric type
 129 .Pq that uses the MSB as a sign bit, but not Q numbers
 130 passed in as
 131 .Fa n .
 132 The function is signed/unsigned type safe.
 133 .Pp
 134 .Fn Q_SHL
 135 and
 136 .Fn Q_SHR
 137 return the integral value
 138 .Fa v
 139 left or right shifted by the appropriate amount for
 140 .Fa q .
 141 .Pp
 142 .Fn Q_MAXSTRLEN
 143 calculates the maximum number of characters that may be required to render the
 144 C-string representation of
 145 .Fa q
 146 with numeric base
 147 .Fa base .
 148 .Pp
 149 .Fn Q_TOSTR
 150 renders the C-string representation of
 151 .Fa q
 152 with numeric base
 153 .Fa base
 154 and fractional precision
 155 .Fa prec
 156 into
 157 .Fa s
 158 which has an available capacity of
 159 .Fa slen
 160 characters.
 161 .Fa base
 162 must be in range
 163 .Bq 2,16 .
 164 Specifying
 165 .Fa prec
 166 as -1 renders the number's fractional component with maximum precision.
 167 If
 168 .Fa slen
 169 is greater than zero but insufficient to hold the complete C-string, the '\\0'
 170 C-string terminator will be written to
 171 .Fa *s ,
 172 thereby returning a zero length C-string.
 173 .Pp
 174 .Fn Q_DEBUG
 175 returns a format string and associated data suitable for printf-like rendering
 176 of debugging information pertaining to
 177 .Fa q .
 178 If either
 179 .Fa prefmt
 180 and/or
 181 .Fa postfmt
 182 are specified, they are prepended and appended to the resulting format string
 183 respectively.
 184 The
 185 .Fa incfmt
 186 boolean specifies whether to include
 187 .Pq Vt true
 188 or exclude
 189 .Pq Vt false
 190 the raw format string itself in the debugging output.
 191 .Pp
 192 .Fn Q_DFV2BFV
 193 converts decimal fractional value
 194 .Fa dfv
 195 to its binary-encoded representation with
 196 .Fa nfbits
 197 of binary precision.
 198 .Fa dfv
 199 must be passed as a preprocessor literal to preserve leading zeroes.
 200 The returned value can be used to set a Q number's fractional bits, for example
 201 using
 202 .Fn Q_SFVAL .
 203 .Pp
 204 All of those functions operate on
 205 the 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 ,
 213 and
 214 .Vt u64q_t ,
 215 which are referred to generically as
 216 .Fa QTYPE .
 217 The
 218 .Fa ITYPE
 219 refers to the
 220 .Xr stdint 7
 221 integer types.
 222 .Fa NTYPE
 223 is used to refer to any numeric type and is therefore a superset of
 224 .Fa QTYPE
 225 and
 226 .Fa ITYPE .
 227 .Pp
 228 For more details, see
 229 .Xr qmath 3 .
 230 .Sh RETURN VALUES
 231 .Fn Q_INI
 232 returns the initialised Q number which can be used to chain initialise
 233 additional Q numbers.
 234 .Pp
 235 .Fn Q_TOSTR
 236 returns a pointer to the '\\0' C-string terminator appended to
 237 .Fa s
 238 after the rendered numeric data, or NULL on buffer overflow.
 239 .Pp
 240 .Fn Q_DFV2BFV
 241 returns the binary-encoded representation of decimal fractional value
 242 .Fa dfv
 243 with
 244 .Fa nfbits
 245 of binary precision.
 246 .Sh SEE ALSO
 247 .Xr errno 2 ,
 248 .Xr qmath 3 ,
 249 .Xr stdint 7
 250 .Sh HISTORY
 251 The
 252 .Xr qmath 3
 253 functions first appeared in
 254 .Fx 13.0 .
 255 .Sh AUTHORS
 256 .An -nosplit
 257 The
 258 .Xr qmath 3
 259 functions and this manual page were written by
 260 .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org
 261 and sponsored by Netflix, Inc.