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/.