The float-features Reference Manual

This is the float-features Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 05:15:00 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 float-features

A portability library for IEEE float features not covered by the CL standard.

Maintainer

Yukari Hafner <>

Author

Yukari Hafner <>

Home Page

https://github.com/Shinmera/float-features

License

zlib

Version

1.0.0

Dependencies
  • trivial-features (system).
  • documentation-utils (system).
Source

float-features.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 float-features/float-features.asd

Source

float-features.asd.

Parent Component

float-features (system).

ASDF Systems

float-features.


3.1.2 float-features/float-features.lisp

Source

float-features.asd.

Parent Component

float-features (system).

Packages

float-features.

Public Interface
Internals

with-rounding-mode (macro).


3.1.3 float-features/documentation.lisp

Dependency

float-features.lisp (file).

Source

float-features.asd.

Parent Component

float-features (system).


3.1.4 float-features/nan.lisp

Dependency

documentation.lisp (file).

Source

float-features.asd.

Parent Component

float-features (system).

Public Interface

4 Packages

Packages are listed by definition order.


4.1 float-features

Source

float-features.lisp.

Nickname

org.shirakumo.float-features

Use List

common-lisp.

Public Interface
Internals

with-rounding-mode (macro).


5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Constants

Constant: double-float-nan

A positive quiet NaN value with zero-cleared payload for double-floats.
This value should NOT be used for comparison with a float value for the pupose of testing NaN
because NaN has unused bits (called payload) which are explicitly allowed to store additional information. Comparing this value with other NaN representations via = will fail.
To test if a number is a NaN, use FLOAT-NAN-P.

It is supported on implementations which support BITS-DOUBLE-FLOAT.

Defaults to MOST-POSITIVE-DOUBLE-FLOAT on unsupported implementations.

Package

float-features.

Source

nan.lisp.

Constant: double-float-negative-infinity

The negative infinity for double-floats.

Supported on:
* ABCL
* ALLEGRO
* CCL
* CMUCL
* ECL
* LISPWORKS
* MEZZANO
* MKCL
* SBCL

Defaults to MOST-NEGATIVE-DOUBLE-FLOAT on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Constant: double-float-positive-infinity

The positive infinity for double-floats.

Supported on:
* ABCL
* ALLEGRO
* CCL
* CMUCL
* ECL
* LISPWORKS
* MEZZANO
* MKCL
* SBCL

Defaults to MOST-POSITIVE-DOUBLE-FLOAT on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Constant: long-float-negative-infinity

The negative infinity for long-floats.

Supported on:
* CCL
* CMUCL
* ECL
* LISPWORKS
* MEZZANO
* MKCL
* SBCL

Defaults to MOST-NEGATIVE-LONG-FLOAT on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Constant: long-float-positive-infinity

The positive infinity for long-floats.

Supported on:
* CCL
* CMUCL
* ECL
* LISPWORKS
* MEZZANO
* MKCL
* SBCL

Defaults to MOST-POSITIVE-LONG-FLOAT on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Constant: short-float-nan

A positive quiet NaN value with zero-cleared payload for short-floats.
This value should NOT be used for comparison with a float value for the pupose of testing NaN
because NaN has unused bits (called payload) which are explicitly allowed to store additional information. Comparing this value with other NaN representations via = will fail.
To test if a number is a NaN, use FLOAT-NAN-P.

It is supported on implementations which support BITS-SHORT-FLOAT.

Defaults to MOST-POSITIVE-SHORT-FLOAT on unsupported implementations.

Package

float-features.

Source

nan.lisp.

Constant: short-float-negative-infinity

The negative infinity for short-floats.

Supported on:
* ALLEGRO
* CCL
* CMUCL
* ECL
* LISPWORKS
* MEZZANO
* MKCL
* SBCL

Defaults to MOST-NEGATIVE-SHORT-FLOAT on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Constant: short-float-positive-infinity

The positive infinity for short-floats.

Supported on:
* ALLEGRO
* CCL
* CMUCL
* ECL
* LISPWORKS
* MEZZANO
* MKCL
* SBCL

Defaults to MOST-POSITIVE-SHORT-FLOAT on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Constant: single-float-nan

A positive quiet NaN value with zero-cleared payload for single-floats.
This value should NOT be used for comparison with a float value for the pupose of testing NaN
because NaN has unused bits (called payload) which are explicitly allowed to store additional information. Comparing this value with other NaN representations via = will fail.
To test if a number is a NaN, use FLOAT-NAN-P.

It is supported on implementations which support BITS-SINGLE-FLOAT.

Defaults to MOST-POSITIVE-SINGLE-FLOAT on unsupported implementations.

Package

float-features.

Source

nan.lisp.

Constant: single-float-negative-infinity

The negative infinity for single-floats.

Supported on:
* ABCL
* ALLEGRO
* CCL
* CMUCL
* ECL
* LISPWORKS
* MEZZANO
* MKCL
* SBCL

Defaults to MOST-NEGATIVE-SINGLE-FLOAT on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Constant: single-float-positive-infinity

The positive infinity for single-floats.

Supported on:
* ABCL
* ALLEGRO
* CCL
* CMUCL
* ECL
* LISPWORKS
* MEZZANO
* MKCL
* SBCL

Defaults to MOST-POSITIVE-SINGLE-FLOAT on unsupported implementations.

Package

float-features.

Source

float-features.lisp.


5.1.2 Symbol macros

Symbol Macro: long-float-nan
Package

float-features.

Source

nan.lisp.


5.1.3 Macros

Macro: with-float-traps-masked (traps &body body)

Attempts to mask the given floating point traps.

Masking a floating point trap causes the given floating point exception to not signal a condition in the lisp world, and instead lets the operation return a float that is either a NaN or an infinity.

The following traps are recognised:

:underflow
:overflow
:inexact
:invalid
:divide-by-zero
:denormalized-operand

The traps argument may be either a list of the above trap identifiers, or T to signify all maskable traps.

Note that not all implementations will signal conditions on all of the above floating point traps anyway, and some implementations may only support masking some of the above traps.

Supported on:
* ABCL (:overflow :underflow)
* CCL (:overflow :underflow :inexact :invalid :divide-by-zero)
* CLISP (:underflow)
* CMUCL T
* ECL (:underflow :overflow :inexact :invalid :divide-by-zero)
* MEZZANO T
* SBCL T

Defaults to a progn on unsupported implementations and ignores unsupported traps.

Package

float-features.

Source

float-features.lisp.


5.1.4 Ordinary functions

Function: bits-double-float (bits)

Encodes the (unsigned-byte 64) bit representation into a native double-float.

Supported on:
* ABCL
* ALLEGRO
* CCL
* CLASP
* CMUCL
* LISPWORKS
* MEZZANO
* SBCL

Defaults to signalling an error on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Function: bits-long-float (bits)

Encodes the (unsigned-byte 128) bit representation into a native long-float.

Supported on:

Defaults to signalling an error on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Function: bits-short-float (bits)

Encodes the (unsigned-byte 16) bit representation into a native short-float.

Supported on:
* MEZZANO

Supported (with 32bit short-float = single-float) on:
* ALLEGRO
* CCL
* CMUCL
* ECL
* LISPWORKS (64-bit only. on 32-bit lw, short-float is not 16 or 32 bits) * SBCL

Defaults to signalling an error on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Function: bits-single-float (bits)

Encodes the (unsigned-byte 32) bit representation into a native single-float.

Supported on:
* ABCL
* ALLEGRO
* CCL
* CLASP
* CMUCL
* LISPWORKS
* MEZZANO
* SBCL

Defaults to signalling an error on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Function: double-float-bits (float)

Returns the bit representation of the double-float as an (unsigned-byte 64).

Supported on:
* ABCL
* ALLEGRO
* CCL
* CLASP
* CMUCL
* LISPWORKS
* MEZZANO
* SBCL

Defaults to signalling an error on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Function: float-infinity-p (float)

Returns T if the given float is an infinity, NIL otherwise.

Supported on:
* ABCL
* ALLEGRO
* CCL
* CMUCL
* ECL
* LISPWORKS
* MEZZANO
* SBCL

Defaults to comparing against the individual constants on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Function: float-nan-p (float)

Returns T if the given float is in not-a-number state, NIL otherwise.

Supported on:
* ABCL
* ALLEGRO
* CCL
* CMUCL
* ECL
* LISPWORKS
* MEZZANO
* SBCL

Defaults to returning NIL on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Function: long-float-bits (float)

Returns the bit representation of the long-float as an (unsigned-byte 128).

Supported on:

Defaults to signalling an error on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Function: short-float-bits (float)

Returns the bit representation of the short-float as an (unsigned-byte 16).

Supported on:
* MEZZANO

Supported (with 32bit short-float = single-float) on:
* ALLEGRO
* CCL
* CMUCL
* ECL
* LISPWORKS (64-bit only. on 32-bit lw, short-float is not 16 or 32 bits) * SBCL

On platforms with 32-bit short-float, low bits of significand are dropped without rounding, and out of range exponents are converted to infinities. All values returned by bits-short-float should convert
back to the same bits.

Defaults to signalling an error on unsupported implementations.

Package

float-features.

Source

float-features.lisp.

Function: single-float-bits (float)

Returns the bit representation of the single-float as an (unsigned-byte 32).

Supported on:
* ABCL
* ALLEGRO
* CCL
* CLASP
* CMUCL
* LISPWORKS
* MEZZANO
* SBCL

Defaults to signalling an error on unsupported implementations.

Package

float-features.

Source

float-features.lisp.


5.2 Internals


5.2.1 Macros

Macro: with-rounding-mode (mode &body body)

Temporarily set rounding mode when execute body.

The following modes are recognised:

:nearest Round to nearest, ties to even
:positive Round toward positive infinity
:negative Round toward negative infinity
:zero Round toward zero

Note that many compilers would by default try to fold floating point expressions into constants before the rounding mode can take effect. It is advisory to check disassembled functions to see if that is the case when the result is not expected.

Supported on:
* CCL
* CMUCL
* MEZZANO
* SBCL

Defaults to a progn on unsupported implementations.

Package

float-features.

Source

float-features.lisp.


Appendix A Indexes


A.1 Concepts