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 70returns 71.Ft true 72if the numeric data type passed in as 73.Fa n 74is signed, or 75.Ft false 76otherwise. 77.Pp 78.Fn Q_LTZ 79returns 80.Ft true 81if the numeric value 82passed in as 83.Fa n 84is negative 85.Pq requires types which use the MSB as the sign bit , 86or 87.Ft false 88otherwise. 89.Pp 90.Fn Q_PRECEQ 91returns 92.Ft true 93if the number of 94.Fa a 95and 96.Fa b 97fractional bits is the same, 98.Ft false 99otherwise. 100.Pp 101The 102.Fn Q_QLTQ , 103.Fn Q_QLEQ , 104.Fn Q_QGTQ , 105.Fn Q_QGEQ , 106.Fn Q_QEQ 107and 108.Fn Q_QNEQ 109functions compare two Q numbers, returning 110.Ft true 111if 112.Fa a 113is less than, less than or equal to, greater than, greater than or equal to, 114equal to, or not equal to 115.Fa b 116respectively, or 117.Ft false 118otherwise. 119The integral and fractional values are used to perform the comparison, without 120explicit concern for the underlying number of integer versus fractional bits. 121.Pp 122.Fn Q_OFLOW 123returns 124.Ft true 125if integer value 126.Fa iv 127cannot be stored in 128.Fa q 129without truncation, or false otherwise. 130.Pp 131.Fn Q_RELPREC 132returns the relative precision of 133.Fa a 134versus 135.Fa b . 136In terms of 137.Em Qm.n 138notation, this function returns the difference between the 139.Em n 140values of 141.Fa a 142and 143.Fa b . 144For example, a return value of +4 means that 145.Fa a 146has an additional 4 bits of fractional precision compared to 147.Fa b . 148.Pp 149All of those functions operate on 150the 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 , 158and 159.Vt u64q_t , 160which are referred to generically as 161.Fa QTYPE . 162The 163.Fa ITYPE 164refers to the 165.Xr stdint 7 166integer types. 167.Fa NTYPE 168is used to refer to any numeric type and is therefore a superset of 169.Fa QTYPE 170and 171.Fa ITYPE . 172.Pp 173For more details, see 174.Xr qmath 3 . 175.Sh RETURN VALUES 176The 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 186and 187.Fn Q_OFLOW 188functions return expressions that evaluate to boolean 189.Vt true 190or 191.Vt false . 192.Pp 193.Fn Q_RELPREC 194returns 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 200The 201.Xr qmath 3 202functions first appeared in 203.Fx 13.0 . 204.Sh AUTHORS 205.An -nosplit 206The 207.Xr qmath 3 208functions and this manual page were written by 209.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org 210and sponsored by Netflix, Inc. 211