# 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
```