balanced-ternary 0.2.0

A library to manipulate balanced ternary values.
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
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

[![Rust](https://github.com/Trehinos/balanced-ternary/actions/workflows/rust.yml/badge.svg)](https://github.com/Trehinos/balanced-ternary/actions/workflows/rust.yml)

# Balanced Ternary

**Balanced Ternary** is a Rust library for manipulating *
*[balanced ternary](https://en.wikipedia.org/wiki/Balanced_ternary)** numbers, a numeral system with digits `-1`,
`0`, and `+1`.

This system is useful in areas like computer science and mathematics due to its symmetry and unique arithmetic
properties.

## Features

- **Number Conversions:** Convert between decimal and balanced ternary representations.
- **Arithmetic Operations:** Support for addition, subtraction, multiplication, and division.
- **[Logic Operations](https://en.wikipedia.org/wiki/Three-valued_logic):** Support for bitwise and, or, xor, and not.
- **Advanced logic**: Implementation of K3, BI3, L3, RM3 and HT imply operation.
- **Custom Representation:** Parse and display numbers using `+`, `0`, and `-` symbols.
- **No Standard Library:** Suitable for `#![no_std]` environments.
- Provides the types:
    - `Digit` (`Neg`, `Zero` or `Pos`),
    - `Ternary` (heap allocated variable-length balanced-ternary number),
    - `Tryte` (6 characters long copy-type ternary number).

### Digits operators

These operators can be applied for `Ternary` with `Ternary::each(operator)`:

| Unary operators       | ➖   | 0️⃣ | ➕   |
|-----------------------|-----|-----|-----|
| possibly              | ➖   | ➕   | ➕   |
| necessary             | ➖   | ➖   | ➕   |
| contingently          | ➖   | ➕   | ➖   |
| ht_not                | ➕   | ➖   | ➖   |
| post                  | 0️⃣ | ➕   | ➖   |
| pre                   | ➕️  | ➖   | 0️⃣ |
| `!` (not) / `-` (neg) | ➕   | 0️⃣ | ➖   |
| absolute_positive     | ➕   | 0️⃣ | ➕   |
| positive              | 0️⃣ | 0️⃣ | ➕   |
| not_negative          | 0️⃣ | ➕   | ➕   |
| not_positive          | ➖   | ➖   | 0️⃣ |
| negative              | ➖   | 0️⃣ | 0️⃣ |
| absolute_negative     | ➖   | 0️⃣ | ➖   |

These operators can be applied for `Ternary` with:
- `Ternary::each_with(operator, with)`, or,
- `Ternary::each_zip(operator, other)`:

| Binary operators | ➖➖  | ➖0️⃣ | ➖➕  | 0️⃣➖ | 0️⃣0️⃣ | 0️⃣➕ | ➕➖  | ➕0️⃣ | ➕➕  |
|------------------|-----|------|-----|:-----|:-------|:-----|:----|:-----|:----|
| `+` (add)        | ➖➕  | ➖    | 0️⃣ | ➖    | 0️⃣    | ➕    | 0️⃣ | ➕    | ➕➖  |
| `-` (sub)        | 0️⃣ | ➖    | ➖➕  | ➕    | 0️⃣    | ➖    | ➕➖  | ➕    | 0️⃣ |
| `/` (div)        | ➕   | 🚫   | ➖   | 0️⃣  | 🚫     | 0️⃣  | ➖   | 🚫   | ➕   |
| `*` (mul)        | ➕   | 0️⃣  | ➖   | 0️⃣  | 0️⃣    | 0️⃣  | ➖   | 0️⃣  | ➕   |
| `&` (bitand)     | ➖   | ➖    | ➖   | ➖    | 0️⃣    | 0️⃣  | ➖   | 0️⃣  | ➕   |
| bi3_and          | ➖   | 0️⃣  | ➖   | 0️⃣  | 0️⃣    | 0️⃣  | ➖   | 0️⃣  | ➕   |
| `\|` (bitor)     | ➖   | 0️⃣  | ➕   | 0️⃣  | 0️⃣    | ➕    | ➕   | ➕    | ➕   |
| bi3_or           | ➖   | 0️⃣  | ➕   | 0️⃣  | 0️⃣    | 0️⃣  | ➕   | 0️⃣  | ➕   |
| `^` (bitxor)     | ➖   | 0️⃣  | ➕   | 0️⃣  | 0️⃣    | 0️⃣  | ➕   | 0️⃣  | ➖   |
| k3_equiv         | ➕   | 0️⃣  | ➖   | 0️⃣  | 0️⃣    | 0️⃣  | ➖   | 0️⃣  | ➕   |
| k3_imply         | ➕   | ➕    | ➕   | 0️⃣  | 0️⃣    | ➕    | ➖   | 0️⃣  | ➕   |
| bi3_imply        | ➕   | 0️⃣  | ➕   | 0️⃣  | 0️⃣    | 0️⃣  | ➖   | 0️⃣  | ➕   |
| l3_imply         | ➕   | ➕    | ➕   | 0️⃣  | ➕      | ➕    | ➖   | 0️⃣  | ➕   |
| rm3_imply        | ➕   | ➕    | ➕   | ➖    | 0️⃣    | ➕    | ➖   | ➖    | ➕   |
| ht_imply         | ➕   | ➕    | ➕   | ➖    | ➕      | ➕    | ➖   | 0️⃣  | ➕   |

## Examples

### Convert between decimal and balanced ternary

```rust
use balanced_ternary::*;

fn test() {
    let ternary = Ternary::from_dec(5);
    assert_eq!(ternary.to_string(), "+--");

    let ternary = Ternary::parse("+--");
    assert_eq!(ternary.to_dec(), 5);
}
```

### Perform arithmetic or logic operations

```rust
use balanced_ternary::*;

fn test() {
    let a = Ternary::from_dec(9);
    let b = Ternary::from_dec(4);
    let sum = &a + &b;
    assert_eq!(ternary.to_string(), "+++");
    assert_eq!(sum.to_dec(), 13);

    let bitwise = &Ternary::parse("++00") & &Ternary::parse("0000");
    assert_eq!(bitwise.to_string(), "0000");

    let bitwise = &Ternary::parse("++00") & &Ternary::parse("0+00");
    assert_eq!(bitwise.to_string(), "0+00");

    let bitwise = &Ternary::parse("+000") | &Ternary::parse("000-");
    assert_eq!(bitwise.to_string(), "+000");


    let bitwise = &Ternary::parse("+000") & &Ternary::parse("000-");
    assert_eq!(bitwise.to_string(), "000-");

    let bitwise = &Ternary::parse("+000") | &Ternary::parse("000+");
    assert_eq!(bitwise.to_string(), "+00+");
}
```

### Handle negative numbers

```rust
use balanced_ternary::*;

fn test() {
    let negative = Ternary::from_dec(-5);
    assert_eq!(negative.to_string(), "-++");
}
```

## Installation

Add the following to your `Cargo.toml`:

```toml
[dependencies]
balanced-ternary = "0.1.*"
```

## License

Copyright (c) 2025 Sébastien GELDREICH  
`Balanced Ternary` is licensed under the [MIT License](LICENSE).