https://github.com/ultd/base58-zig
A base58 encoder/decoder implementation in Zig
https://github.com/ultd/base58-zig
Last synced: 6 months ago
JSON representation
A base58 encoder/decoder implementation in Zig
- Host: GitHub
- URL: https://github.com/ultd/base58-zig
- Owner: ultd
- License: mit
- Created: 2023-05-16T02:32:43.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-27T00:00:32.000Z (over 1 year ago)
- Last Synced: 2024-11-15T11:36:21.018Z (12 months ago)
- Language: Zig
- Size: 31.3 KB
- Stars: 8
- Watchers: 1
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- License: LICENSE
Awesome Lists containing this project
- awesome-zig - Base58-zig🗒️A base58 encoding/decoding library providing both alloc and non-alloc methods
README
🌀 Base58-zig
## Overview
_base58-zig_ is encoder/decoder library written in Zig.
## Installation
### Manual
1. Declare Base58-zig as a dependency in `build.zig.zon`:
```diff
.{
.name = "my-project",
.version = "1.0.0",
.dependencies = .{
+ .@"base58-zig" = .{
+ .url = "https://github.com/ultd/base58-zig/archive/.tar.gz",
+ },
},
}
```
2. Expose Base58-zig as a module in `build.zig`:
```diff
const std = @import("std");
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
+ const opts = .{ .target = target, .optimize = optimize };
+ const base58_module = b.dependency("base58-zig", opts).module("base58-zig");
const exe = b.addExecutable(.{
.name = "test",
.root_source_file = .{ .path = "src/main.zig" },
.target = target,
.optimize = optimize,
});
+ exe.addModule("base58-zig", base58_module);
exe.install();
...
}
```
3. Obtain Base58-zig's package hash:
```
$ zig build
my-project/build.zig.zon:6:20: error: url field is missing corresponding hash field
.url = "https://github.com/ultd/base58-zig/archive/.tar.gz",
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
note: expected .hash = "",
```
4. Update `build.zig.zon` with hash value:
```diff
.{
.name = "my-project",
.version = "1.0.0",
.dependencies = .{
.@"base58-zig" = .{
.url = "https://github.com/ultd/base58-zig/archive/.tar.gz",
+ .hash = "",
},
},
}
```
### API Reference
encodeAlloc - Encodes a `[]u8` into an alloc'ed base58 encoded string.
**Example**
```zig
const std = @import("std");
const base58 = @import("base58-zig");
const allocator = std.heap.page_allocator;
var someBytes = [4]u8{ 10, 20, 30, 40 };
pub fn main() !void {
const encoder = base58.Encoder.init(.{});
var encodedStr = try encoder.encodeAlloc(allocator, &someBytes);
defer allocator.free(encodedStr);
std.log.debug("encoded val: {s}", .{encodedStr});
}
```
encode - Base58 Encodes a `[]u8` into an `dest` buffer passed and returns bytes written to buffer.
The `dest` buffer written to needs to be properly sized. Base58 encoding is a variable length encoder therefore you should allocate extra and then resize if needed afterwards. Below is an example.
**Example**
```zig
const std = @import("std");
const base58 = @import("base58-zig");
const allocator = std.heap.page_allocator;
var someBytes = [4]u8{ 10, 20, 30, 40 };
pub fn main() !void {
const encoder = base58.Encoder.init(.{});
// allocate someBytes.len * 2 []u8
var dest = allocator.alloc(u8, someBytes.len * 2);
var size = try encoder.encode(&someBytes, dest);
if(dest != size) {
dest = allocator.realloc(dest, size);
}
defer allocator.free(dest);
std.log.debug("encoded val: {s}", .{dest});
}
```
decodeAlloc - Decodes a base58 encoded string into a alloc'ed `[]u8` and returns it.
**Example**
```zig
const std = @import("std");
const base58 = @import("base58-zig");
const allocator = std.heap.page_allocator;
var encodedStr: []const u8 = "4rL4RCWHz3iNCdCaveD8KcHfV9YWGsqSHFPo7X2zBNwa";
pub fn main() !void {
const decoder = base58.Decoder.init(.{});
var decodedBytes = try decoder.decodeAlloc(allocator, encodedStr);
defer allocator.free(decodedBytes);
std.log.debug("decoded bytes: {any}", .{decodedBytes});
}
```
decode - Decodes a base58 encoded string into `dest` buffer and returns number of bytes written.
The `dest` buffer written to needs to be properly sized. Base58 encoding is a variable length encoder therefore you should allocate same size buffer as encoded value and then resize, if needed, afterwards. Below is an example.
**Example**
```zig
const std = @import("std");
const base58 = @import("base58-zig");
const allocator = std.heap.page_allocator;
var encodedStr: []const u8 = "4rL4RCWHz3iNCdCaveD8KcHfV9YWGsqSHFPo7X2zBNwa";
pub fn main() !void {
const decoder = base58.Decoder.init(.{});
// allocate 1 * encodedStr.len buffer
var dest = allocator.alloc(u8, encodedStr.len);
var size = try decoder.decode(encodedStr, dest);
if(dest.len != size){
dest = allocator.realloc(dest, size);
}
defer allocator.free(dest);
std.log.debug("decoded bytes: {any}", .{dest});
}
```
Alphabet - create a custom alphabet set to pass to encoder/decoder`.
**Example**
```zig
const std = @import("std");
const base58 = @import("base58-zig");
const allocator = std.heap.page_allocator;
var alpha = base58.Alphabet.new(.{
.alphabet = [58]u8{...}. // custom alphabets
});
pub fn main() !void {
const encoder = base58.Encoder.init(.{ alphabet = alpha });
var encodedStr = try encoder.encodeAlloc(allocator, &someBytes);
defer allocator.free(encodedStr);
std.log.debug("encoded val: {s}", .{encodedStr});
}
```