Where are the examples?

[ok-ryoko]

Code of conduct

• I have read and agree to the community’s code of conduct.

Scope

I propose the addition of one or more Zig source files to an examples/ directory in the root of the project repository. Each file would emulate client code that imports and builds over multiring.zig. Each file would contain at least one passing test. For example, we could show how to:

• Use memory allocation to build multirings, e.g., a MultiRingBuilder API
• Iterate over the data in a multiring, filtering out (skipping) subrings conditionally
• Sort the data nodes in a ring
• Find the lowest common superring of any two rings in the same multiring
• Remove a (long) chain of data nodes in a ring by cutting links at only the endpoints of the chain
• Use a multiring to index the rings in another multiring

Value proposition

The purpose of this project is to provide a minimal set of low-level operations that facilitate the implementation of algorithms over multirings in client code.

To my knowledge, the multiring is a rarely described data structure. (I have not encountered it in the wild, although it may exist out there in some form and under a different name.) It can therefore be unintuitive to reason about this structure and determine whether it fits one’s use case. By adding examples to this repository, we can make it easier for developers to get started with the data structure and, by extension, increase the project’s accessibility.

Examples can demonstrate the value of this data structure (or the absence thereof, in which case we can save other developers time and energy spent thinking about this structure at all). Without examples, a developer may be less likely to consider this repository for use in their application(s) even when the multiring is a strong model for the data.

Supporting information

To recapitulate, the goal is to prescribe and describe basic idioms for working with multiring.zig. Therefore, the contents of the examples don’t have to be sophisticated, but they must be complete and correct.

If this proposal is accepted, then we should also update the pre-commit hook and CI configuration for Zig source code.