Disclaimer: This was an exploratory project that I no longer believe should be used for practical purposes. Everything I leared in this project was refined into the zimpl library which I will continue to maintain.
An attempt at implementing something along the lines of Rust type traits in Zig. Using this library you can define traits and compile-time verify that types implement them.
I wrote
an article
about working with anytype which reflects on
developing this library.
Below are some related projects and Zig proposal threads that I read while implementing the library.
- Zig Compile-Time-Contracts
- Zig issues: #1268, #1669, #6615, #17198
I don't have any strong position on proposed changes to the Zig language regarding generics, and I respect the Zig team's reasoning for keeping the type system simple.
A trait is simply a comptime function taking a type and returning a struct type containing only declarations. Each declaration of the returned struct is a required declaration that a type must have if it implements the trait.
Below is a trait that requires implementing types to define an integer
sub-type Count, define an init function, and define member functions
increment and read.
pub fn Incrementable(comptime Type: type) type {
return struct {
// below is the same as `pub const Count = type` except that during
// trait verification it requires that '@typeInfo(Type.Count) == .Int'
pub const Count = hasTypeId(.Int);
pub const init = fn () Type;
pub const increment = fn (*Type) void;
pub const read = fn (*const Type) Type.Count;
};
}A type that implements the above Incrementable trait is provided below.
const MyCounter = struct {
pub const Count = u32;
count: Count,
pub fn init() @This() {
return .{ .count = 0 };
}
pub fn increment(self: *@This()) void {
self.count += 1;
}
pub fn read(self: *const @This()) Count {
return self.count;
}
};To require that a generic type parameter implements a given trait you simply need to add a comptime verification line at the start of your function.
pub fn countToTen(comptime Counter: type) void {
comptime where(Counter, implements(Incrementable));
var counter = Counter.init();
while (counter.read() < 10) {
counter.increment();
}
}Note: If we don't specify that trait verification is comptime then verification might be evaluated later during compilation. This results in regular duck-typing errors rather than trait implementation errors.
If we define a type that fails to implement the Incrementable trait and pass
it to countToTen, then the call to where will produce a compile error.
const MyCounterMissingDecl = struct {
pub const Count = u32;
count: Count,
pub fn init() @This() {
return .{ .count = 0 };
}
pub fn read(self: *const @This()) Count {
return self.count;
}
};trait.zig:12:13: error: trait 'count.Incrementable(count.MyCounterMissingDecl)' failed: missing decl 'increment'Multiple traits can be type checked with a single call.
pub fn HasDimensions(comptime _: type) type {
return struct {
pub const width = comptime_int;
pub const height = comptime_int;
};
}
pub fn computeAreaAndCount(comptime T: type) void {
comptime where(T, implements(.{ Incrementable, HasDimensions }));
var counter = T.init();
while (counter.read() < T.width * T.height) {
counter.increment();
}
}Traits can require types to declare sub-types that implement traits.
pub fn HasIncrementable(comptime _: type) type {
return struct {
pub const Counter = implements(Incrementable);
};
}
pub fn useHolderToCountToTen(comptime T: type) void {
comptime where(T, implements(HasIncrementable));
var counter = T.Counter.init();
while (counter.read() < 10) {
counter.increment();
}
}pub const CounterHolder = struct {
pub const Counter = MyCounter;
};
pub const InvalidCounterHolder = struct {
pub const Counter = MyCounterMissingDecl;
};trait.zig:12:13: error: trait 'count.HasIncrementable(count.InvalidCounterHolder)' failed: decl 'Counter': trait 'count.Incrementable(count.MyCounterMissingDecl)' failed: missing decl 'increment'Alongside enforcing trait implementation in generic functions, types themselves can declare that they implement a given trait.
const MyCounter = struct {
comptime { where(@This(), implements(Incrementable)); }
// ...
};Then with testing.refAllDecls you can run zig test to automatically verify
that these traits are implemented.
test {
std.testing.refAllDecls(@This);
}Credit to "NewbLuck" on the Zig Discord for pointing out this nice pattern.
Often one will want to pass a pointer type to a function taking
anytype, and it turns out that it is still quite simple to do
trait checking.
Single item pointers allow automatic dereferencing in Zig, e.g.
ptr.decl is ptr.*.decl, so it makes sense to define that a pointer
type *T implements a trait if T implements the trait.
To
accomplish this, types are passed through an Unwrap function before
trait checking occurs.
pub fn Unwrap(comptime Type: type) type {
return switch (@typeInfo(Type)) {
.Pointer => PointerChild(Type),
else => Type,
};
}Therefore the following function will work just fine with pointers to
types that implement Incrementable.
pub fn countToTen(counter: anytype) void {
comptime where(@TypeOf(counter), implements(Incrementable));
while (counter.read() < 10) {
counter.increment();
}
}For slice parameters we usually want the caller to be able to pass
both *[_]T and []T. The library provides the
SliceChild helper function to verify that a type can coerce to a slice
andt extract its child type.
pub fn incrementAll(list: anytype) void {
comptime where(SliceChild(@TypeOf(list)), implements(Incrementable));
for (list) |*counter| {
counter.increment();
}
}The above function works directly on parameters that can coerce to a slice, but if required we can force coercion to a slice type as shown below.
pub fn incrementAll(list: anytype) void {
comptime where(SliceChild(@TypeOf(list)), implements(Incrementable));
const slice: []SliceChild(@TypeOf(list)) = list;
for (slice) |*counter| {
counter.increment();
}
}Using where and implements we can require that types have
declaration satisfying trait requirements. We cannot, however,
prevent code from using declarations beyond the scope of the checked
traits. Thus it is on the developer to keep traits up to date with how
types are actually used.
The interface function provides a method to formally restrict
traits to be both necessary and sufficient requirements for types.
Calling interface(Type, Trait) will construct a comptime instance of a
generated struct type that contains a field for each declaration of
Type that has a matching declaration in Trait. The
fields of this interface struct should then be used in place of the
declarations of Type.
pub fn countToTen(counter: anytype) void {
const ifc = interface(@TypeOf(counter), Incrementable);
while (ifc.read(counter) < 10) {
ifc.increment(counter);
}
}Interface construction performs the same type checking as where.
The type returned by interface(U, T) is Interface(U, T), a
struct type containing one field for each declaration of
T with default value equal to the corresponding declaration of U
(if it exists and has the correct type).
A more flexible way to work with interfaces is to
take an Interface struct as an explicit comptime parameter.
pub fn countToTen(counter: anytype, ifc: Interface(@TypeOf(Counter), Incrementable)) void {
while (ifc.read(counter) < 10) {
ifc.increment(counter);
}
}This allows the caller to override declarations, or provide a custom interface for a type that doesn't have the required declarations.
Unfortunately, this style of interfaces does not allow
trait declarations to depend on one another.
A restricted version of the Incrementable interface that will play
well with the interface parameter convention is provided below.
pub fn Incrementable(comptime Type: type) type {
return struct {
pub const increment = fn (*Type) void;
pub const read = fn (*const Type) usize;
};
}An example of what is possible with this convention is shown below.
const USize = struct {
pub fn increment(i: *usize) void {
i.* += 1;
}
pub fn read(i: *const usize) usize {
return i.*;
}
};
var my_count: usize = 0;
countToTen(&my_count, .{ .increment = USize.increment, .read = USize.read });Users can define their own helper functions as needed by wrapping and expanding the trait module.
// mytrait.zig
// expose all declaraions from the standard trait module
const zt = @import("ztrait");
pub usingnamespace zt;
// define your own convenience functions
pub fn BackingInteger(comptime Type: type) type {
comptime zt.where(Type, zt.isPackedContainer());
return switch (@typeInfo(Type)) {
inline .Struct, .Union => |info| info.backing_integer.?,
else => unreachable,
};
}Sometimes it can be useful to have type signatures directly in function
definitions. Zig currently does not support this, but there is a hacky
workaround using the fact that Zig can evaluate a comptime function in
the return type location.
pub fn sumIntSlice(comptime I: type, list: []const I) Returns(I, .{
where(I, hasTypeId(.Int)),
}) {
var count: I = 0;
for (list) |elem| {
count += elem;
}
return count;
}The first parameter of Returns is the actual return type of the function,
while the second is an unreferenced anytype parameter.
pub fn Returns(comptime ReturnType: type, comptime _: anytype) type {
return ReturnType;
}Warning: Error messages can be less helpful when using Returns
because the compile error occurs while a function signature is being
generated. This can result in the line number of the original call
not be reported unless building with -freference-trace (and even then
the call site may still be obscured in some degenerate cases).