Better README.zig

README.md

@@ -1,306 +1,173 @@
 # 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
 
-### Add as a Zig dependency
+### 1. 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
+### 2. Configure `build.zig`
-`build.zig`:
-
 ```zig
 const zig_units = b.dependency("zig_units", .{
-    .target  = target,
+    .target = target,
     .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
-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 = 100.0 };
+    const dist = Meter{ .value = 10.0 };
-const t    = Second{ .value = 5.0 };
+    const time = Second{ .value = 2.0 };
 
-// Dimension is tracked automatically — vel has type L¹T⁻¹
+    // Arithmetic is type-safe and creates the correct resulting dimension
-const vel = dist.divBy(t);
+    const vel = dist.divBy(time); // Type is Velocity (L/T)
     
-// Convert to an explicit type (same dims required, compile error otherwise)
+    std.debug.print("Speed: {f}\n", .{vel}); // Output: 5m.s⁻¹
-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)`
-
+- `.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`
+- `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.

src/BaseQuantities.zig

@@ -13,7 +13,7 @@ pub fn QtyNamespace(comptime d: anytype) type {
 
         /// Creates a Quantity of this dimension using default scales.
         /// 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(.{}));
         }
 
@@ -95,7 +95,7 @@ pub const SurfaceTension = QtyNamespace(.{ .M = 1, .T = -2 }); // Corrected from
 
 test "BaseQuantities - Core dimensions instantiation" {
     // Basic types via generic wrappers
-    const M = Meter.Base(f32);
+    const M = Meter.Of(f32);
     const distance = M{ .value = 100.0 };
     try std.testing.expectEqual(100.0, distance.value);
     try std.testing.expectEqual(1, M.dims.get(.L));
@@ -110,8 +110,8 @@ test "BaseQuantities - Core dimensions instantiation" {
 }
 
 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
     const v = d.divBy(t);
@@ -128,7 +128,7 @@ test "BaseQuantities - Dynamics (Force and Work)" {
     // 10 kg
     const m = Gramm.Scaled(f32, Scales.init(.{ .M = .k })){ .value = 10.0 };
     // 9.8 m/s^2
-    const a = Acceleration.Base(f32){ .value = 9.8 };
+    const a = Acceleration.Of(f32){ .value = 9.8 };
 
     // Force = mass * acceleration
     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));
 
     // 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);
     try std.testing.expectEqual(490000, energy.value);
     try std.testing.expect(Energy.dims.eql(@TypeOf(energy).dims));
 }
 
 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
     const charge = current.mulBy(time);

src/main.zig

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