adrien/zig-dimal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Compare commits

base: adrien:52e58829eb85071edb3d1a97283ed1c2951d0831
Branches Tags
adrien:main
adrien:0.1.1
adrien:0.1.0
..
compare: adrien:79bf70d5031e12b9fd1086c38e789744681891c1
Branches Tags
adrien:main
adrien:0.1.1
adrien:0.1.0

3 Commits
52e58829eb ... 79bf70d503

Author SHA1 Message Date
AdrienBouvais
79bf70d503 Better README.zig 2026-04-21 15:14:50 +02:00
AdrienBouvais
8234591f6e . 2026-04-21 15:14:44 +02:00
AdrienBouvais
7e2652c4ba Renamed Base to Of in BaseQuantities 2026-04-21 15:05:22 +02:00
3 changed files with 146 additions and 278 deletions
Show Stats Expand all files Collapse all files

407
README.md
View File

@ -1,306 +1,173 @@
# zig_units # zig_units
**Compile-time dimensional analysis for Zig.** **Compile-time dimensional analysis and physical quantities for Zig.**
`zig_units` lets you attach physical units to numeric values so that `zig_units` lets you attach physical units to numeric values so that dimension mismatches (like adding distance to time) become **compile errors** rather than silent bugs.
dimension mismatches become *compile errors* rather than silent bugs.
At runtime a `Quantity` is nothing but a single number — zero overhead.
``` At runtime, a `Quantity` is just its underlying numeric value — **zero memory overhead.**
velocity = distance / time → L¹T⁻¹ ✓
force = mass + velocity → compile error: M¹ ≠ L¹T⁻¹ ```zig
const velocity = distance.divBy(time); // Result type: L¹T⁻¹ ✓
const error = mass.add(velocity); // COMPILE ERROR: M¹ != L¹T⁻¹
``` ```
Requires **Zig 0.16** or later. **Requirements:** Zig `0.16.0`
---
## 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 ## Installation
### Add as a Zig dependency ### 1. Add as a Zig dependency
```bash ```bash
zig fetch --save https://github.com/YOUR_USERNAME/zig_units/archive/refs/heads/main.tar.gz 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 ### 2. Configure `build.zig`
`build.zig`:
```zig ```zig
const zig_units = b.dependency("zig_units", .{ const zig_units = b.dependency("zig_units", .{
.target = target, .target = target,
.optimize = optimize, .optimize = optimize,
}); });
my_module.addImport("zig_units", zig_units.module("zig_units")); // Add to your module or executable
``` exe.root_module.addImport("units", zig_units.module("zig_units"));
### Local path (monorepo / development)
```zig
// build.zig.zon
.dependencies = .{
.zig_units = .{ .path = "../zig_units" },
},
``` ```
--- ---
## Quick start ## Quick Start: Using Predefined Quantities
`units.Base` provides a clean way to instantiate common physical types without manually defining dimensions.
```zig ```zig
const units = @import("zig_units"); const std = @import("std");
const Quantity = units.Quantity; const units = @import("units");
const Dims = units.Dimensions;
const Scales = units.Scales;
// Define named unit types pub fn main() !void {
const Meter = Quantity(f32, Dims.init(.{ .L = 1 }), Scales.init(.{})); // Instantiate types for f32 backing
const KiloMeter= Quantity(f32, Dims.init(.{ .L = 1 }), Scales.init(.{ .L = .k })); const Meter = units.Base.Meter.Of(f32);
const Second = Quantity(f32, Dims.init(.{ .T = 1 }), Scales.init(.{})); const Second = units.Base.Second.Of(f32);
const MPerSec = Quantity(f32, Dims.init(.{ .L = 1, .T = -1 }), Scales.init(.{}));
const dist = Meter{ .value = 10.0 };
const time = Second{ .value = 2.0 };
const dist = Meter{ .value = 100.0 }; // Arithmetic is type-safe and creates the correct resulting dimension
const t = Second{ .value = 5.0 }; const vel = dist.divBy(time); // Type is Velocity (L/T)
// Dimension is tracked automatically — vel has type L¹T⁻¹ std.debug.print("Speed: {f}\n", .{vel}); // Output: 5m.s⁻¹
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 ## Defining Custom Quantities
You aren't limited to the built-in library. You can define any physical quantity by specifying its **Dimensions**
(powers of base units) and its **Scale** (SI prefixes).
### 1. Create a custom dimension
Dimensions are defined by 7 base SI units: `L` (Length), `M` (Mass), `T` (Time), `I` (Current), `Tp` (Temp), `N` (Substance), `J` (Intensity).
```zig
const Dims = units.Dimensions;
const Scales = units.Scales;
// Frequency is T⁻¹
const FreqDims = Dims.init(.{ .T = -1 });
// Force is M¹ L¹ T⁻²
const ForceDims = Dims.init(.{ .M = 1, .L = 1, .T = -2 });
```
### 2. Create a custom Type
Combine a numeric type, the dimensions, and a scale.
```zig
const Hertz = units.Quantity(f32, FreqDims, Scales.init(.{}));
// A specialized scale: Millimeters per Second Squared
const MmPerSecSq = units.Quantity(f32,
Dims.init(.{ .L = 1, .T = -2 }),
Scales.init(.{ .L = .m }) // .m = milli
);
```
---
## Unit Conversions
The library handles SI prefixes (`k`, `m`, `u`, `n`, etc.) and time aliases (`.min`, `.hour`) automatically.
When performing arithmetic between different scales, the **finer (smaller) scale wins** to preserve precision.
```zig
const KM = units.Base.Meter.Scaled(f32, Scales.init(.{ .L = .k })); // Kilometers
const M = units.Base.Meter.Of(f32); // Meters
const d1 = KM{ .value = 1.2 }; // 1.2 km
const d2 = M{ .value = 300.0 }; // 300 m
const total = d1.add(d2); // Result is 1500.0 (Meters)
const final = total.to(KM); // Explicitly convert back to KM -> 1.5
```
---
## Physical Vectors (Vec3)
Physical quantities often come in 3D vectors (Position, Velocity, Force). Every `Quantity` type has a `.Vec3` alias built-in.
```zig
const Vec3M = units.Base.Meter.Of(f32).Vec3;
const gravity = Vec3M{ .data = .{ 0, -9.81, 0 } };
const pos = Vec3M.initDefault(0); // [0, 0, 0]
// Vectors support standard operations
const length = gravity.length(); // Returns f32: 9.81
const double = gravity.scale(2.0);
```
You can also create a Vector of any length.
Vec3 found in a Quantity is just a convenience.
```zig
const M = units.Base.Meter.Of(f32);
const Vec10M = units.QuantityVec(10, Meter);
const gravity = Vec10M.initDefault(1);
const length = gravity.length(); // Returns f32: 1.0
```
---
## SI Scales Reference
| Prefix | Enum | Factor |
| :--- | :--- | :--- |
| **Kilo** | `.k` | 10³ |
| **Mega** | `.M` | 10⁶ |
| **Giga** | `.G` | 10⁹ |
| **Milli** | `.m` | 10⁻³ |
| **Micro** | `.u` | 10⁻⁶ |
| **Minute**| `.min` | 60 |
| **Hour** | `.hour`| 3,600 |
---
## API Summary
### `Quantity(T, dims, scales)` ### `Quantity(T, dims, scales)`
- `.add(rhs)` / `.sub(rhs)`: Automatic scaling, requires same dimensions.
| Member | Kind | Description | - `.mulBy(rhs)` / `.divBy(rhs)`: Composes dimensions (e.g., $L \times L = L^2$).
|---|---|---| - `.scale(scalar)`: Multiply by a raw number (preserves dimensions).
| `value` | field | The raw numeric value | - `.to(OtherType)`: Safely convert between scales of the same dimension.
| `ValueType` | comptime | Alias for `T` | - `.vec3()`: Create a 3D vector from a scalar.
| `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` ### `Dimensions`
- `L`: Length (m)
- `M`: Mass (g)
- `T`: Time (s)
- `I`: Current (A)
- `Tp`: Temperature (K)
- `N`: Amount (mol)
- `J`: Intensity (cd)
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.

16
src/BaseQuantities.zig
View File

@ -13,7 +13,7 @@ pub fn QtyNamespace(comptime d: anytype) type {
/// Creates a Quantity of this dimension using default scales. /// Creates a Quantity of this dimension using default scales.
/// Example: const V = Quantities.Velocity.Base(f32); /// Example: const V = Quantities.Velocity.Base(f32);
pub fn Base(comptime T: type) type { pub fn Of(comptime T: type) type {
return Quantity(T, dims, Scales.init(.{})); return Quantity(T, dims, Scales.init(.{}));
} }
@ -95,7 +95,7 @@ pub const SurfaceTension = QtyNamespace(.{ .M = 1, .T = -2 }); // Corrected from
test "BaseQuantities - Core dimensions instantiation" { test "BaseQuantities - Core dimensions instantiation" {
// Basic types via generic wrappers // Basic types via generic wrappers
const M = Meter.Base(f32); const M = Meter.Of(f32);
const distance = M{ .value = 100.0 }; const distance = M{ .value = 100.0 };
try std.testing.expectEqual(100.0, distance.value); try std.testing.expectEqual(100.0, distance.value);
try std.testing.expectEqual(1, M.dims.get(.L)); try std.testing.expectEqual(1, M.dims.get(.L));
@ -110,8 +110,8 @@ test "BaseQuantities - Core dimensions instantiation" {
} }
test "BaseQuantities - Kinematics equations" { test "BaseQuantities - Kinematics equations" {
const d = Meter.Base(f32){ .value = 50.0 }; const d = Meter.Of(f32){ .value = 50.0 };
const t = Second.Base(f32){ .value = 2.0 }; const t = Second.Of(f32){ .value = 2.0 };
// Velocity = Distance / Time // Velocity = Distance / Time
const v = d.divBy(t); const v = d.divBy(t);
@ -128,7 +128,7 @@ test "BaseQuantities - Dynamics (Force and Work)" {
// 10 kg // 10 kg
const m = Gramm.Scaled(f32, Scales.init(.{ .M = .k })){ .value = 10.0 }; const m = Gramm.Scaled(f32, Scales.init(.{ .M = .k })){ .value = 10.0 };
// 9.8 m/s^2 // 9.8 m/s^2
const a = Acceleration.Base(f32){ .value = 9.8 }; const a = Acceleration.Of(f32){ .value = 9.8 };
// Force = mass * acceleration // Force = mass * acceleration
const f = m.mulBy(a); const f = m.mulBy(a);
@ -136,15 +136,15 @@ test "BaseQuantities - Dynamics (Force and Work)" {
try std.testing.expect(Force.dims.eql(@TypeOf(f).dims)); try std.testing.expect(Force.dims.eql(@TypeOf(f).dims));
// Energy (Work) = Force * distance // Energy (Work) = Force * distance
const distance = Meter.Base(f32){ .value = 5.0 }; const distance = Meter.Of(f32){ .value = 5.0 };
const energy = f.mulBy(distance); const energy = f.mulBy(distance);
try std.testing.expectEqual(490000, energy.value); try std.testing.expectEqual(490000, energy.value);
try std.testing.expect(Energy.dims.eql(@TypeOf(energy).dims)); try std.testing.expect(Energy.dims.eql(@TypeOf(energy).dims));
} }
test "BaseQuantities - Electric combinations" { test "BaseQuantities - Electric combinations" {
const current = ElectricCurrent.Base(f32){ .value = 2.0 }; // 2 A const current = ElectricCurrent.Of(f32){ .value = 2.0 }; // 2 A
const time = Second.Base(f32){ .value = 3.0 }; // 3 s const time = Second.Of(f32){ .value = 3.0 }; // 3 s
// Charge = Current * time // Charge = Current * time
const charge = current.mulBy(time); const charge = current.mulBy(time);

1
src/main.zig
View File

@ -14,3 +14,4 @@ test {
_ = @import("BaseQuantities.zig"); _ = @import("BaseQuantities.zig");
_ = @import("helper.zig"); _ = @import("helper.zig");
} }