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