Basic README
This commit is contained in:
adrien
parent
b0e06bf4cf
commit
305d113752
306
README.md
306
README.md
@ -0,0 +1,306 @@
|
|||||||
|
# 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.
|
||||||
Loading…
x
Reference in New Issue
Block a user