hwcalc 0.2.0

An arbitrary bit-width calculator
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
137
138

# hwcalc

hwcalc, or `hc`, is an arbitrary bit width calculator.

## Documentation

Refer to the man page at `docs/man/hc.1`, use e.g.

```
$ man -l docs/man/hc.1
```

There is also a rendered version available at <https://hllmn.net/man/hc.1>.

## Build

The Cargo package manager can be used to fetch dependencies and build `hc`:

```
$ cargo build --release
```

The resulting binary will be located at `target/release/hc`.

## Install

The makefile has a rule for installing the `hc` binary and the man page:

```
# make install
```

There is also an uninstall rule:

```
# make uninstall
```

Alternatively, `hc` can be installed from crates.io via Cargo:

```
cargo install hwcalc
```

This will install the `hc` binary in `bin/hc` under the Cargo root folder
(typically `~/.cargo`) but will not install the man page.

## Examples

`hc` mostly works like a typical calculator, one can enter expressions that
will be evaluated:
```
> (2 + 7) * 0xd
117
 = 0b111_0101
 = 0o165
 = 0x75
```

Numbers can be given a specific width with a type specifier:

```
> 77u8
77
 = 0b0100_1101
 = 0o115
 = 0x4d
```
For negative numbers, the non-decimal representations will display the two's
complement value:

```
> -77i8
-77 (= 179)
 = 0b1011_0011
 = 0o263
 = 0xb3
```

The signedness of a number affects how it is extended when operands differ in
width:

```
> 32u8 + (-1)'i4
31
 = 0b0001_1111
 = 0o037
 = 0x1f
> 32u8 + (-1)'u4
47
 = 0b0010_1111
 = 0o057
 = 0x2fa
```

Values may not only have integer values, they may also contain a fractional
part:

```
> 10/4
2.5 (= 5/2)
 = 0b10.1
 = 0o2.4
 = 0x2.8
```

By default, the precision is infinite, if a value cannot be represented by a
finite number of digits, infinitively repeating sequences of digits will be
enclosed with parentheses:

```
> 1/3
0.(3) (= 1/3)
 = 0b0.(01)
 = 0o0.(25)
 = 0x0.(5)
```

If a fractional width is specified, the fractional part will be truncated:

```
> 1/3q.8
0.332_031_25 (= 85/256)
 = 0b0.0101_0101
 = 0o0.252
 = 0x0.55
```

Negative numbers with an unspecified integer width will have an infinitively
repeating digit in the integer part for non-decimal bases:

```
> -5.25
-5.25 (= -21/4)
 = 0b(1)010.11
 = 0o(7)2.6
 = 0x(f)a.c
```