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

Added some doc comments

Browse Source
This commit is contained in:
adrien 2026-04-22 10:58:14 +02:00
parent ec05b60fc3
commit 86841318f2
4 changed files with 54 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
src/Dimensions.zig
View File

@ -29,10 +29,16 @@ pub const Dimension = enum {
}
};
// --------- Dimensions struct ---------
/// Holds the exponent of each SI base dimension for a given quantity (e.g. velocity = L¹T⁻¹).
/// All values are `comptime_int` — no runtime storage.
const Self = @This();
data: std.EnumArray(Dimension, comptime_int),
/// Create a `Dimensions` from an anonymous struct literal, e.g. `.{ .L = 1, .T = -1 }`.
/// Unspecified dimensions default to 0.
pub fn init(comptime init_val: anytype) Self {
var s = Self{ .data = std.EnumArray(Dimension, comptime_int).initFill(0) };
inline for (std.meta.fields(@TypeOf(init_val))) |f|
@ -52,6 +58,7 @@ pub fn set(comptime self: *Self, comptime key: Dimension, comptime val: i8) void
self.data.set(key, val);
}
/// Add exponents component-wise. Used internally by `mulBy`.
pub fn add(comptime a: Self, comptime b: Self) Self {
var result = Self.initFill(0);
for (std.enums.values(Dimension)) |d|
@ -59,6 +66,7 @@ pub fn add(comptime a: Self, comptime b: Self) Self {
return result;
}
/// Subtract exponents component-wise. Used internally by `divBy`.
pub fn sub(comptime a: Self, comptime b: Self) Self {
@setEvalBranchQuota(10_000);
var result = Self.initFill(0);
@ -67,6 +75,7 @@ pub fn sub(comptime a: Self, comptime b: Self) Self {
return result;
}
/// Returns true if every dimension exponent is equal. Used to enforce type compatibility in `add`, `sub`, `to`.
pub fn eql(comptime a: Self, comptime b: Self) bool {
inline for (std.enums.values(Dimension)) |d|
if (a.get(d) != b.get(d)) return false;

27
src/Scalar.zig
View File

@ -18,18 +18,29 @@ const Dimension = Dimensions.Dimension;
// - pow: Scalar power another
// - log: Scalar log another
/// A dimensioned scalar value. `T` is the numeric type, `d` the dimension exponents, `s` the SI scales.
/// All dimension and unit tracking is resolved at comptime — zero runtime overhead.
pub fn Scalar(comptime T: type, comptime d: Dimensions, comptime s: Scales) type {
@setEvalBranchQuota(10_000_000);
return struct {
value: T,
const Self = @This();
/// Type of Vector(3, Self)
pub const Vec3: type = Vector(3, Self);
/// Type of underline value, mostly use for Vector
pub const ValueType: type = T;
/// Dimensions of this type
pub const dims: Dimensions = d;
/// Scales of this type
pub const scales = s;
/// Add two quantities. Dimensions must match — compile error otherwise.
/// Scales are auto-resolved to the finer of the two.
pub inline fn add(self: Self, rhs: anytype) Scalar(
T,
dims,
@ -47,6 +58,8 @@ pub fn Scalar(comptime T: type, comptime d: Dimensions, comptime s: Scales) type
return .{ .value = lhs_val + rhs_val };
}
/// Subtract two quantities. Dimensions must match — compile error otherwise.
/// Scales are auto-resolved to the finer of the two.
pub inline fn sub(self: Self, rhs: anytype) Scalar(
T,
dims,
@ -64,6 +77,7 @@ pub fn Scalar(comptime T: type, comptime d: Dimensions, comptime s: Scales) type
return .{ .value = lhs_val - rhs_val };
}
/// Multiply two quantities. Dimension exponents are summed: `L¹ * T⁻¹ → L¹T⁻¹`.
pub inline fn mulBy(self: Self, rhs: anytype) Scalar(
T,
dims.add(@TypeOf(rhs).dims),
@ -80,6 +94,8 @@ pub fn Scalar(comptime T: type, comptime d: Dimensions, comptime s: Scales) type
return .{ .value = lhs_val * rhs_val };
}
/// Divide two quantities. Dimension exponents are subtracted: `L¹ / T¹ → L¹T⁻¹`.
/// Integer types use truncating division.
pub inline fn divBy(self: Self, rhs: anytype) Scalar(
T,
dims.sub(@TypeOf(rhs).dims),
@ -97,6 +113,8 @@ pub fn Scalar(comptime T: type, comptime d: Dimensions, comptime s: Scales) type
}
}
/// Convert to a compatible unit type. The scale ratio is computed at comptime.
/// Compile error if dimensions don't match.
pub inline fn to(self: Self, comptime Dest: type) Dest {
if (comptime !dims.eql(Dest.dims))
@compileError("Dimension mismatch in to: " ++ dims.str() ++ " vs " ++ Dest.dims.str());
@ -138,10 +156,17 @@ pub fn Scalar(comptime T: type, comptime d: Dimensions, comptime s: Scales) type
}
}
pub fn Vec(self: Self, comptime len: comptime_int) Vector(len, Self) {
/// Return a `Vector(len, Self)` type.
pub fn Vec(_: Self, comptime len: comptime_int) type {
return Vector(len, Self);
}
/// Return a `Vector(len, Self)` with all components set to this value.
pub fn vec(self: Self, comptime len: comptime_int) Vector(len, Self) {
return Vector(len, Self).initDefault(self.value);
}
/// Shorthand for `Vec(3)` — wrap this value into a 3-component vector.
pub fn vec3(self: Self) Vec3 {
return Vec3.initDefault(self.value);
}

8
src/Scales.zig
View File

@ -3,6 +3,9 @@ const hlp = @import("helper.zig");
const Dimensions = @import("Dimensions.zig");
const Dimension = @import("Dimensions.zig").Dimension;
/// SI prefix (pico…peta) plus time-unit aliases (min, hour, year).
/// The integer value encodes the exponent for SI prefixes (e.g. `k = 3` → 10³),
/// and the literal factor for time units (e.g. `hour = 3600`).
pub const UnitScale = enum(isize) {
P = 15,
T = 12,
@ -54,10 +57,13 @@ pub const UnitScale = enum(isize) {
}
};
/// Maps each SI base dimension to its `UnitScale`. Stored and resolved entirely at comptime.
const Scales = @This();
data: std.EnumArray(Dimension, UnitScale),
/// Create a `Scales` from an anonymous struct literal, e.g. `.{ .L = .k, .T = .hour }`.
/// Unspecified dimensions default to `.none` (factor 1).
pub fn init(comptime init_val: anytype) Scales {
comptime var s = Scales{ .data = std.EnumArray(Dimension, UnitScale).initFill(.none) };
inline for (std.meta.fields(@TypeOf(init_val))) |f| {
@ -81,6 +87,8 @@ pub fn set(comptime self: *Scales, comptime key: Dimension, comptime val: UnitSc
comptime self.data.set(key, val);
}
/// Compute the combined scale factor for a given dimension signature.
/// Each dimension's prefix is raised to its exponent and multiplied together.
pub inline fn getFactor(comptime s: Scales, comptime d: Dimensions) comptime_float {
comptime var factor: f64 = 1.0;
inline for (std.enums.values(Dimension)) |dim| {

12
src/Vector.zig
View File

@ -7,6 +7,7 @@ const UnitScale = Scales.UnitScale;
const Dimensions = @import("Dimensions.zig");
const Dimension = Dimensions.Dimension;
/// A fixed-size array of `len` elements sharing the same dimension and scale as scalar type `Q`.
pub fn Vector(comptime len: usize, comptime Q: type) type {
const T = Q.ValueType;
const d: Dimensions = Q.dims;
@ -30,6 +31,7 @@ pub fn Vector(comptime len: usize, comptime Q: type) type {
return .{ .data = data };
}
/// Element-wise addition. Dimensions must match; scales resolve to the finer of the two.
pub inline fn add(self: Self, rhs: anytype) Vector(len, Scalar(
T,
dims,
@ -43,7 +45,7 @@ pub fn Vector(comptime len: usize, comptime Q: type) type {
}
return res;
}
/// Element-wise subtraction. Dimensions must match; scales resolve to the finer of the two.
pub inline fn sub(self: Self, rhs: anytype) Vector(len, Scalar(
T,
dims,
@ -58,6 +60,7 @@ pub fn Vector(comptime len: usize, comptime Q: type) type {
return res;
}
/// Element-wise division. Dimension exponents are subtracted per component.
pub inline fn divBy(
self: Self,
rhs: anytype,
@ -75,6 +78,7 @@ pub fn Vector(comptime len: usize, comptime Q: type) type {
return res;
}
/// Element-wise multiplication. Dimension exponents are summed per component.
pub inline fn mulBy(
self: Self,
rhs: anytype,
@ -92,6 +96,7 @@ pub fn Vector(comptime len: usize, comptime Q: type) type {
return res;
}
/// Divide every component by a single scalar. Dimensions are subtracted (e.g. position / time → velocity).
pub inline fn divByScalar(
self: Self,
scalar: anytype,
@ -108,6 +113,7 @@ pub fn Vector(comptime len: usize, comptime Q: type) type {
return res;
}
/// Multiply every component by a single scalar. Dimensions are summed.
pub inline fn mulByScalar(
self: Self,
scalar: anytype,
@ -124,6 +130,7 @@ pub fn Vector(comptime len: usize, comptime Q: type) type {
return res;
}
/// Negate all components. Dimensions are preserved.
pub fn negate(self: Self) Self {
var res: Self = undefined;
inline for (self.data, 0..) |v, i|
@ -131,6 +138,7 @@ pub fn Vector(comptime len: usize, comptime Q: type) type {
return res;
}
/// Convert all components to a compatible scalar type. Compile error on dimension mismatch.
pub inline fn to(self: Self, comptime DestQ: type) Vector(len, DestQ) {
var res: Vector(len, DestQ) = undefined;
inline for (self.data, 0..) |v, i|
@ -138,6 +146,7 @@ pub fn Vector(comptime len: usize, comptime Q: type) type {
return res;
}
/// Sum of squared components. Cheaper than `length` — use for comparisons.
pub inline fn lengthSqr(self: Self) T {
var sum: T = 0;
inline for (self.data) |v|
@ -145,6 +154,7 @@ pub fn Vector(comptime len: usize, comptime Q: type) type {
return sum;
}
/// Euclidean length. Integer types use integer sqrt (truncated).
pub inline fn length(self: Self) T {
const len_sq = self.lengthSqr();