307 lines
8.8 KiB
Markdown
307 lines
8.8 KiB
Markdown
# zig_units
|
||
|
||
**Compile-time dimensional analysis for Zig.**
|
||
|
||
`zig_units` lets you attach physical units to numeric values so that
|
||
dimension mismatches become *compile errors* rather than silent bugs.
|
||
At runtime a `Quantity` is nothing but a single number — zero overhead.
|
||
|
||
```
|
||
velocity = distance / time → L¹T⁻¹ ✓
|
||
force = mass + velocity → compile error: M¹ ≠ L¹T⁻¹
|
||
```
|
||
|
||
Requires **Zig 0.16** or later.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
- Seven SI base dimensions (`L M T I Tp N J`)
|
||
- Full SI prefix support (`P T G M k h da d c m u n p f`)
|
||
- Custom time aliases (`.min`, `.hour`, `.year`)
|
||
- Automatic scale conversion on add/sub (finer unit wins)
|
||
- `Quantity(T, dims, scales)` — scalar, any numeric backing type
|
||
- `QuantityVec3` — three-component vector with the same guarantees
|
||
- Unicode superscript formatting (`9.81m.s⁻²`)
|
||
- Integer-safe square root for `Vec3.length()`
|
||
- All dimension tracking happens at `comptime` — no runtime cost
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
### Add as a Zig dependency
|
||
|
||
```bash
|
||
zig fetch --save https://github.com/YOUR_USERNAME/zig_units/archive/refs/heads/main.tar.gz
|
||
```
|
||
|
||
This adds an entry to your `build.zig.zon`. Then wire it up in your
|
||
`build.zig`:
|
||
|
||
```zig
|
||
const zig_units = b.dependency("zig_units", .{
|
||
.target = target,
|
||
.optimize = optimize,
|
||
});
|
||
my_module.addImport("zig_units", zig_units.module("zig_units"));
|
||
```
|
||
|
||
### Local path (monorepo / development)
|
||
|
||
```zig
|
||
// build.zig.zon
|
||
.dependencies = .{
|
||
.zig_units = .{ .path = "../zig_units" },
|
||
},
|
||
```
|
||
|
||
---
|
||
|
||
## Quick start
|
||
|
||
```zig
|
||
const units = @import("zig_units");
|
||
const Quantity = units.Quantity;
|
||
const Dims = units.Dimensions;
|
||
const Scales = units.Scales;
|
||
|
||
// Define named unit types
|
||
const Meter = Quantity(f32, Dims.init(.{ .L = 1 }), Scales.init(.{}));
|
||
const KiloMeter= Quantity(f32, Dims.init(.{ .L = 1 }), Scales.init(.{ .L = .k }));
|
||
const Second = Quantity(f32, Dims.init(.{ .T = 1 }), Scales.init(.{}));
|
||
const MPerSec = Quantity(f32, Dims.init(.{ .L = 1, .T = -1 }), Scales.init(.{}));
|
||
|
||
const dist = Meter{ .value = 100.0 };
|
||
const t = Second{ .value = 5.0 };
|
||
|
||
// Dimension is tracked automatically — vel has type L¹T⁻¹
|
||
const vel = dist.divBy(t);
|
||
|
||
// Convert to an explicit type (same dims required, compile error otherwise)
|
||
const vel2 = vel.to(MPerSec);
|
||
|
||
// Cross-scale addition: km + m → result in metres (finer scale)
|
||
const km = KiloMeter{ .value = 1.0 };
|
||
const sum = km.add(dist); // 1100 m
|
||
```
|
||
|
||
---
|
||
|
||
## API reference
|
||
|
||
### `Quantity(T, dims, scales)`
|
||
|
||
| Member | Kind | Description |
|
||
|---|---|---|
|
||
| `value` | field | The raw numeric value |
|
||
| `ValueType` | comptime | Alias for `T` |
|
||
| `dims` | comptime | The `Dimensions` of this type |
|
||
| `scales` | comptime | The `Scales` of this type |
|
||
| `Vec3` | comptime | The matching `QuantityVec3` type |
|
||
| `add(rhs)` | fn | Same-dimension addition, finer scale |
|
||
| `sub(rhs)` | fn | Same-dimension subtraction, finer scale |
|
||
| `mulBy(rhs)` | fn | Multiplication, dims are added |
|
||
| `divBy(rhs)` | fn | Division, dims are subtracted |
|
||
| `scale(s: T)` | fn | Dimensionless scalar multiply |
|
||
| `to(Dest)` | fn | Convert to another `Quantity` type (same dims) |
|
||
| `vec3()` | fn | Broadcast scalar to a `Vec3` |
|
||
| `format(writer)` | fn | Print `value + unit string` |
|
||
|
||
### `QuantityVec3`
|
||
|
||
Obtained via `SomeQuantity.Vec3`.
|
||
|
||
| Member | Kind | Description |
|
||
|---|---|---|
|
||
| `x, y, z` | fields | The three components |
|
||
| `zero` | comptime | `(0, 0, 0)` |
|
||
| `one` | comptime | `(1, 1, 1)` |
|
||
| `initDefault(v)` | fn | Broadcast scalar to all components |
|
||
| `add(rhs)` | fn | Component-wise addition |
|
||
| `sub(rhs)` | fn | Component-wise subtraction |
|
||
| `mulBy(rhs)` | fn | Component-wise element-wise multiply |
|
||
| `divBy(rhs)` | fn | Component-wise element-wise divide |
|
||
| `mulByScalar(q)` | fn | Multiply by a scalar `Quantity` |
|
||
| `divByScalar(q)` | fn | Divide by a scalar `Quantity` |
|
||
| `scale(s: T)` | fn | Dimensionless scalar multiply |
|
||
| `negate()` | fn | Negate all components |
|
||
| `to(DestQ)` | fn | Convert to another vector quantity type |
|
||
| `lengthSqr()` | fn | Squared Euclidean length (no sqrt) |
|
||
| `length()` | fn | Euclidean length (integer-safe) |
|
||
| `format(writer)` | fn | Print `(x, y, z) + unit string` |
|
||
|
||
### `Dimensions`
|
||
|
||
A comptime struct storing a signed exponent per SI base dimension.
|
||
|
||
```zig
|
||
const Dims = @import("zig_units").Dimensions;
|
||
|
||
// Acceleration: L¹ T⁻²
|
||
const accel_dims = Dims.init(.{ .L = 1, .T = -2 });
|
||
```
|
||
|
||
| Function | Description |
|
||
|---|---|
|
||
| `init(struct_literal)` | Create from named exponents; unset dims default to 0 |
|
||
| `initFill(val: i8)` | Set all exponents to `val` |
|
||
| `get(dim)` | Read a single exponent |
|
||
| `set(dim, val)` | Write a single exponent |
|
||
| `add(a, b)` | Component-wise sum (for `mulBy`) |
|
||
| `sub(a, b)` | Component-wise difference (for `divBy`) |
|
||
| `eql(a, b)` | Equality check |
|
||
| `str()` | Comptime human-readable string, e.g. `"L1T-2"` |
|
||
|
||
### `Scales`
|
||
|
||
A comptime struct storing a `UnitScale` per SI base dimension.
|
||
|
||
```zig
|
||
const Scales = @import("zig_units").Scales;
|
||
|
||
// Kilometres per nanosecond
|
||
const spd_scales = Scales.init(.{ .L = .k, .T = .n });
|
||
```
|
||
|
||
| `UnitScale` variant | Factor |
|
||
|---|---|
|
||
| `.P` | ×10¹⁵ |
|
||
| `.T` | ×10¹² |
|
||
| `.G` | ×10⁹ |
|
||
| `.M` | ×10⁶ |
|
||
| `.k` | ×10³ |
|
||
| `.h` | ×10² |
|
||
| `.da` | ×10¹ |
|
||
| `.none` | ×1 |
|
||
| `.d` | ×10⁻¹ |
|
||
| `.c` | ×10⁻² |
|
||
| `.m` | ×10⁻³ |
|
||
| `.u` | ×10⁻⁶ |
|
||
| `.n` | ×10⁻⁹ |
|
||
| `.p` | ×10⁻¹² |
|
||
| `.f` | ×10⁻¹⁵ |
|
||
| `.min` | ×60 (seconds) |
|
||
| `.hour` | ×3 600 |
|
||
| `.year` | ×31 536 000 |
|
||
|
||
---
|
||
|
||
## Examples
|
||
|
||
### Kinematics
|
||
|
||
```zig
|
||
const Meter = Quantity(f64, Dims.init(.{ .L = 1 }), Scales.init(.{}));
|
||
const Second = Quantity(f64, Dims.init(.{ .T = 1 }), Scales.init(.{}));
|
||
|
||
const pos = Meter{ .value = 200.0 };
|
||
const time = Second{ .value = 8.0 };
|
||
|
||
const vel = pos.divBy(time); // L¹T⁻¹ — 25 m/s
|
||
const accel = vel.divBy(time); // L¹T⁻² — 3.125 m/s²
|
||
```
|
||
|
||
### Cross-scale addition
|
||
|
||
```zig
|
||
const KM = Quantity(i64, Dims.init(.{ .L = 1 }), Scales.init(.{ .L = .k }));
|
||
const M = Quantity(i64, Dims.init(.{ .L = 1 }), Scales.init(.{}));
|
||
|
||
const a = KM{ .value = 2 }; // 2 km
|
||
const b = M{ .value = 500 }; // 500 m
|
||
|
||
const sum = a.add(b); // result scale = metres (finer) → 2500 m
|
||
```
|
||
|
||
### Time conversion
|
||
|
||
```zig
|
||
const Hour = Quantity(i64, Dims.init(.{ .T = 1 }), Scales.init(.{ .T = .hour }));
|
||
const Minute = Quantity(i64, Dims.init(.{ .T = 1 }), Scales.init(.{ .T = .min }));
|
||
const Second = Quantity(i64, Dims.init(.{ .T = 1 }), Scales.init(.{}));
|
||
|
||
const h = Hour{ .value = 2 };
|
||
const min = h.to(Minute); // 120
|
||
const sec = min.to(Second); // 7200
|
||
```
|
||
|
||
### Vec3 velocity
|
||
|
||
```zig
|
||
const Meter = Quantity(f32, Dims.init(.{ .L = 1 }), Scales.init(.{}));
|
||
const Second = Quantity(f32, Dims.init(.{ .T = 1 }), Scales.init(.{}));
|
||
|
||
const pos = Meter.Vec3{ .x = 30.0, .y = 60.0, .z = 90.0 };
|
||
const time = Second{ .value = 3.0 };
|
||
|
||
const vel = pos.divByScalar(time); // Vec3 with dims L¹T⁻¹
|
||
const dist = vel.length(); // Euclidean length
|
||
```
|
||
|
||
### Dimension mismatch — compile error
|
||
|
||
```zig
|
||
const Meter = Quantity(f32, Dims.init(.{ .L = 1 }), Scales.init(.{}));
|
||
const Second = Quantity(f32, Dims.init(.{ .T = 1 }), Scales.init(.{}));
|
||
|
||
const d = Meter{ .value = 5.0 };
|
||
const t = Second{ .value = 2.0 };
|
||
|
||
// This will NOT compile:
|
||
const bad = d.add(t); // error: Dimension mismatch in add: L1 vs T1
|
||
```
|
||
|
||
---
|
||
|
||
## Running the tests
|
||
|
||
```bash
|
||
zig build test
|
||
```
|
||
|
||
The test suite covers scalar and vector arithmetic, cross-scale operations,
|
||
conversion chains, negative values, formatting, and an optional benchmark
|
||
(`"Comprehensive Benchmark: All Ops × All Types"`).
|
||
|
||
---
|
||
|
||
## Project layout
|
||
|
||
```
|
||
zig_units/
|
||
├── build.zig # Build script; exposes the "zig_units" module
|
||
├── build.zig.zon # Package manifest
|
||
├── src/
|
||
│ ├── main.zig # Quantity, QuantityVec3, tests
|
||
│ ├── Dimensions.zig # SI base dimensions + comptime arithmetic
|
||
│ ├── Scales.zig # SI prefixes + scale helpers
|
||
│ └── helper.zig # Internal utilities (isInt, printSuperscript)
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## Design notes
|
||
|
||
**Why comptime parameters?** Zig's `comptime` means the compiler can
|
||
evaluate all dimension arithmetic before any machine code is generated.
|
||
Two quantities with mismatched dimensions simply fail to compile —
|
||
there is no runtime overhead and no need for exception handling.
|
||
|
||
**Scale selection on arithmetic.** When two operands have different
|
||
scales (e.g. km and m), `zig_units` automatically picks the finer
|
||
(smaller-factor) scale for the result. This prevents silent precision
|
||
loss at the cost of an automatic rescaling of both operands.
|
||
|
||
**Integer backing types.** Division uses an `f64` intermediate and
|
||
rounds back to the integer type. For best accuracy, prefer `f32`/`f64`
|
||
for quantities that will be divided frequently.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT — see `LICENSE` for details.
|