zul

# Zig Utility Library
The purpose of this library is to enhance Zig's standard library. Much of zul wraps Zig's std to provide simpler APIs for common tasks (e.g. reading lines from a file). In other cases, new functionality has been added (e.g. a UUID type).

Besides Zig's standard library, there are no dependencies. Most functionality is contained within its own file and can be copy and pasted into an existing library or project.

Full documentation is available at: [https://www.goblgobl.com/zul/](https://www.goblgobl.com/zul/).

(This readme is auto-generated from [docs/src/readme.njk](https://github.com/karlseguin/zul/blob/master/docs/src/readme.njk))

## Usage
In your build.zig.zon add a reference to Zul:

```zig
.{
  .name = "my-app",
  .paths = .{""},
  .version = "0.0.0",
  .dependencies = .{
    .zul = .{
      .url = "https://github.com/karlseguin/zul/archive/master.tar.gz",
      .hash = "$INSERT_HASH_HERE"
    },
  },
}
```

To get the hash, run:

```bash
zig fetch https://github.com/karlseguin/zul/archive/master.tar.gz
```

Instead of `master` you can use a specific commit/tag.

Next, in your `build.zig`, you should already have an executable, something like:

```zig
const exe = b.addExecutable(.{
    .name = "my-app",
    .root_source_file = b.path("src/main.zig"),
    .target = target,
    .optimize = optimize,
});
```

Add the following line:

```zig
exe.root_module.addImport("zul", b.dependency("zul", .{}).module("zul"));
```

You can now `const zul = @import("zul");` in your project.

## [zul.benchmark.run](https://www.goblgobl.com/zul/benchmark/)
Simple benchmarking function.

```zig
const HAYSTACK = "abcdefghijklmnopqrstvuwxyz0123456789";

pub fn main() !void {
	(try zul.benchmark.run(indexOfScalar, .{})).print("indexOfScalar");
	(try zul.benchmark.run(lastIndexOfScalar, .{})).print("lastIndexOfScalar");
}

fn indexOfScalar(_: Allocator, _: *std.time.Timer) !void {
	const i = std.mem.indexOfScalar(u8, HAYSTACK, '9').?;
	if (i != 35) {
		@panic("fail");
	}
}

fn lastIndexOfScalar(_: Allocator, _: *std.time.Timer) !void {
	const i = std.mem.lastIndexOfScalar(u8, HAYSTACK, 'a').?;
	if (i != 0) {
		@panic("fail");
	}
}

// indexOfScalar
//   49882322 iterations   59.45ns per iterations
//   worst: 167ns  median: 42ns    stddev: 20.66ns
//
// lastIndexOfScalar
//   20993066 iterations   142.15ns per iterations
//   worst: 292ns  median: 125ns   stddev: 23.13ns
```

## [zul.CommandLineArgs](https://www.goblgobl.com/zul/command_line_args/)
A simple command line parser.

```zig
var args = try zul.CommandLineArgs.parse(allocator);
defer args.deinit();

if (args.contains("version")) {
	//todo: print the version
	os.exit(0);
}

// Values retrieved from args.get are valid until args.deinit()
// is called. Dupe the value if needed.
const host = args.get("host") orelse "127.0.0.1";
...
```

## [zul.DateTime](https://www.goblgobl.com/zul/datetime/)
Simple (no leap seconds, UTC-only), DateTime, Date and Time types.

```zig
// Currently only s