share/man/man3/Q_SIGNED.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_SIGNED 3
  30 .Os
  31 .Sh NAME
  32 .Nm Q_SIGNED ,
  33 .Nm Q_LTZ ,
  34 .Nm Q_PRECEQ ,
  35 .Nm Q_QLTQ ,
  36 .Nm Q_QLEQ ,
  37 .Nm Q_QGTQ ,
  38 .Nm Q_QGEQ ,
  39 .Nm Q_QEQ ,
  40 .Nm Q_QNEQ ,
  41 .Nm Q_OFLOW ,
  42 .Nm Q_RELPREC
  43 .Nd fixed-point math comparison and logic functions
  44 .Sh SYNOPSIS
  45 .In sys/qmath.h
  46 .Ft bool
  47 .Fn Q_SIGNED "NTYPE n"
  48 .Ft bool
  49 .Fn Q_LTZ "NTYPE n"
  50 .Ft bool
  51 .Fn Q_PRECEQ "QTYPE a" "QTYPE b"
  52 .Ft bool
  53 .Fn Q_QLTQ "QTYPE a" "QTYPE b"
  54 .Ft bool
  55 .Fn Q_QLEQ "QTYPE a" "QTYPE b"
  56 .Ft bool
  57 .Fn Q_QGTQ "QTYPE a" "QTYPE b"
  58 .Ft bool
  59 .Fn Q_QGEQ "QTYPE a" "QTYPE b"
  60 .Ft bool
  61 .Fn Q_QEQ "QTYPE a" "QTYPE b"
  62 .Ft bool
  63 .Fn Q_QNEQ "QTYPE a" "QTYPE b"
  64 .Ft bool
  65 .Fn Q_OFLOW "QTYPE q" "ITYPE iv"
  66 .Ft int
  67 .Fn Q_RELPREC "QTYPE a" "QTYPE b"
  68 .Sh DESCRIPTION
  69 .Fn Q_SIGNED
  70 returns
  71 .Ft true
  72 if the numeric data type passed in as
  73 .Fa n
  74 is signed, or
  75 .Ft false
  76 otherwise.
  77 .Pp
  78 .Fn Q_LTZ
  79 returns
  80 .Ft true
  81 if the numeric value
  82 passed in as
  83 .Fa n
  84 is negative
  85 .Pq requires types which use the MSB as the sign bit ,
  86 or
  87 .Ft false
  88 otherwise.
  89 .Pp
  90 .Fn Q_PRECEQ
  91 returns
  92 .Ft true
  93 if the number of
  94 .Fa a
  95 and
  96 .Fa b
  97 fractional bits is the same,
  98 .Ft false
  99 otherwise.
 100 .Pp
 101 The
 102 .Fn Q_QLTQ ,
 103 .Fn Q_QLEQ ,
 104 .Fn Q_QGTQ ,
 105 .Fn Q_QGEQ ,
 106 .Fn Q_QEQ
 107 and
 108 .Fn Q_QNEQ
 109 functions compare two Q numbers, returning
 110 .Ft true
 111 if
 112 .Fa a
 113 is less than, less than or equal to, greater than, greater than or equal to,
 114 equal to, or not equal to
 115 .Fa b
 116 respectively, or
 117 .Ft false
 118 otherwise.
 119 The integral and fractional values are used to perform the comparison, without
 120 explicit concern for the underlying number of integer versus fractional bits.
 121 .Pp
 122 .Fn Q_OFLOW
 123 returns
 124 .Ft true
 125 if integer value
 126 .Fa iv
 127 cannot be stored in
 128 .Fa q
 129 without truncation, or false otherwise.
 130 .Pp
 131 .Fn Q_RELPREC
 132 returns the relative precision of
 133 .Fa a
 134 versus
 135 .Fa b .
 136 In terms of
 137 .Em Qm.n
 138 notation, this function returns the difference between the
 139 .Em n
 140 values of
 141 .Fa a
 142 and
 143 .Fa b .
 144 For example, a return value of +4 means that
 145 .Fa a
 146 has an additional 4 bits of fractional precision compared to
 147 .Fa b .
 148 .Pp
 149 All of those functions operate on
 150 the following data types:
 151 .Vt s8q_t ,
 152 .Vt u8q_t ,
 153 .Vt s16q_t ,
 154 .Vt u16q_t ,
 155 .Vt s32q_t ,
 156 .Vt u32q_t ,
 157 .Vt s64q_t ,
 158 and
 159 .Vt u64q_t ,
 160 which are referred to generically as
 161 .Fa QTYPE .
 162 The
 163 .Fa ITYPE
 164 refers to the
 165 .Xr stdint 7
 166 integer types.
 167 .Fa NTYPE
 168 is used to refer to any numeric type and is therefore a superset of
 169 .Fa QTYPE
 170 and
 171 .Fa ITYPE .
 172 .Pp
 173 For more details, see
 174 .Xr qmath 3 .
 175 .Sh RETURN VALUES
 176 The
 177 .Fn Q_SIGNED ,
 178 .Fn Q_LTZ ,
 179 .Fn Q_PRECEQ ,
 180 .Fn Q_QLTQ ,
 181 .Fn Q_QLEQ ,
 182 .Fn Q_QGTQ ,
 183 .Fn Q_QGEQ ,
 184 .Fn Q_QEQ ,
 185 .Fn Q_QNEQ
 186 and
 187 .Fn Q_OFLOW
 188 functions return expressions that evaluate to boolean
 189 .Vt true
 190 or
 191 .Vt false .
 192 .Pp
 193 .Fn Q_RELPREC
 194 returns the relative precision difference as a signed integer.
 195 .Sh SEE ALSO
 196 .Xr errno 2 ,
 197 .Xr qmath 3 ,
 198 .Xr stdint 7
 199 .Sh HISTORY
 200 The
 201 .Xr qmath 3
 202 functions first appeared in
 203 .Fx 13.0 .
 204 .Sh AUTHORS
 205 .An -nosplit
 206 The
 207 .Xr qmath 3
 208 functions and this manual page were written by
 209 .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org
 210 and sponsored by Netflix, Inc.