mirror of
https://github.com/GaloisInc/cryptol.git
synced 2024-09-11 22:17:18 +03:00
Update documentation with info about floats + fractional literals
This commit is contained in:
parent
bf2258b5d8
commit
39acf61ee5
15
CHANGES.md
15
CHANGES.md
@ -54,6 +54,21 @@
|
||||
typechecker will use that information to infer superclass instances
|
||||
from subclasses.
|
||||
|
||||
* Added a family of base types, `Float e p`, for working with
|
||||
floating point numbers. The parameters control the precision of
|
||||
the numbers, with `e` being the number of bits to use in the exponent
|
||||
and `p-1` being the number of bits to use in the mantissa.
|
||||
The `Float` family of types may be used through the usual overloaded
|
||||
functionality in Cryptol, and there is a new buit-in module called
|
||||
`Float`, which contains functionality specific to floating point numbers.
|
||||
|
||||
* Add a way to write fractional literals in base 2,8,10, and 16.
|
||||
Fractional literals are overloaded, and may be used for different types
|
||||
(currently `Rational` and the `Float` family). Fractional literal in base
|
||||
2,8,and 16 must be precise, and will be rejected statically if they cannot be
|
||||
represented exactly. Fractional literals in base 10 are rounded to the
|
||||
nearest even representable number.
|
||||
|
||||
## New features
|
||||
|
||||
* Document the behavior of lifted selectors.
|
||||
|
BIN
docs/Cryptol.pdf
BIN
docs/Cryptol.pdf
Binary file not shown.
@ -38,6 +38,21 @@ Literals
|
||||
, lengthFromThenTo first next last == len) =>
|
||||
[len]a
|
||||
|
||||
Fractional Literals
|
||||
-------------------
|
||||
|
||||
The predicate `FLiteral m n r a` asserts that the type `a` contains the
|
||||
fraction `m/n`. The flag `r` indicates if we should round (`r >= 1`)
|
||||
or report an error if the number can't be represented exactly.
|
||||
|
||||
type FLiteral : # -> # -> # -> * -> Prop
|
||||
|
||||
|
||||
Fractional literals are desugared into calles to the primitive `fraction`:
|
||||
|
||||
fraction : { m, n, r, a } FLiteral m n r a => a
|
||||
|
||||
|
||||
|
||||
Zero
|
||||
----
|
||||
|
Binary file not shown.
Binary file not shown.
@ -188,6 +188,51 @@ is inferred from context in which the literal is used. Examples:
|
||||
// a = Integer or [n] where n >= width 10
|
||||
\end{verbatim}
|
||||
|
||||
Numeric literals may also be written as polynomials by writing a
|
||||
polynomial expression in terms of \texttt{x} between an opening
|
||||
\texttt{\textless{}\textbar{}} and a closing
|
||||
\texttt{\textbar{}\textgreater{}}. Numeric literals in polynomial
|
||||
notation result in bit sequences of length one more than the degree of
|
||||
the polynomial. Examples:
|
||||
|
||||
\begin{verbatim}
|
||||
<| x^^6 + x^^4 + x^^2 + x^^1 + 1 |> // : [7], equal to 0b1010111
|
||||
<| x^^4 + x^^3 + x |> // : [5], equal to 0b11010
|
||||
\end{verbatim}
|
||||
|
||||
Cryptol also supports fractional literals using binary (prefix
|
||||
\texttt{0b}), octal (prefix \texttt{0o}), decimal (no prefix), and
|
||||
hexadecimal (prefix \texttt{ox}) digits. A fractional literal must
|
||||
contain a \texttt{.} and may optionally have an exponent. The base of
|
||||
the exponent for binary, octal, and hexadecimal literals is 2 and the
|
||||
exponent is marked using the symbol \texttt{p}. Decimal fractional
|
||||
literals use exponent base 10, and the symbol \texttt{e}. Examples:
|
||||
|
||||
\begin{verbatim}
|
||||
10.2
|
||||
10.2e3 // 10.2 * 10^3
|
||||
0x30.1 // 3 * 64 + 1/16
|
||||
0x30.1p4 // (3 * 64 + 1/16) * 2^4
|
||||
\end{verbatim}
|
||||
|
||||
All fractional literals are overloaded and may be used with types that
|
||||
support fractional numbers (e.g., \texttt{Rational}, and the
|
||||
\texttt{Float} family of types).
|
||||
|
||||
Some types (e.g.~the \texttt{Float} family) cannot represent all
|
||||
fractional literals precisely. Such literals are rejected statically
|
||||
when using binary, octal, or hexadecimal notation. When using decimal
|
||||
notation, the literal is rounded to the closes represental even number.
|
||||
|
||||
All numeric literals may also include \texttt{\_}, which has no effect
|
||||
on the literal value but may be used to improve readability. Here are
|
||||
some examples:
|
||||
|
||||
\begin{verbatim}
|
||||
0b_0000_0010
|
||||
0x_FFFF_FFEA
|
||||
\end{verbatim}
|
||||
|
||||
\hypertarget{expressions}{%
|
||||
\section{Expressions}\label{expressions}}
|
||||
|
||||
@ -233,6 +278,7 @@ f x : Bit // specify that `f x` has type `Bit`
|
||||
if x
|
||||
then y
|
||||
else z : Bit // the type annotation is on `z`, not the whole `if`
|
||||
[1..9 : [8]] // specify that elements in `[1..9]` have type `[8]`
|
||||
\end{verbatim}
|
||||
|
||||
\textbf{Local Declarations}
|
||||
@ -579,8 +625,8 @@ type T a b = [a] b
|
||||
\hypertarget{modules}{%
|
||||
\section{Modules}\label{modules}}
|
||||
|
||||
A \textbf{\emph{module}} is used to group some related definitions.
|
||||
Each file may contain at most one module.
|
||||
A \textbf{\emph{module}} is used to group some related definitions. Each
|
||||
file may contain at most one module.
|
||||
|
||||
\begin{verbatim}
|
||||
module M where
|
||||
|
@ -287,6 +287,61 @@ written \texttt{/.}, and should not be confused with
|
||||
and integers.
|
||||
|
||||
|
||||
%===============================================================================
|
||||
\section{Floating Point Numbers}
|
||||
\label{sec:floats}
|
||||
|
||||
The family of types \texttt{Float e p}\indTheFloatType represent IEEE 754
|
||||
floating point numbers with \texttt{e} bits in the exponent and
|
||||
\texttt{p-1} bits in the mantissa. The family is defined in a built-in
|
||||
module called \texttt{Float} so to use it you'd need to either import
|
||||
it in you Cryptol specification or use \texttt{:m Float} on the
|
||||
Cryptol REPL.
|
||||
|
||||
Floating point numbers may be written using either integral or fractioanl
|
||||
literals. In general, literals that cannot be represented exactly are
|
||||
rejected with a type error, with the exception of decimal fractional litrals
|
||||
which are rounded to the nearest even representable numbers.
|
||||
|
||||
Floating point numbers may be manipulated and compared using
|
||||
standard Cryptol operators, such as \texttt{+}, \texttt{==}, and \texttt{/.}
|
||||
(but {\em not} \texttt{/} which is only for integral types).
|
||||
When using the standard Cryptol operators the results that cannot be
|
||||
represented exactly are rounded to the nearest even representable number.
|
||||
|
||||
The module \texttt{Float} provides additional functionality specific
|
||||
to floating point numbers. In particular, it contains constants for
|
||||
writing special floating point values, and arithmetic operations
|
||||
that are parameterized on the rounding mode to use during computation
|
||||
(e.g., \texttt{fpAdd}).
|
||||
|
||||
Of particular importance is the relation \texttt{=.=} for comparing
|
||||
floating point numbers semantically, rather that using the IEEE equality,
|
||||
which is done by \texttt{==}. The behavior of the two differs
|
||||
mostly on special values, here are some examples:
|
||||
\begin{Verbatim}
|
||||
Float> fpNaN == (fpNaN : Float64)
|
||||
False
|
||||
Float> fpNaN =.= (fpNaN : Float64)
|
||||
True
|
||||
Float> 0 == (-0 : Float64)
|
||||
True
|
||||
Float> 0 =.= (-0 : Float64)
|
||||
False
|
||||
\end{Verbatim}
|
||||
|
||||
Cryptol supports reasoning about floating point numbers using the
|
||||
{\texttt What4} interface to solvers that support IEEE floats.
|
||||
These back-ends have names starting with {\texttt w4}, for example,
|
||||
a good one to try is \texttt{w4-z3}.
|
||||
|
||||
The Cryptol REPL has some settings to control how floating point numbers
|
||||
are printed on the REPL. In particular \texttt{:fp-base} specifies
|
||||
in what numeric base to output floating point numbers, while
|
||||
\texttt{:fp-format} provides various settings for formatting the
|
||||
results. For more information, see \texttt{:help :set fp-format}.
|
||||
|
||||
|
||||
%=====================================================================
|
||||
% \section{Tuples: Heterogeneous collections}
|
||||
% \label{sec:tuple}
|
||||
|
@ -50,6 +50,7 @@
|
||||
\newcommand{\indTheWordType}{\index{word}\xspace}
|
||||
\newcommand{\indTheIntegerType}{\index{integer}\xspace}
|
||||
\newcommand{\indTheRationalType}{\index{rational}\xspace}
|
||||
\newcommand{\indTheFloatType}{\index{float}\xspace}
|
||||
\newcommand{\indTheSequenceType}{\index{sequence}\xspace}
|
||||
\newcommand{\indTheRecordType}{\index{record}\xspace}
|
||||
\newcommand{\indTheStringType}{\index{string}\xspace}
|
||||
|
Binary file not shown.
@ -184,6 +184,32 @@ the degree of the polynomial. Examples:
|
||||
<| x^^6 + x^^4 + x^^2 + x^^1 + 1 |> // : [7], equal to 0b1010111
|
||||
<| x^^4 + x^^3 + x |> // : [5], equal to 0b11010
|
||||
|
||||
Cryptol also supports fractional literals using binary (prefix `0b`),
|
||||
octal (prefix `0o`), decimal (no prefix), and hexadecimal (prefix `ox`) digits.
|
||||
A fractional literal must contain a `.` and may optionally have an exponent.
|
||||
The base of the exponent for binary, octal, and hexadecimal literals is 2
|
||||
and the exponent is marked using the symbol `p`. Decimal fractional literals
|
||||
use exponent base 10, and the symbol `e`. Examples:
|
||||
|
||||
10.2
|
||||
10.2e3 // 10.2 * 10^3
|
||||
0x30.1 // 3 * 64 + 1/16
|
||||
0x30.1p4 // (3 * 64 + 1/16) * 2^4
|
||||
|
||||
All fractional literals are overloaded and may be used with types that support
|
||||
fractional numbers (e.g., `Rational`, and the `Float` family of types).
|
||||
|
||||
Some types (e.g. the `Float` family) cannot represent all fractional literals
|
||||
precisely. Such literals are rejected statically when using binary, octal,
|
||||
or hexadecimal notation. When using decimal notation, the literal is rounded
|
||||
to the closes represental even number.
|
||||
|
||||
|
||||
All numeric literals may also include `_`, which has no effect on the
|
||||
literal value but may be used to improve readability. Here are some examples:
|
||||
|
||||
0b_0000_0010
|
||||
0x_FFFF_FFEA
|
||||
|
||||
Expressions
|
||||
===========
|
||||
|
BIN
docs/Syntax.pdf
BIN
docs/Syntax.pdf
Binary file not shown.
Loading…
Reference in New Issue
Block a user