Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the fixed Reference Manual, version 0.0.2, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 16:04:35 2021 GMT+0.
| • Introduction | What fixed is all about | |
| • Systems | The systems documentation | |
| • Modules | The modules documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
A Common Lisp fixed-point numeric type package intended to be similar to the Ada language type. The focus is providing a useful abstraction for known reliable precision in a specific range. This package uses CLOS to encapsulate the underlying type.
If the reader macro is installed (install-reader-macro), then fixed point values can be read without floating point precision issues.
A small utility package (:fixed/real-time) provides a portable fixed-point type representing the internal real time.
Please let me know if you find this useful, or encounter issues.
;; Ordinary power-of-2 fixed point type that supports a resolution of 1/10.
;; This is represented by a 1/16 resolution value.
> (defdelta foo 1/10)
;; Reader macro usage.
> #q foo 1.25
#<FOO 5/4>
;; Fixed point type with precise resolution
;; This is represented by a 1/10 resolution value.
> (defdelta bar 1/10 :small 1/10)
;; Adding range info
> (defdelta foobar 0.01 :small 0.01 :low 0.00 :high 1.00)
> (defparameter fb (make-foobar 0.5))
FB
> fb
#<FOOBAR 0.5>
> (f+ fb (make-foobar 1/2))
#<FOOBAR 1.0>
> (f+ fb (make-foobar 0.51))
;; ERROR: The value 101 is not of type (MOD 101).
> (setf (foobar fb) 0.49)
#<FOOBAR 0.48999998>
> (f+ fb (make-foobar 0.51))
#<FOOBAR 1.0>
;; Base 10 decimal types are simply created like this:
> (fixed:defdecimal milli 3)
MILLI
;; Using the make-milli function works...but comes with
;; floating point precision issues.
> (make-milli 123456789.001)
#<MILLI 123456782.336>
0.0
;; Using the #q reader avoids floating point representation.
> #q milli 123456789.001
#<MILLI 123456789.001>
A fixed-point reader macro provides a method to input fixed-point literals in decimal form. The reader macro uses the Q format to define a fixed-point spec for the following value.
Install the reader macro as a Q dispatch on # with (install-q-reader).
e.g.
;; Read in fixed-point literals that can be represented exactly by a Q8 spec.
> #Q8 1.5
3/2
> #Q8 0.0078125
1/128
;; Read in a fixed-point literal that can be represented exactly by a Q3 spec, and one that can't.
> #Q3 1.5
3/2
> #Q3 0.0078125
;; ERROR: 0.0078125 is not a #Q3
Bounds checking can also be performed when the maximum number of useable bits are provided in the Q spec.
;; Read in the most positive Q7.8 value.
> #Q7.8 255.99609375
65535/256
> #Q7.8 256.0
;; Error: 256.0 is not a #Q7.8
> #Q7.8 -256.0
-256
Decimal fixed-point values can be read as well with #QD and an optional spec value for digits.
e.g.
> #QD 1.2345678901234567890
1234567890123456789/1000000000000000000
> #QD3 1.2345678901234567890
;; ERROR: 1.2345678901234567890 is not a #QD3
> #QD3 1.234
617/500
> (float *)
1.234
defdelta name delta [:small small-value] [:low low-value] [:high high-value]
=> delta-name
defdecimal name power [:low low-value] [:high high-value]
=> decimal-name
name --- a symbol
delta --- real number
power --- integer
small-value, low-value, and high-value --- optional real numbers
defdelta defines a fixed-point number type named name capable of representing a value with at least the accuracy provided in delta.
If small-value is provided in defdelta, it must be a real value no greater than delta. small-value is used as the minimum resolution scaling factor for the underlying value. When small-value is not provided, it will be chosen automatically and will be no larger than delta.
The small-value can be any real number, but rationals are recommended to avoid unexpected rounding behaviors for some of the operations. If necessary, consider entering a decimal value using the provided #Q reader macro. The following are equivalent.
(defdelta a-fixed-type #qd 0.2 :small #qd 0.2)
(defdelta a-fixed-type 1/5 :small 1/5)
defdecimal defines a fixed-point number type named name capable of representing a base-10 decimal value with up to power number of digits to the right of the decimal. The small-value selected will be (expt 10 (- power)). Note: This declaration is different from the Ada decimal type where you must still define the delta (but as a power-of-10), and you define the number of digits to use in the underlying type.
low-value and high-value are both optional for defdelta or defdecimal, and are used to define the most-negative and most-positive values of the fixed point type.
defdecimal is essentially identical to defdelta when called with an identical delta and small that is a power of 10. The only difference is that values that have a defdecimal defined type will always be printed in decimal form. Values with a defdelta defined type may be printed as rationals.
defdelta and defdecimal create a set of functions and generic methods associated with name.
| Operation | Type | Description | | --- | --- | --- | | (make-name value) | Function | Return a new instance of name with value rounded as necessary with *rounding-method* | | (make-name-value value) | Function | Return a new instance of name with the provided underlying value | | (name fp) | Function | Return the value in the name instance scaled by small | | (name-value fp) | Function | Returns the underlying value of an instance of name | | (set-name fp value) | Generic | Set the value of a name instance, rounding as necessary with *rounding-method* | | (set-name-value fp value) | Function | Set the underlying integer value of an instance of name | | (setf (name fp) value) | setf | Set the value of fp with rounding as necessary with *rounding-method* | | (setf (name-value fp) value) | setf | Set the underlying value of fp | | (small fp) or (small 'name) | Generic | Return the small when passed 'name or an instance of name | | (delta fp) or (delta 'name) | Generic | Return the delta when passed 'name or an instance of name | | (size fp) or (size 'name) | Generic | Return the number of bits required to store the underlying value of name when it is ranged, otherwise return :INFINITY |
+MOST-POSITIVE-NAME+ is defined for each fixed-point type and is either the most positive value, or :POSITIVE-INFINITY if unlimited.
+MOST-NEGATIVE-NAME+ is defined for each fixed-point type and is either the most negative value, or :NEGATIVE-INFINITY if unlimited.
Generic Function Predicates: f= f/= f> f>= f< f<=
Generic Arithmetic Operations: f+ f- f* f/
A utility package that implements a fixed-point type for internal real time.
;; Get the current internal real time as a fixed point
> (defparameter the-time (current-time))
THE-TIME
> the-time
#<REAL-TIME 3711125.080>
;; do some stuff
;; calculate deltat
> (f- (current-time) the-time)
#<REAL-TIME 15.616>
MIT
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The fixed system |
Nick Patrick <npatrick04@gmail.com>
MIT
A fixed-point number type.
0.0.2
fixed.asd (file)
src (module)
Modules are listed depth-first from the system components tree.
| • The fixed/src module |
fixed (system)
src/
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
| • The fixed.asd file | ||
| • The fixed/src/package.lisp file | ||
| • The fixed/src/reader.lisp file | ||
| • The fixed/src/fixed.lisp file |
Next: The fixed/src/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
fixed.asd
fixed (system)
Next: The fixed/src/reader․lisp file, Previous: The fixed․asd file, Up: Lisp files [Contents][Index]
Next: The fixed/src/fixed․lisp file, Previous: The fixed/src/package․lisp file, Up: Lisp files [Contents][Index]
src (module)
src/reader.lisp
Previous: The fixed/src/reader․lisp file, Up: Lisp files [Contents][Index]
src (module)
src/fixed.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The fixed package |
package.lisp (file)
common-lisp
Definitions are sorted by export status, category, package, and then by lexicographic order.
| • Exported definitions | ||
| • Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
| • Exported special variables | ||
| • Exported macros | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported conditions | ||
| • Exported classes |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
#’round or #’truncate or similar functions will be used to handle precision loss.
fixed.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [Contents][Index]
A short-cut for defining a base-10 decimal type, that also happens to be printed correctly.
fixed.lisp (file)
Define a fixed point class named NAME which supports a resolution
of DELTA. The class maintains the value as an
(INTEGER LOW-RANGE HIGH-RANGE) where the LOW-RANGE and HIGH_RANGE are
determined to provide an engineering-unit value within the range of low
to high.
When SMALL is provided, the resolution of the type is defined to
be exactly SMALL. When only DELTA is provided, the resolution of
the type is defined to be the negative power of 2 that is no larger
than DELTA.
e.g. (defdelta foo 1/10) yields a SMALL value of 1/16.
(defdelta foo 1/10 :small 1/10) yields a SMALL value of 1/10.
This definition also produces a set of related functions and generic
methods for working with the NAME type.
- MAKE-NAME: Creates a NAME type with initial value rounded to the
provided value.
- MAKE-NAME-VALUE: Creates a NAME type with internal value as
provided.
- SET-NAME: A function to set the internal value according to the
engineering unit value provided by rounding.
- SET-NAME-VALUE: A function to set the internal value.
- NAME-VALUE: Accessor (setf’able) for the internal value.
- NAME: Accessor (setf’able) for the engineering unit value.
- Predicates: f= f/= f< f<= f> f>=
- Math operations: f+ f- f* f/
fixed.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
The Q reader can be used to read fixed point types directly with
exact precision. Generic fixed point types will be read directly
as rational values, and are suitable as an argument for a compatible
fixed point type using the MAKE-NAME constructor, where NAME is
the name of the fixed point type.
A generic ordinary fixed point Q spec looks like this:
#Q3 => a type with delta and small of (/ (expt 2 3))
#Q7.8 => a 16 bit (1+ 7 8) signed type with delta and small of (/ (expt 2 8))
A generic decimal fixed point Q spec looks like this:
#QD3 => a type with delta and small of 1/1000
#QD3.1 => a 5 bit type with delta and small of 1/10, i.e. min == -
Use the Q reader to input fixed-point literals in decimal form. The
rightmost integer in the Q spec defines the number of fractional
bits. The left-most number before the period, if provided, defines
the number of non-fractional bits. The sign bit is implied.
e.g.
#Q3 1.5 => 3/2
#Q3 1.25 => 5/4
#Q3 1.125 => 9/8
#Q3 1.0625 => Error: 1.0625 is not a Q3
The error in the last one is because 1.0625 requires 4 fractional bits
to represent.
#Q4 1.0625 => 17/16
Currently, the reader function returns a ratio representing the
decimal value read.
reader.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Is the object a decimal fixed point type.
fixed.lisp (file)
Return the delta used by fp.
fixed.lisp (file)
Multiply all fixed-point arguments of a single
type. The first value returned is the resultant fixed-point value,
the second value is the residual.
fixed.lisp (file)
Sum all fixed-point arguments of a single type.
fixed.lisp (file)
Subtract all fixed-point arguments of a single type
from the first value when more than one value are provided. If only
a single value is provided, negate that value.
fixed.lisp (file)
Divide the first value by the rest, or perform the
inverse operation if a single value is provided.
The first value returned is the resultant fixed-point value, the
second value is the residual.
fixed.lisp (file)
Determine if fixed-point values of the same type are not equal.
fixed.lisp (file)
Determine if fixed-point values of the same type are in ascending order.
fixed.lisp (file)
Determine if fixed-point values of the same type are in ascending-or-equal order.
fixed.lisp (file)
Determine if fixed-point values of the same type are equal.
fixed.lisp (file)
Determine if fixed-point values of the same type are in descending order.
fixed.lisp (file)
Determine if fixed-point values of the same type are in descending-or-equal order.
fixed.lisp (file)
Is the object an fixed point type.
fixed.lisp (file)
Is the object an ordinary fixed point type.
fixed.lisp (file)
Is the object a ranged fixed point type.
fixed.lisp (file)
Return the number of bits required by a ranged fp. An fp type defined with zero or one limits returns :INFINITY.
fixed.lisp (file)
Return the scaling factor used by fp.
fixed.lisp (file)
Next: Exported classes, Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
reader.lisp (file)
error (condition)
reader.lisp (file)
q-reader-error (condition)
q-reader-invalid-value-message (method)
:message
q-reader-invalid-value-message (generic function)
reader.lisp (file)
q-reader-error (condition)
reader.lisp (file)
q-reader-error (condition)
unknown-fixed-type-symbol (method)
:symbol
unknown-fixed-type-symbol (generic function)
Previous: Exported conditions, Up: Exported definitions [Contents][Index]
fixed.lisp (file)
standard-object (class)
fixed.lisp (file)
fp (class)
ordinary-fixedp (method)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal constants | ||
| • Internal macros | ||
| • Internal functions | ||
| • Internal generic functions | ||
| • Internal classes |
Next: Internal macros, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
reader.lisp (file)
Next: Internal functions, Previous: Internal constants, Up: Internal definitions [Contents][Index]
Do the work of creating the delta type.
fixed.lisp (file)
fixed.lisp (file)
fixed.lisp (file)
fixed.lisp (file)
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
reader.lisp (file)
Is a number a power of 2? If so, return that power.
fixed.lisp (file)
fixed.lisp (file)
reader.lisp (file)
A generic Q spec looks like this:
#Q3 => a type with delta and small of (/ (expt 2 3))
Return value (cons nil 3)
#Q7.8 => a 16 bit (1+ 7 8) signed type with delta and small of (/ (expt 2 8))
Return value (cons 7 8)
Alternatively, a generic Q spec could be in decimal form:
#QD2 123.45 => 12345/100
reader.lisp (file)
reader.lisp (file)
Read a decimal #QD with infinite precision, or #QDvalue where value is some integer defining the number of digits of precision.
reader.lisp (file)
Read a decimal #QD with infinite precision, or #QDvalue where value is some integer defining the number of digits of precision.
reader.lisp (file)
Read a base-10 integer, leaving whitespace or other characters on the stream. The integer is terminated by any non-digit-char. Return is (values sign result power terminating-char)
reader.lisp (file)
Read an ordinary fixed-point value.
reader.lisp (file)
Read an ordinary fixed-point value.
reader.lisp (file)
Read a user-specified Q type, or the D for a decimal type. If the first character read is #D or #d, followed by a digit character, then the result is ’D, indicating a decimal type.
Otherwise, the character is unread, the READ function is called, returning the resultant symbol
reader.lisp (file)
This reads the integer and fraction into the car and cdr of a cons. The second value is a cons of the count of digits in the first and second integers.
reader.lisp (file)
reader.lisp (file)
reader.lisp (file)
reader.lisp (file)
Given a cons of a Q spec (see Q-READER), return the inverse of the small-value of a corresponding fixed type.
reader.lisp (file)
fixed.lisp (file)
Next: Internal classes, Previous: Internal functions, Up: Internal definitions [Contents][Index]
reader.lisp (file)
reader.lisp (file)
Previous: Internal generic functions, Up: Internal definitions [Contents][Index]
fixed.lisp (file)
fp (class)
decimal-fixedp (method)
fixed.lisp (file)
fp (class)
ranged-fixedp (method)
Previous: Definitions, Up: Top [Contents][Index]
| • Concept index | ||
| • Function index | ||
| • Variable index | ||
| • Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
| Jump to: | F L M |
|---|
| Jump to: | F L M |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | %
C D F G I M O P Q R S U |
|---|
| Jump to: | %
C D F G I M O P Q R S U |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
+
C M S V |
|---|
| Jump to: | *
+
C M S V |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | C D F O P Q R S |
|---|
| Jump to: | C D F O P Q R S |
|---|