README.md

multiring.zig

The multiring is a hierarchical, forwardly linked and circularly linked abstract data type. multiring.zig implements the multiring in the Zig programming language.

Note

The multiring, as implemented in this repository, hasn’t been specified and verified formally.

Here’s how a multiring is traversed:

The counter-clockwise orientation of traversal in the animation above is arbitrary—we obtain it by having the normal to the plane of each ring point up and applying the right-hand rule. We chose a 3D representation to better visualize the depth of the traversal.

Properties of this module

• Linked list-like interface
• No recursive method implementations
• No dependencies
• No memory management

Adding multiring.zig to a Zig v0.13.0 project

In your project’s build.zig.zon file, add the following dependency:

.{
    .dependencies = .{
        .multiring = .{
            .url = "https://github.com/ok-ryoko/multiring.zig/archive/refs/heads/main.tar.gz",
        },
    },
}

When you first run zig build, it will complain about a missing hash for the multiring dependency and echo the computed hash. You can use this value to populate the dependency’s hash field.

Next, declare this module as a dependency in your build.zig file, e.g.,

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

Finally, add the module to your target, e.g.,

exe.root_module.addImport("multiring", multiring.module("multiring"));

… where exe in this example is a *std.Build.Step.Compile that represents an executable to be compiled. You should now be able to import the MultiRing ADT like so:

const MultiRing = @import("multiring").MultiRing;

This module has not yet had any versioned releases, so dependents that favor reproducibility should reference a particular commit on main as in the following example:

.{
    .dependencies = .{
        .multiring = .{
            .url = "https://github.com/ok-ryoko/multiring.zig/archive/4d241318e1aa6cec7c0bb9b50dda4fae11720839.tar.gz",
            .hash = "12202e4b8b3ea04e5397225ab2ee83a9e002946488b07da78b4da09f88519a7d459d",
        },
    },
}

Using multiring.zig

Please see the tests in multiring_test.zig as well as the examples.

The MultiRing API is still unstable; Ryoko doesn’t recommend using this library in production.

Applications

multiring.zig has no known applications. Ryoko wrote it to practice Zig, have fun and show linked lists some love. If you have used multiring.zig successfully in your project(s), please let us know by starting a discussion.

Community

Understanding our code of conduct

Please take time to read our code of conduct before reaching out for support or making a contribution.

Getting support

If you’re encountering unexpected or undesirable program behavior, check the issue tracker to see whether your problem has already been reported. If not, please consider taking time to create a bug report.

If you have questions about using the program or participating in the community around the program, consider starting a discussion.

Please allow up to 1 week for a maintainer to reply to an issue or a discussion.

Contributing to multiring.zig

If you’re interested in contributing, then please read our contributing guidelines.

License

multiring.zig is free and open source software licensed under the MIT license.

Acknowledgements

The multiring.zig logos and traversal animations were made in Inkscape and Blender, respectively.

The initial implementation was inspired by Zig 0.9.1’s std.SinglyLinkedList.

The following resources have been instrumental in preparing this repository for community contributions:

• Open Source Guides
• the GitHub documentation and the github/docs repository
• the tokio contributing guidelines