# 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 .
## Installation
Fetch the package and save it to your `build.zig.zon`:
```console
zig fetch --save git+https://git.jcollie.dev/jeff/zig-macaddress.git
```
Then wire the module into your build:
```zig
const macaddress_dep = b.dependency("macaddress", .{
.target = target,
.optimize = optimize,
});
exe.root_module.addImport("macaddress", macaddress_dep.module("macaddress"));
```
## Usage
```zig
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`:
```zig
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):
```console
git clone https://git.jcollie.dev/jeff/zig-macaddress.git
git clone https://codeberg.org/jcollie/zig-macaddress.git
```
The Tangled mirror is at .
## Checking out the source with Radicle
This repository is published on [Radicle](https://radicle.dev/), 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:
```console
curl -sSf https://radicle.dev/install | sh
rad auth
rad node start
```
Then clone the repository:
```console
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 `.
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:
```console
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:
```console
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`:
```console
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:
```console
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
.
## License
MIT, except where noted otherwise. This repository follows the
[REUSE](https://reuse.software/) specification: every file carries its own
SPDX headers, and the full license texts live in `LICENSES/`.