share/man/man3/Q_QADDQ.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_QADDQ 3
  30 .Os
  31 .Sh NAME
  32 .Nm Q_QADDQ ,
  33 .Nm Q_QDIVQ ,
  34 .Nm Q_QMULQ ,
  35 .Nm Q_QSUBQ ,
  36 .Nm Q_NORMPREC ,
  37 .Nm Q_QMAXQ ,
  38 .Nm Q_QMINQ ,
  39 .Nm Q_QCLONEQ ,
  40 .Nm Q_CPYVALQ
  41 .Nd fixed-point math functions which operate on two Q numbers
  42 .Sh SYNOPSIS
  43 .In sys/qmath.h
  44 .Ft int
  45 .Fn Q_QADDQ "QTYPE *a" "QTYPE b"
  46 .Ft int
  47 .Fn Q_QDIVQ "QTYPE *a" "QTYPE b"
  48 .Ft int
  49 .Fn Q_QMULQ "QTYPE *a" "QTYPE b"
  50 .Ft int
  51 .Fn Q_QSUBQ "QTYPE *a" "QTYPE b"
  52 .Ft int
  53 .Fn Q_NORMPREC "QTYPE *a" "QTYPE *b"
  54 .Ft QTYPE
  55 .Fn Q_QMAXQ "QTYPE a" "QTYPE b"
  56 .Ft QTYPE
  57 .Fn Q_QMINQ "QTYPE a" "QTYPE b"
  58 .Ft int
  59 .Fn Q_QCLONEQ "QTYPE *l" "QTYPE r"
  60 .Ft int
  61 .Fn Q_QCPYVALQ "QTYPE *l" "QTYPE r"
  62 .Sh DESCRIPTION
  63 The
  64 .Fn Q_QADDQ ,
  65 .Fn Q_QDIVQ ,
  66 .Fn Q_QMULQ ,
  67 and
  68 .Fn Q_QSUBQ
  69 functions add, divide, multiply or subtract
  70 .Fa b
  71 to/by/from
  72 .Fa a
  73 respectively, storing the result in
  74 .Fa a .
  75 Both arguments must be initialized with the same fractional radix point.
  76 .Pp
  77 The
  78 .Fn Q_NORMPREC
  79 function attempts to normalise the precision of
  80 .Fa a
  81 and
  82 .Fa b
  83 if they differ.
  84 The greater of the two precisions is preferred if possible, unless that would
  85 truncate integer component data for the other operand, in which case the highest
  86 precision that preserves the integer component of both
  87 .Fa a
  88 and
  89 .Fa b
  90 is selected.
  91 .Pp
  92 The
  93 .Fn Q_QMAXQ
  94 and
  95 .Fn Q_QMINQ
  96 functions return the larger or smaller of
  97 .Fa a
  98 and
  99 .Fa b
 100 respectively.
 101 .Pp
 102 The
 103 .Fn Q_QCLONEQ
 104 and
 105 .Fn Q_QCPYVALQ
 106 functions attempt to store identical or representational copies of
 107 .Fa r ,
 108 in
 109 .Fa l
 110 respectively.
 111 An identical Q number produced by cloning copies the control bits as well as the
 112 verbatim integer/fractional bits.
 113 A representational copy only copies the values of
 114 .Fa r Ap s
 115 integer and fractional bits, representing them in the bits available per
 116 .Fa l Ap s
 117 Q format.
 118 .Pp
 119 All of those functions operate on the following data types:
 120 .Vt s8q_t ,
 121 .Vt u8q_t ,
 122 .Vt s16q_t ,
 123 .Vt u16q_t ,
 124 .Vt s32q_t ,
 125 .Vt u32q_t ,
 126 .Vt s64q_t ,
 127 and
 128 .Vt u64q_t ,
 129 which are referred to generically as
 130 .Fa QTYPE .
 131 .Pp
 132 For more details, see
 133 .Xr qmath 3 .
 134 .Sh RETURN VALUES
 135 The
 136 .Fn Q_QADDQ ,
 137 .Fn Q_QDIVQ ,
 138 .Fn Q_QMULQ ,
 139 .Fn Q_QSUBQ
 140 .Fn Q_NORMPREC ,
 141 .Fn Q_QCLONEQ
 142 and
 143 .Fn Q_QCPYVALQ
 144 functions return 0 on success, or an errno on failure.
 145 .Er EINVAL
 146 is returned for divide-by-zero.
 147 .Er EOVERFLOW
 148 and
 149 .Er ERANGE
 150 are returned for overflow and underflow respectively.
 151 .Er ERANGE is also returned when the precision of arguments
 152 does not match.
 153 .Pp
 154 The
 155 .Fn Q_QMAXQ
 156 and
 157 .Fn Q_QMINQ
 158 functions return the numerically larger or smaller of their two inputs
 159 respectively.
 160 .Sh SEE ALSO
 161 .Xr errno 2 ,
 162 .Xr qmath 3 ,
 163 .Xr stdint 7
 164 .Sh HISTORY
 165 The
 166 .Xr qmath 3
 167 functions first appeared in
 168 .Fx 13.0 .
 169 .Sh AUTHORS
 170 .An -nosplit
 171 The
 172 .Xr qmath 3
 173 functions and this manual page were written by
 174 .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org
 175 and sponsored by Netflix, Inc.