2 .\" Copyright (c) 2018 Netflix, Inc.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
48 .Nd fixed-point math miscellaneous functions/variables
52 .Fn Q_INI "QTYPE *q" "ITYPE iv" "ITYPE dfv" "int rpshft"
57 .Fn Q_TC "QTYPE q" "ITYPE v"
59 .Fn Q_NTBITS "QTYPE q"
61 .Fn Q_NFCBITS "QTYPE q"
63 .Fn Q_MAXNFBITS "QTYPE q"
65 .Fn Q_NFBITS "QTYPE q"
67 .Fn Q_NIBITS "QTYPE q"
69 .Fn Q_RPSHFT "QTYPE q"
73 .Fn Q_MAXSTRLEN "QTYPE q" "int base"
75 .Fn Q_TOSTR "QTYPE q" "int prec" "int base" "char *s" "int slen"
77 .Fn Q_SHL "QTYPE q" "ITYPE iv"
79 .Fn Q_SHR "QTYPE q" "ITYPE iv"
81 .Fn Q_DEBUG "QTYPE q" "char *prefmt" "char *postfmt" "incfmt"
83 .Fn Q_DFV2BFV "ITYPE dfv" "int nfbits"
86 initialises a Q number with the supplied integral value
88 and decimal fractional value
90 with appropriate control bits based on the requested radix shift point
93 must be passed as a preprocessor literal to preserve leading zeroes.
97 defined constant specifies the number of reserved control bits, currently 3.
107 count of total, control-encoded fractional, maximum fractional, effective
108 fractional, and integer bits applicable to
113 returns the C data type of
119 type casted to the C data type of
123 returns the bit position of
125 binary radix point relative to bit zero.
128 returns the absolute value of any standard numeric type
129 .Pq that uses the MSB as a sign bit, but not Q numbers
132 The function is signed/unsigned type safe.
137 return the integral value
139 left or right shifted by the appropriate amount for
143 calculates the maximum number of characters that may be required to render the
144 C-string representation of
150 renders the C-string representation of
154 and fractional precision
158 which has an available capacity of
166 as -1 renders the number's fractional component with maximum precision.
169 is greater than zero but insufficient to hold the complete C-string, the '\\0'
170 C-string terminator will be written to
172 thereby returning a zero length C-string.
175 returns a format string and associated data suitable for printf-like rendering
176 of debugging information pertaining to
182 are specified, they are prepended and appended to the resulting format string
186 boolean specifies whether to include
190 the raw format string itself in the debugging output.
193 converts decimal fractional value
195 to its binary-encoded representation with
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
204 All of those functions operate on
205 the following data types:
215 which are referred to generically as
223 is used to refer to any numeric type and is therefore a superset of
228 For more details, see
232 returns the initialised Q number which can be used to chain initialise
233 additional Q numbers.
236 returns a pointer to the '\\0' C-string terminator appended to
238 after the rendered numeric data, or NULL on buffer overflow.
241 returns the binary-encoded representation of decimal fractional value
253 functions first appeared in
259 functions and this manual page were written by
260 .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org
261 and sponsored by Netflix, Inc.