interfaceCast

A Zig-ish way of handling interfaces.

Features

interfaceCast allows you to cast any struct into an interface. - Interfaces are just structs that have both a vtable and a context field. - The context (ptr, data and userdata also works) field must be of type *anyopaque. - The vtable field must be a constant pointer to a struct and each field of that struct must be a constant pointer to a function.
Automatic casting of *anyopaque into the interface's context type.
Automatic error coercion if the interface returns an error superset of its context type's (see example below).
Allows for generic interfaces (see example below).
Friendly with predefined interfaces (like the ones from std).

Example

const std = @import("std");
const interfaceCast = @import("interfaceCast").interfaceCast;
const print = std.debug.print;
const assert = std.debug.assert;

/// This is an interface that can be used to represent a list
/// that can append and pop elements of type `T`.
pub fn AnyList(comptime T: type) type {

    // Interfaces are just structs with `context` and `vtable` fields.
    return struct {

        // This is the context field, which must of type `*anyopaque`.
        context: *anyopaque,

        // This is the vtable field, which must be a constant pointer to a struct.
        //
        // Each field in the vtable must be a constant pointer to a function
        //
        // The name of each field is significant, as it directly maps to the context type's function names.
        // Since we want this interface to append and pop elements, we define the vtable with `append` and `pop` fields.
        // The function signatures must match the context type's function signatures.
        vtable: *const struct {
            append: *const fn (self: *anyopaque, value: T) error{ OutOfMemory, Overflow }!void,
            pop: *const fn (self: *anyopaque) ?T,
        },

        // Notice how the following function return type is an error union with `OutOfMemory` and `Overflow`.
        // This is the case because `ArrayList` might return `error.OutOfMemory` when appending an element,
        // and `BoundedArray` might return `error.Overflow` when trying to append an element
        // that exceeds its defined capacity.
        //
        // So to allow both `ArrayList` and `BoundedArray` to be cast to this interface,
        // we need to define the return type to be an error union that is a superset
        // of both `ArrayList` and `BoundedArray` error sets.
        //
        // This is possible because `interfaceCast` automatically detects that the return
        // type is a superset of the context type's.
        pub fn append(self: @This(), value: T) error{ OutOfMemory, Overflow }!void {
            // Here we call the function from the vtable.
            try self.vtable.append(self.context, value);
        }

        // Interfaces can also return values.
        pub fn pop(self: @This()) ?T {
            // Here we also call the function from the vtable.
            return self.vtable.pop(self.context);
        }
    };
}

/// Appends numbers from 0 to `count - 1` to the provided list.
pub fn appendNumbers(list: AnyList(usize), count: usize) anyerror!void {
    for (0..count) |i| {
        try list.append(i);
    }
}

/// Pops all elements from the list and prints them.
pub fn popAll(list: AnyList(usize)) void {
    while (list.pop()) |item| {
        print("{d} ", .{item});
    }
    print("\r\n", .{});
}

pub fn main() !void {
    // Lets try casting an `ArrayList` to the `AnyList` interface.
    var arraylist = std.ArrayList(usize).init(std.heap.page_allocator);
    defer arraylist.deinit();

    const any_list = interfaceCast(AnyList(usize), &arraylist);
    try appendNumbers(any_list, 5);
    assert(arraylist.items.len == 5);
    // Notice how we fed `any_list` to `appendNumbers`, and `arraylist` gets updated.

    popAll(any_list); // Prints: 4 3 2 1 0
    assert(arraylist.items.len == 0);

    // Lets try the same thing, but now with a `BoundedArray`.
    var bounded_array = std.BoundedArray(usize, 3){};

    const any_list2 = interfaceCast(AnyList(usize), &bounded_array);
    try appendNumbers(any_list2, 3);
    assert(bounded_array.len == 3);
    // Just like the last time, when we append to `any_list2`, `bounded_array` gets updated.

    assert(any_list2.append(3) == error.Overflow);
    // Interfaces can also return errors.

    popAll(any_list2); // Prints: 2 1 0
    assert(bounded_array.len == 0);
}

Adding to a project

Run the following command to add the package to your project.

zig fetch --save git+https://github.com/DanielKMach/interfaceCast#main

Then add it as an import in your build.zig

const interface_cast = b.dependency("interfaceCast", .{
    .target = target,
    .optimize = optimize,
});

your_exe_module.addImport("interfaceCast", interface_cast.module("interfaceCast"));

Now you are ready to use it in your code.

const interfaceCast = @import("interfaceCast").interfaceCast;

Contributing

Feel free to open an issue or make a PR.