zfuel 0.5.0

ZFuel types used for a mutual credit accounting system
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
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# ZFuel

A high-precision Rust library for handling ZFuel types in mutual credit accounting systems. ZFuel provides fixed-point arithmetic with configurable precision (0-6 decimal places), ensuring accurate financial calculations without floating-point rounding errors.

[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Rust](https://github.com/zo-el/zfuel/actions/workflows/fuzz.yml/badge.svg)](https://github.com/zo-el/zfuel/actions/workflows/fuzz.yml)

## Features

- Variable precision support (0-6 decimal places)
- Type-safe precision handling with validation
- Mixed-precision arithmetic operations
- Full support for positive and negative values
- Precise fee calculations with configurable rates
- String parsing and formatting with full precision
- Comprehensive test coverage including fuzz testing
- No floating-point arithmetic, ensuring exact calculations
- Bounds checking on all operations
- Efficient implementation with zero-cost abstractions

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
zfuel = "0.4.0"
```

## Quick Start

```rust
use zfuel::fuel::{ZFuel, Precision};
use zfuel::fraction::Fraction;

// Create a ZFuel amount (default precision is 6)
let amount = ZFuel::from_str("123.456789").unwrap();

// Create with specific precision
let amount_2dp = ZFuel::new(12345, Precision::new(2).unwrap()); // 123.45

// Perform arithmetic operations
let doubled = (amount + amount).unwrap();
let sum = (amount + amount_2dp).unwrap(); // Automatically uses higher precision

// Calculate fees (1%)
let fee = (amount * Fraction::new(1, 100).unwrap()).unwrap();

// Format as string
println!("Amount: {}", amount);      // "123.456789"
println!("Doubled: {}", doubled);    // "246.913578"
println!("Fee: {}", fee);            // "1.234567"
```

## Documentation

- [API Documentation](https://docs.rs/zfuel)
- [Technical Documentation](docs/technical.md) - Detailed implementation details
- [CHANGELOG](CHANGELOG.md) - Version history and changes

## Development

### Prerequisites

- Rust (nightly toolchain)
- cargo-fuzz

### Setup

```bash
# Install nightly toolchain
rustup install nightly

# Install cargo-fuzz
cargo install cargo-fuzz
```

### Testing

The project includes comprehensive test coverage:

```bash
# Run all tests (unit tests and fuzz tests)
make all

# Run only unit tests
make test

# Run only fuzz tests
make fuzz

# Run specific fuzz tests
make fuzz-fuzz_fuel
make fuzz-fuzz_fraction
make fuzz-fuzz_fuel_string
make fuzz-fuzz_fuel_operations
make fuzz-fuzz_fraction_operations
make fuzz-fuzz_fee_calculations
make fuzz-fuzz_fuel_serialization
```

### Fuzz Testing

The project includes several fuzz tests to ensure robustness:

1. `fuzz_fuel`: Basic ZFuel creation and validation
2. `fuzz_fraction`: Fraction operations and validation
3. `fuzz_fuel_string`: String parsing and validation
4. `fuzz_fuel_operations`: Arithmetic operations
5. `fuzz_fraction_operations`: Fraction arithmetic
6. `fuzz_fee_calculations`: Fee computation
7. `fuzz_fuel_serialization`: Serialization/deserialization

## Contributing

Contributions are welcome! Please see our [Contributing Guidelines](.github/CONTRIBUTING.md) for details.

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.