zmath: function naming convention or member functions

[Avokadoen]

It can be a bit cumbersome to find the functions you want when using zmath since the function names are not necessarily tied to the type it relates to and are not members of said type. The zmath.zig file is 4k lines of code and tests are intertwined which makes it harder to get an overview of what is there.

As an example, the identity function for a Mat is called identity while for quaternions it is called qidentity.

In this case I do think that it would make more sense to have midentity & qidentity, mat_identity & quat_identity or Mat.identity & Quat.identity. I do understand that the library does try to not avoid unnecessary abstractions. I think zmath can be improved so that it is easier to quickly find the functions that operate on certain types while keeping abstractions at a minimum. Splitting operations that tie to a certain construct i.e Vec, Mat and Quat (and a common.zig for f32xX + common functions) into struct files could also solve this problem.

Keep in mind that this problem should not be high priority and zmath is very usable as is, but I think this discussion can make it even more usable 👀

[michal-z]

Note that we can't use member functions in case of vectors and quaternions because math operators would stop working. For consistency we also don't use members in case of matrices.

We could use namespaces though:

pub const Vec = @Vector(4, f32);
pub const Quat = @Vector(4, f32);

pub const  vec = struct {
    pub fn dot3(...);
    // ...
};

pub const quat = struct {
    pub fn identity(...);
};

The loose idea was to name functions according to a mathematical operations they perform (similar to HLSL).

Personally I like to put tests right after implementation and I think that documentation is better for discoverability (this is why I put a list of functions at the beginning of the file).

I think that we could try the approach with namespaces. I see some problems though. For example, where to put mul(vec, mat) function - to a mat namespace or to a vec namespace?

[Avokadoen]

What about having a op namespace for mul and potentially others?

I agree the test placement is as much of a pro as it is a con

[michal-z]

Do you mean something like below?

pub const mul = struct {
   pub fn vecMat(...);
   pub fn scalarMat(...);
}

[Avokadoen]

That was not what I meant, but I like that idea more. I was trying to say that maybe just dump all ops that does not fit in a specific type in a op namespace

[glitch-cake]

I think that we could try the approach with namespaces. I see some problems though. For example, where to put mul(vec, mat) function - to a mat namespace or to a vec namespace?

Could functions be placed based on their return type? That jumps out to me as being a sensible option and what I would generally expect. e.g. mul(vec, mat) returns mat and thus is in the mat namespace.