A small Zig library for parsing and formatting IEEE 802 MAC addresses.
README.md

zig-macaddress #

A small Zig library for parsing and formatting IEEE 802 MAC addresses.

A MacAddress is a single u48, so it is cheap to copy, compare, sort, and store. Parsing accepts the common textual conventions; formatting can emit any of them in either case.

Requires Zig 0.16.0 or later.

The API documentation, generated from the doc comments in the source, is published at https://jeff.jcollie.page/zig-macaddress/.

Installation #

Fetch the package and save it to your build.zig.zon:

zig fetch --save git+https://git.jcollie.dev/jeff/zig-macaddress.git

Then wire the module into your build:

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

exe.root_module.addImport("macaddress", macaddress_dep.module("macaddress"));

Usage #

const std = @import("std");
const macaddress = @import("macaddress");
const MacAddress = macaddress.MacAddress;

pub fn main() !void {
    const mac: MacAddress = try .parse("00:11:22:33:44:55");

    // mac.data is a plain u48
    std.debug.assert(mac.data == 0x001122334455);

    var buffer: [17]u8 = undefined;

    // Default formatting: upper case, colon separated.
    var w: std.Io.Writer = .fixed(&buffer);
    try w.print("{f}", .{mac});
    std.debug.assert(std.mem.eql(u8, w.buffered(), "00:11:22:33:44:55"));

    // Or pick a style and case explicitly.
    var w2: std.Io.Writer = .fixed(&buffer);
    try mac.formatOptions(&w2, .{ .case = .lower, .style = .cisco });
    std.debug.assert(std.mem.eql(u8, w2.buffered(), "0011.2233.4455"));
}

Parsing #

MacAddress.parse (also re-exported as macaddress.parse) trims surrounding whitespace and then accepts exactly these layouts:

Input Length
001122334455 12
0011.2233.4455 14
00 11 22 33 44 55 17
00:11:22:33:44:55 17
00-11-22-33-44-55 17

Hex digits may be upper or lower case, and the two cases may be mixed. Anything else — a wrong length, a stray character, a separator in the wrong place, or a separator that does not match the layout — returns error.NotAMacAddress. The separators in a 17-character address are checked individually, so mixed forms such as 00:11-22 33:44-55 are also accepted.

Formatting #

format implements the standard std.fmt interface, so a MacAddress can be printed with {f}. It uses the defaults: upper case, colon separated.

For anything else, call formatOptions with a FormatOptions:

pub const FormatOptions = struct {
    case: Case = .upper,   // .upper, .lower
    style: Style = .colons,
};
Style Output
.compact 001122334455
.cisco 0011.2233.4455
.spaces 00 11 22 33 44 55
.colons 00:11:22:33:44:55
.hyphen, .dash, .minus 00-11-22-33-44-55

.hyphen, .dash, and .minus are three names for the same output; pick whichever reads best where you use it.

Every style produces at most 17 bytes, so a [17]u8 is always a large enough buffer.

Where this lives #

The canonical repository is on my Forgejo instance, mirrored to Codeberg and Tangled, and published on Radicle (see below):

git clone https://git.jcollie.dev/jeff/zig-macaddress.git
git clone https://codeberg.org/jcollie/zig-macaddress.git

The Tangled mirror is at https://tangled.org/jcollie.dev/zig-macaddress.

Checking out the source with Radicle #

This repository is published on Radicle, a peer-to-peer code forge built on git. Its Repository ID (RID) is:

rad:z3tH7LKeAUZWLmjbkkquzDxZ4Zjam

If you do not have Radicle yet, install it, create an identity, and start your node:

curl -sSf https://radicle.dev/install | sh
rad auth
rad node start

Then clone the repository:

rad clone rad:z3tH7LKeAUZWLmjbkkquzDxZ4Zjam

rad clone consults your node's routing table to find seeds that carry the repository, and drops the working copy into a zig-macaddress directory. Pass a target path as a second argument to put it somewhere else. If your node has not discovered a seed yet, name one directly with --seed <NID>.

The result is an ordinary git working copy on the main branch, with a rad remote wired up, so everyday work is just git. To pull in changes published since your clone:

rad sync --fetch
git pull rad main

Building and testing #

This package is a library only — it builds no executable, so test is the one interesting step:

zig build test

It has no dependencies of its own beyond the standard library.

zig build check compiles everything without running it, which is how the documentation server is kept from quietly breaking — nothing else builds it.

A Nix flake provides a development shell with the pinned Zig toolchain plus reuse, pinact, and git-pages-cli:

nix develop

Documentation #

Zig generates the API documentation from the doc comments, and this project keeps most of its explanation there, so it is worth reading rather than the source:

zig build docs        # writes zig-out/docs
zig build docs-serve  # then open http://127.0.0.1:8000/

It has to be served rather than opened as a file: the viewer fetches sources.tar and main.wasm at runtime, and a browser refuses both from a file:// page. Pass -Ddocs-port=N to use a port other than 8000.

Pushes to main publish the same bundle to https://jeff.jcollie.page/zig-macaddress/.

License #

MIT, except where noted otherwise. This repository follows the REUSE specification: every file carries its own SPDX headers, and the full license texts live in LICENSES/.