2026-10-03\n·\nzig,\ntraits,\npolymorphism,\nabstraction
\nI have had more time recently to write code in Zig, and it has been good for my\nsoul. I wanted to share some insights I have arrived at regarding abstractions\nin Zig, including some techniques that I have found useful but not seen employed\nmore broadly.
\nConsiderable[1] ink[2] has[3] been[4]\nspilled[5] on Zig Interfaces, and justifiably so. While not a language\nfeature, interfaces are the de-facto way of implementing runtime polymorphism in\nZig. Yet[6] more[7] has been said about zig's comptime, and\nhow it may be leveraged to avoid the performance woes of dynamic dispatch and\nwrite slick, data-oriented code.
\nTo put it briefly, polymorphism in Zig is conventionally obtained in one of two\nways:
\nDynamic Interfaces: Use opaque pointers, virtual tables, and dynamic
dispatch to achieve runtime polymorphism.
Comptime Duck Typing: Use type reflection, switch statements, and
monomorphism at compile time to achieve static polymorhpism.
This state of affairs has proven to be quite effective so far, but it is not\nwithout its tradeoffs.
\nInterfaces offer the sort of type contracts that we are used to from other\nlanguages. A function that accepts an interface has a guarantee of its method\nsignatures, but not its implementation. However because interfaces are, by\ndesign, modular at runtime, they also introduce a hard barrier for the compiler\nand thus a performance overhead. There is enough indirection that it often\ncannot effectively apply the optimizations that it would to monomorphic code.
\nFor cases of performance critical code, Zig code typically relies on comptime\nduck typing. A function argument is either anytype or parameterized by a type\nargument T, and the function implementation will either perform compile-time\nreflection or make assumptions about the type's methods that can be checked at\ncompile-time. Implementations can then be monomorphised, similar to C++\ntemplating or C macros. This is slightly more safe than runtime duck typing,\nbecause any interface violations will be caught at compile time rather than\nruntime, but the caller and callee must still be careful to document and follow\nthe contract of what types may be passed.
If you are coming from another strongly typed language, you would be forgiven\nfor finding this arrangement rather simplistic. This is perhaps by design\n-- Zig aims to be simple. However if you have grown accustomed to Rust's traits\nor Haskell typeclasses, there appears to be no ready equivalent in Zig.
\nI will argue that, with a little adaptation, it is perfectly possible to express\nsimilar abstractions over types in Zig userland. I would propose a new\nconvention for defining compile-time type contracts as Traits in Zig. It\ndoesn't require any libraries or machinery - in fact if fits remarkably well\ninto vanilla Zig. It is inspired by the functional programming world in general,\nand OCaml in particular.
\n\nDefinition: a Trait is a compile-time struct which contains related\nfunctions over a given type. [8]
So as not to bury the lead, let me begin with a brief example of how we might\ndefine a trait for folding (reducing) on a type.
\n/// T forms a Reducer under an empty value and a combine operation\nfn Reducer(T: type) type {\n return struct {\n empty: T,\n combine: fn (T, T) T,\n\n fn reduce(self: @This(), xs: []const T) T {\n var accum = self.empty;\n for (xs) |x| accum = self.combine(accum, x);\n return accum;\n }\n };\n}\n\n/// i32 forms a sum reducer under 0 and addition\nconst sum_trait = impl(Reducer(i32), struct {\n pub const empty = 0;\n pub fn combine(x: T, y: T) T { return x + y; }\n});\n\n/// i32 forms a product reducer under 1 and multiplication\nconst product_trait = impl(Reducer(i32), struct {\n pub const empty = 1;\n pub fn combine(x: T, y: T) T { return x * y; }\n});\n\nexport fn run(buf: [*c]i32, n: usize) i32 {\n const sum = sum_trait.reduce(buf[0..n]);\n const product = product_trait.reduce(buf[0..n]);\n return sum + product;\n}Ugh. Isn't that just buttery smooth?[9] The contract is clear, LSP\nautocompletion picks it up, the compiler even knows to inline it and unroll the\nloop.
\nTraits are just bags of functions and types that tell the receiving function how\nto execute subtasks that it's not responsible for defining. They behave a lot\nlike vtables, except that they are evaluated at comptime rather than runtime.
\nTo justify traits, let's take a tour through Zig polymorphism with a common\nmotivating example: arithmetic operations. I've seen a few complaints over the\nyears about how awkward is it to do math in Zig over user-defined types. In its\npursuit of explicit control flow, Zig has eschewed operator overloading, and\nthis can be jarring if you're coming from other typed languages.
\nLet's imagine we have some user-defined types like Rational and Complex, and\nwe want to define their basic arithmentic operations. We would probably end up\nwith something like the following.
const Rational = struct {\n numerator: i32,\n denominator: i32,\n\n fn add(lhs: Rational, rhs: Rational) Rational {...}\n fn sub(lhs: Rational, rhs: Rational) Rational {...}\n fn mul(lhs: Rational, rhs: Rational) Rational {...}\n fn div(lhs: Rational, rhs: Rational) Rational {...}\n};\n\nconst Complex = struct {\n real: f32,\n imaginary: f32,\n\n fn add(lhs: Complex, rhs: Complex) Complex {...}\n fn sub(lhs: Complex, rhs: Complex) Complex {...}\n fn mul(lhs: Complex, rhs: Complex) Complex {...}\n fn div(lhs: Complex, rhs: Complex) Complex {...}\n};For the sake of having something to do with them, let's say that we want to\ncompute the\nMöbius transformation:\n(a * x + b) / (c * x + d), which is useful for complex numbers as well as\nrationals. To keep things simple, we'll assume that all arguments to the\nfunction are of the same type.
If we were to implement the Mobius transformation naively, we could just use\nbuilt-in operators.
\nfn mobius(T: type, x: T, a: T, b: T, c: T, d: T) T {\n return (a * x + b) / (c * x + d);\n}This would work fine, as long as the inputs were all floats of the same type.\nDivision would break for integers, and of course it wouldn't work with our\nuser-defined types, but it's a starting point.
\nWe could of course notice that both of our user-defined types have arithmetic\nfunctions with matching names and similar signatures, which would lend\nthemselves to duck typing as well.
\nfn mobius(T: type, x: T, a: T, b: T, c: T, d: T) T {\n const numerator = a.mul(x).add(b);\n const denominator = c.mul(x).add(d);\n return numerator.div(denominator);\n}This will work for our user-defined types, but obviously not with Zig's\nprimitive types. We would have to wrap those in our own user-defined types with\ntheir own functions. More troublingly, this sort of ties us to a sort of\nobject-oriented pattern: the de-facto way to obey this abstraction contract is\nto define methods on the struct.
\nThe good news is that it's all monomorphised at compile time, allowing the\ncompiler to simplify and inline these function calls.
\nIf we wanted this to work dynamically at runtime, we could perhaps declare a\nNum interface that uses a VTable and opaque pointer to dynamically dispatch\nthese math operations.
const Num = struct {\n value: [32]u8,\n vtable: *const VTable,\n\n const VTable = struct {\n add: *const fn([*]u8, [*]u8) Num,\n sub: *const fn([*]u8, [*]u8) Num,\n mul: *const fn([*]u8, [*]u8) Num,\n div: *const fn([*]u8, [*]u8) Num,\n };\n\n fn add(lhs: Num, rhs: Num) Num { ... }\n fn sub(lhs: Num, rhs: Num) Num { ... }\n fn mul(lhs: Num, rhs: Num) Num { ... }\n fn div(lhs: Num, rhs: Num) Num { ... }\n\n fn mobius(x: Num, a: Num, b: Num, c: Num, d: Num) {\n const numerator = a.mul(x).add(b);\n const denominator = c.mul(x).add(d);\n return numerator.div(denominator);\n }\n}We would then need to wire up Complex and Rational to expose\nfn num(self: *Self) Num (or some such) that wraps our arithmentic functions,\nwhich is a little too tedious to reproduce here, but it would work fine on the\nhappy path. You would of course need to be a bit careful: there's nothing\nstopping you from mixing complex and rational numbers in your function calls,\nand this would lead to undefined behavior. You could probably add some saftey\nchecks with a bit of overengineering, but we won't get into that here.
Not only is this clunkier than comptime duck typing, it will also be slower. We\nare effectively demanding dynamic dispatch whenever we want to do a math\noperation, which will trip up the compiler and have a significant performance\nimpact if we're doing a lot of math.
\nWhen we define the mobius function, we really want to say "I don't know what\ntype I'm dealing with, but it needs to have arithmetic operations." In this sort\nof case, I think it makes the most sense to just pass the functions it needs to\nuse at compile-time. This would remove any ambiguity, at the cost of being\nrather explicit.
\nfn mobius(\n comptime T: type,\n comptime add: fn (T, T) T,\n comptime mul: fn (T, T) T,\n comptime div: fn (T, T) T,\n x: T,\n a: T,\n b: T,\n c: T,\n d: T,\n) T {\n const numerator = add(mul(a, x), b);\n const denominator = add(mul(c, x), d);\n return div(numerator, denominator);\n}This is effectively compile-time dependency injection at a really fine-grained\nlevel. The signature is rather verbose, but there's actually a lot less\nboilerplate to write for Complex or Rational compared to runtime interfaces.
mobius(Complex, Complex.add, Complex.mul, Complex.div, x, a, b, c, d);\nmobius(Real, Real.add, Real.mul, Real.div, x, a, b, c, d);From here, it's not a huge leap to traits. We're effectively just cleaning up\nthe function signature by gathering together the arithmetic functions into one\nstruct.[10]
\nfn Num(T: type) type {\n return struct {\n add: fn (T, T) T,\n sub: fn (T, T) T,\n mul: fn (T, T) T,\n div: fn (T, T) T,\n };\n}\n\nfn mobius(T: type, num: Num(T), x: T, a: T, b: T, c: T, d: T) T {\n const numerator = num.add(num.mul(a, x), b);\n const denominator = num.add(num.mul(c, x), d);\n return num.div(numerator, denominator);\n}From here, I usually just declare the trait implementation as part of my type.
\nconst Complex = struct {\n // fields...\n const num = Num(Complex) { .add = add, .sub = sub, .mul = mul, .div = div };\n // functions (add, sub, mul, div...)\n};\n\nmobius(Complex, Complex.num, x, a, b, c, d);What I really like about this approach is how flexible it is, while remaining\nvery clear about the contract between the function and type. For example,\nimagine that we wanted to extend our definition of Num to the primitive types\nlike i32 and f32. There are a bunch of ways we could do this, but I would\nprobably just define a function that produces something appropriate for integer\nand float types.
fn builtinNum(T: type) Num(T) {\n const inner = struct {\n fn add(lhs: T, rhs: T) T { return lhs + rhs; }\n fn sub(lhs: T, rhs: T) T { return lhs - rhs; }\n fn mul(lhs: T, rhs: T) T { return lhs * rhs; }\n };\n const div = switch (@typeInfo(T)) {\n .int, .comptime_int => struct {\n fn div(lhs: T, rhs: T) T { return @divTrunc(lhs, rhs); }\n }.div,\n .float, .comptime_float => struct {\n fn div(lhs: T, rhs: T) T { return lhs / rhs; }\n }.div,\n else => @compileError("unsupported type: " ++ @typeName(T)),\n };\n return .{ .add = inner.add, .sub = inner.sub, .mul = inner.mul, .div = div };\n}\n\nmobius(f32, builtinNum(f32), x, a, b, c, d);Traits are also transparent to the compiler, which will happily monomorphize and\ninline these functions. I prefer this over runtime polymorphism most of the\ntime, especially in hot loops or for library functions that are unopinionated on\ndata layout.
\nYou'll notice that traits have to be explicitly conditioned on a known type.\nUnlike interfaces, there's no way to say "give me a number, I don't care what\nkind." For some applications, it would be nice if we could have an associated\ntype.
\nfn Iter(Elem: type) type {\n return struct {\n T: type,\n next: fn (T) ?Elem,\n };\n}Unfortunately, the above isn't valid Zig, and it's unclear how that would even\nwork at a language level. Instead, traits insist that the types they are\noperating on are known in advance.
\nfn Iter(T: type, Elem: type) type {\n return struct {\n next: fn (T) ?Elem,\n };\n}I have not yet found an ergonomic way around this. Traits do not play very\nwell with type erasure.
\nBefore proceeding, I want to introduce some small helper functions that have\nstreamlined how I work with traits.
\nIf you adopt traits as a programming pattern and convention, you'll quickly end\nup defining functions and passing them around. You will have already noticed\nabove that I define a lot of throwaway inner struct types, just so that I can\npull functions out of them. This has led to the following convenience function\nfor declaring trait implementations, which removes some of the boilerplate.
\npub fn impl(comptime Trait: type, comptime Impl: type) Trait {\n comptime {\n var result: Trait = undefined;\n for (@typeInfo(Trait).@"struct".field_names) |field_name| {\n @field(result, field_name) = @field(Impl, field_name);\n }\n return result;\n }\n}I use this all over the place to derive trait implementations from anonymous\nstructs. For example, we could use it to rewrite builtinNum to be a little\nmore concise and functional. Note that the declarations need to be public for\nthe type reflection to work.
fn builtinNum(T: type) Num(T) {\n return impl(Num(T), struct {\n pub fn add(lhs: T, rhs: T) T { return lhs + rhs; }\n pub fn sub(lhs: T, rhs: T) T { return lhs - rhs; }\n pub fn mul(lhs: T, rhs: T) T { return lhs * rhs; }\n\n pub const div = switch (@typeInfo(T)) {\n .int, .comptime_int => struct {\n fn div(lhs: T, rhs: T) T { return @divTrunc(lhs, rhs); }\n }.div,\n .float, .comptime_float => struct {\n fn div(lhs: T, rhs: T) T { return lhs / rhs; }\n }.div,\n else => @compileError("unsupported type: " ++ @typeName(T)),\n };\n });\n}Most of the time, I don't mind passing trait implementations around explicitly.\nI've gotten into the habit, and just don't find it to be that big of a deal.\nTrait functors make it pretty easy to reduce the boilerplate, and I like having\nexplicit control over how things are implemented.
\nHowever when I'm dealing with my own structs, 99% of the time the trait\nimplementation I'm looking for is going to be declared as a const on the struct\nitself. I use the function below to to easily retrieve or construct the most\ncommon cases.
\nfn getTrait(Trait: type, Impl: type) Trait {\n comptime {\n // try to find the trait declared explicitly as a member\n for (@typeInfo(Impl).@"struct".decl_names) |decl_name| {\n if (@TypeOf(@field(Impl, decl_name)) == Trait) {\n return @field(Impl, decl_name);\n }\n }\n // otherwise throw an error\n @compileError("trait " ++ @typeName(Trait) ++ " not found on " ++ @typeName(Impl));\n }\n}This is basically equivalent to saying "eh, it's duck typed. figure it out".\nJust because we are explicit, doesn't mean that we can't be lazy. If we want\nto take this full circle back to duck typing, we can even define trait functors\nthat rely on getTrait to extract traits from the types they pass.
fn duckMobius(T: type) fn(T, T, T, T) T {\n comptime {\n const num = getTrait(Num(T), T);\n return makeMobius(T, num);\n }\n}With some helpers defined, let's return to the Num example.
Traits in Zig resemble traits in Rust, typeclasses in Haskell, or modules in\nOcaml. In Rust or Haskell, they would be resolved from a global registry managed\nby the compiler. This can feel very convenient, but it violates Zig's principle\nof explicit control flow. Rust and Haskell can require a fair bit of hunting for\nwhere a trait is defined, especially when something's wrong and the LSP isn't\nresolving it properly. It can also be a contributor to long compile times.\nResolving a generic trait in these languages is often equivalent to evaluating a\nproof, and that can take time.
\nOcaml modules, however, work quite a bit like Zig traits: modules are\nfirst-class objects, and they are passed as arguments to the functions that\nconsume them. There is no inference of what modules apply to a type - you locate\nthem and pass them explicitly. If we were to define Num as a module, it might\nlook something like the following.
(* signature *)\nmodule type NUM = sig\n type t\n val add : t -> t -> t\n val sub : t -> t -> t\n val mul : t -> t -> t\n val div : t -> t -> t\nend\n\n(* Implementation on float *)\nmodule Float : NUM with type t = float = struct\n type t = float\n let add = ( +. )\n let sub = ( -. )\n let mul = ( *. )\n let div = ( /. )\nend\n\n(* function *)\nlet mobius (type a) (module N : NUM with type t = a) x a b c d =\n let numerator = N.add (N.mul a x) b in\n let denominator = N.add (N.mul c x) d in\n N.div numerator denominator\n\n(* Usage *)\nlet res = mobius (module Float) x a b c d)Because modules in Ocaml are first-class values, they can actually take it a\nstep further. Rather than defining mobius as written above, it is common in\nOcaml to make use of "module functors", which are simply functions that take\nmodules as arguments and return new modules. If we wanted to define mobius in\nterms of a given numeric type, we might instead write it:
(* MakeMobius receives a NUM module and returns a new module with mobius function *)\nmodule MakeMobius (N : NUM) = struct\n let mobius x a b c d =\n let numerator = N.add (N.mul a x) b in\n let denominator = N.add (N.mul c x) d in\n N.div numerator denominator\nend\n\n(* usage *)\nmodule FloatMobius = MakeMobius (Float)\nlet res = FloatMobius.mobius x a b c dThis is effectively currying: we are applying the module arguments now, and the\nvalue arguments later. However it derives a mobius function that doesn't need to\nbe taking a bunch of type arguments all the time, and that module can in turn be\nused in later constructions. This translates straightforwardly to Zig. If we\nwanted to adhere strictly to the traits pattern, it might look like the\nfollowing.
\nfn Mobius(T: type) type {\n return struct {\n mobius: fn(T, T, T, T, T) T,\n };\n}\nfn makeMobius(T: type, num: Num(T)) Mobius(T) {\n return impl(Mobius(T), struct {\n fn mobius(x: T, a: T, b: T, c: T, d: T) T {\n const numerator = num.add(num.mul(a, x), b);\n const denominator = num.add(num.mul(c, x), d);\n return num.div(numerator, denominator);\n }\n });\n}\nconst complex_mobius = MakeMobius(Complex, Complex.num);\ncomplex_mobius.mobius(x, a, b, c, d);This works fine, but I think it's even simpler to move the functor into\nMobius(T):
fn Mobius(T: type) type {\n return struct {\n mobius: fn(T, T, T, T, T) T,\n\n fn make(num: Num(T)) Mobius(T) {\n return impl(Mobius(T), struct {\n fn mobius(x: T, a: T, b: T, c: T, d: T) T {\n const numerator = num.add(num.mul(a, x), b);\n const denominator = num.add(num.mul(c, x), d);\n return num.div(numerator, denominator);\n }\n });\n }\n };\n}\nconst complex_mobius = Mobius(Complex).make(Complex.num);\ncomplex_mobius.mobius(x, a, b, c, d);However for single functions like this, unless I knew it would need to be\nconsumed by another function as a trait, I would probably be tempted to just\nimplement it as a type-curried function rather than a full-blown trait:
\nfn makeMobius(T: type, num: Num(T)) fn(T, T, T, T) T {\n return struct {\n fn mobius(x: T, a: T, b: T, c: T, d: T) T {\n const numerator = num.add(num.mul(a, x), b);\n const denominator = num.add(num.mul(c, x), d);\n return num.div(numerator, denominator);\n }\n }.mobius;\n}\n\nconst complexMobius = makeMobius(Complex, Complex.num);\ncomplexMobius(x, a, b, c, d);The versatility of Zig's comptime makes all of these more or less equivalent to\nthe compiler. It's just a stylistic choice, depending on what the situation\ncalls for.
\nAlso, notice that technically we have already used trait functors when we\ndefined builtinNum. It's not a deep, technical concept. It's just a function\nthat constructs a trait implementation for you.
Having thoroughly introduced traits, let's talk about what we can do with them.
\nIn this section are a few traits that I find myself reaching for with enough\nregularity that I keep a file around containing them. All of these are fairly\nhumdrum (but wildly applicable) abstractions that I lifted wholecloth from\nother languages.
\nI need to convert one type into another all the freaking time. Often there are\nmultiple ways to do this, depending on how you want to interpret the upstream\ntype. I use Into and From to canonicalize methods for converting one type\ninto another.
/// T can be converted into Out\nfn Into(T: type, Out: type) type {\n return struct {\n into: fn(T) Out,\n };\n}\n\n/// T can be derived from In\nfn From(T: type, In: type) type {\n return struct {\n from: fn(In) T,\n };\n}Sometimes, rather than iterating, we need keyed access to a value. The\ncontainer could be a slice or a hash table - we don't care. For this, I use\nIndex.
/// T forms an index over Key and Value\nfn Index(T: type, Key: type, Value: type) type {\n return struct {\n get: fn(T, Key) ?Value,\n };\n}Another common case: we have a function that iterates over a type, but we don't\ncare what sort of iterable data structure we're going to be working with. We\nusually need two traits: one for the Iterable collection, and another for the\nIterator, which keeps track of our progress through the collection.
/// T can be used to iterate over Elem elements of type\nfn Iterator(T: type, Elem: type) type {\n return struct {\n next: fn(*T) ?Elem,\n };\n}\n\n/// T can return an Iter iterator over Elem elements\nfn Iterable(T: Type, Elem: type, Iter: type) type {\n return struct {\n iter: fn(T) IterPair,\n pub const IterPair = struct {impl: Iter, trait: Iterator(Iter, Elem)};\n };\n}You'll notice that this is a little awkward, because we don't usually care what\nthe iterator implementation is. It's probably just a usize index over an array\nor something. It would be nice if we could just define Iterable(T: type, Elem: type). I've chosen to just let it be awkward. It's usually not a big\ndeal.
I really don't want you to walk away from this article thinking "I need to\nconvert all my code to use traits". Traits should not be thought of as a\ntotalizing pattern. The last thing I want is for Zig code to start looking\nlike Rust or Haskell.
\nTraits are a sometimes treat. They are useful for functions that need\nabstractions inside of hot loops, where you know that you want monomorphization\nand static dispatch. They can become legible building blocks for some neat\nmetaprogramming tricks. However most of the time I only reach for them in a\npull-based manner: I have a function where it would be useful to consume a\ntrait, because it's undecided on some implementation detail.
\nUsed improperly, traits can explode the size of your binary and actually make\nit slower. Each function parameterized on comptime parameters gets its own\ntemplated assembly, and if you nest these a few layers deep, it's easy to end\nup with a combinatorial explosion. This can thrash your CPU cache, and\ndepending on the situation, easily be outperformed by dynamic dispatch and\nvtables.
\nTraits are ultimately handy and very powerful. I wish I saw more codebases\nthat made use of them, especially for abstraction inside of hot loops. I like\nthat they are a design pattern more than a language feature, and this gives you\na lot of explicit control over when and how you use them. I was looking for a\nsolution like this for a long time, and I'm glad I found it.
\nI'm sure that other Zig users have stumbled onto this trick, but I have yet to\nsee it in the wild. I think that part of the reason is that it doesn't really\nlend itself to a library. It's more of a convention that you can choose to\nuse or ignore.
\nMy hope is that for someone reading, traits are the right tool for the job.
\nby William Wong ↩
by Joe McKay ↩
Interfaces in Zig by Brad
Cypert ↩
A Practical Guide to Applying Data-Oriented Design
by Andrew Kelley ↩
by Scott Redit ↩
"Traits" are directly inspired from OCaml modules, but the
term "module" already refers to something else in Zig. ↩
![\"Feels](\"https://www.axelmagn.com/blog/202610-zig-traits/so_good.png\")
↩This is a pretty simplistic definition of a numeric
trait. In practice, you would probably want to look into\n std::ops from Rust or\n Num\n from Haskell. ↩