arpfloat 0.1.5

Arbitrary-precision floating point library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

# Arbitrary-Precision Floating-Point Library

ARPFloat is an implementation of arbitrary precision 
[floating point](https://en.wikipedia.org/wiki/IEEE_754) data
structures and utilities. The library can be used to emulate floating point
operation, in software, or create new floating point data types.
`no_std` environments are supported by disabling the `std` feature.


### Example
```rust
  use arpfloat::Float;
  use arpfloat::FP128;

  // Create the number '5' in FP128 format.
  let n = Float::from_f64(5.).cast(FP128);

  // Use Newton-Raphson to find the square root of 5.
  let mut x = n.clone();
  for _ in 0..20 {
      x += (&n / &x)/2;
  }

  println!("fp128: {}", x);
  println!("fp64:  {}", x.as_f64());
 ```


The program above will print this output:
```console
fp128: 2.2360679774997896964091736687312763
fp64:  2.23606797749979
```

The library also provides API that exposes rounding modes, and low-level
operations.

```rust
    use arpfloat::FP128;
    use arpfloat::RoundingMode::NearestTiesToEven;
    use arpfloat::Float;

    let x = Float::from_u64(FP128, 1<<53);
    let y = Float::from_f64(1000.0).cast(FP128);

    let val = Float::mul_with_rm(&x, &y, NearestTiesToEven);
 ```

 View the internal representation of numbers:
 
 ```rust
    use arpfloat::Float;
    use arpfloat::FP16;

    let fp = Float::from_i64(FP16, 15);

    fp.dump(); // Prints FP[+ E=+3 M=11110000000]

    let m = fp.get_mantissa();
     m.dump(); // Prints 11110000000
```

 Control the rounding mode for type conversion:
 
```rust
    use arpfloat::{FP16, FP32, RoundingMode, Float};

    let x = Float::from_u64(FP32, 2649);
    let b = x.cast_with_rm(FP16, RoundingMode::Zero);
    println!("{}", b); // Prints 2648!
```

 Define new float formats and use high-precision transcendental functions:
 
```rust
  use arpfloat::{Float, Semantics};
  // Define a new float format with 120 bits of accuracy, and dynamic range
  // of 2^10.
  let sem = Semantics::new(10, 120);

  let pi = Float::pi(sem);
  let x = Float::exp(&pi);
  println!("e^pi = {}", x); // Prints 23.1406926327792....
```


The [examples](examples) directory contains a program that computes many digits of pi in float-256.

### Resources

There are excellent resources out there, some of which are referenced in the code:

* Books:
    * Handbook of Floating-Point Arithmetic 2010th by Jean-Michel Muller et al.
    * Elementary Functions: Algorithms and Implementation by Jean-Michel Muller.
    * Modern Computer Arithmetic by Brent and Zimmermann.
* Papers:
    * How to print floating-point numbers accurately by Steele, White.
    * What Every Computer Scientist Should Know About Floating-Point Arithmetic by David Goldberg.
    * Fast Multiple-Precision Evaluation of Elementary Functions by Richard Brent.
    * Fast Trigonometric functions for Arbitrary Precision number by Henrik Vestermark.
* Other excellent software implementations: APFloat, RYU, libBF, newlib, musl, etc.

### License

Licensed under Apache-2.0