paoda
/
bit-string
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: clean up code + documentation

This commit is contained in:
Rekai Nyangadzayi Musuka 2023-12-02 15:08:14 -06:00
parent dbe6bd50cd
commit fbbd25a4c8
2 changed files with 32 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
README.md
View File

@ -1,17 +1,19 @@
# Bit String
A library to check and extract values from integers based on a "bit string". Primarily intended for (my) emulator instruction decoding, but maybe someone else can find a use for it?
A library to check and extract values from integers based on a "bit string". Primarily intended for (my) emulator instruction decoding, but maybe someone else can find a use for it?
## Example
```zig
const std = @import("std");
```zig
const std = @import("std");
test "doc test" {
test "doc test" {
const value: u8 = 0b10001011;
try std.testing.expectEqual(true, match("10001011", value));
try std.testing.expectEqual(true, match("1000_1011", value));
try std.testing.expectEqual(false, match("11111011", value));
try std.testing.expectEqual(true, match("1---1011", value));
{
const ret = extract("1000aaaa", value);
try std.testing.expectEqual(@as(u4, 0b1011), ret.a);
@ -27,17 +29,18 @@ test "doc test" {
try std.testing.expectEqual(@as(u3, 0b1), ret.c);
try std.testing.expectEqual(@as(u3, 0b1), ret.d);
}
}
```
}
```
## Syntax
| Token | Meaning | Description
| ------- | --------- | -----------
| `0` | Unset bit | In the equivalent position, the value's bit must be set.
| `1` | Set bit | In the equivalent position, the value's bit must be set.
| `a..=z` | Variable | Given the 4-bit bit string, `"1aa0"`, the value `0b1010` would produce the variable `a` with the value `0b01`
| `-` | Ignored | In the equivalent position, the value's bit does not matter.
| Token | Meaning | Description
| ------- | --------- | -----------
| `0` | Clear bit | In the equivalent position, the value's bit must be cleared.
| `1` | Set bit | In the equivalent position, the value's bit must be set.
| `a..=z` | Variable | Given the 4-bit bit string, `"1aa0"`, the value `0b1010` would produce the variable `a` with the value `0b01`
| `-` | Ignored | In the equivalent position, the value's bit does not matter.
| `_` | Ignored* | Underscores are completely ignored during parsing, use to make bit strings easier to read e.g. `1111_1111`
## Notes

54
src/lib.zig
View File

@ -45,16 +45,6 @@ const std = @import("std");
const Log2Int = std.math.Log2Int;
/// Test to see if a value matches the provided bit-string
///
/// ### Example
/// ```zig
/// match("1100", @as(u4, 0b1100)) // true
/// match("1100", @as(u4, 0b1110)) // false
///
/// match("1--0", @as(u4, 0b1010)) // true
/// match("1ab0", @as(u4, 0b1010)) // true
/// match("11_00", @as(u4, 0b1100)) // true
/// ```
pub fn match(comptime bit_string: []const u8, value: anytype) bool {
@setEvalBranchQuota(std.math.maxInt(u32)); // FIXME: bad practice
@ -88,7 +78,7 @@ pub fn match(comptime bit_string: []const u8, value: anytype) bool {
return (value & set_mask) == set_mask and (~value & clr_mask) == clr_mask;
}
test "match" {
test match {
// doc tests
try std.testing.expectEqual(true, match("1100", @as(u4, 0b1100)));
try std.testing.expectEqual(false, match("1100", @as(u4, 0b1110)));
@ -113,15 +103,6 @@ test "match" {
/// Extracts the variables (defined in the bit string) from a value.
///
/// ### Examples
/// ```
/// const ret = extract("aaaa", @as(u4, 0b1001)); // ret.a == 0b1001
/// const ret = extract("abcd", @as(u4, 0b1001)); // ret.a == 0b1, ret.b == 0b0, ret.c == 0b0, ret.d == 0b1
/// const ret = extract("a0ab", @as(u4, 0b1001)); // ret.a == 0b10, ret.b == 0b1
/// const ret = extract("-a-a", @as(u4, 0b1001)); // ret.a == 0b01
/// const ret = extract("aa_aa", @as(u4, 0b1001)); // ret.a == 0b1001
/// ```
///
/// Note: In Debug and ReleaseSafe builds, there's a runtime assert that
/// ensures that the value matches against the bit string.
pub fn extract(comptime bit_string: []const u8, value: anytype) Bitfield(bit_string) {
@ -161,19 +142,14 @@ pub fn extract(comptime bit_string: []const u8, value: anytype) Bitfield(bit_str
//
// we're confident in this because it's guaranteed to be the same bit_string,
// and it's the same linear search. If you're reading this double check that this is still the case lol
break :blk @truncate(if (bmi2 and !@inComptime()) pext.hardware(u32, value, masked_val) else pext.software(u32, value, masked_val));
break :blk @truncate(if (bmi2 and !@inComptime()) pext.hw(u32, value, masked_val) else pext.sw(u32, value, masked_val));
};
}
return ret;
}
pub fn matchExtract(comptime bit_string: []const u8, value: anytype) ?Bitfield(bit_string) {
if (!match(bit_string, value)) return null;
return extract(bit_string, value);
}
test "extract" {
test extract {
// doc tests
{
const ret = extract("aaaa", @as(u4, 0b1001));
@ -237,11 +213,13 @@ test "extract" {
}
}
pub fn matchExtract(comptime bit_string: []const u8, value: anytype) ?Bitfield(bit_string) {
if (!match(bit_string, value)) return null;
return extract(bit_string, value);
}
/// Parses a bit string and reifies a struct that will contain fields that correspond to the variables present in the bit string.
///
///
/// Note: If it weren't for the return type of `extract()`, this type would be a private implementation detail
///
/// TODO: I will probably rename this type
pub fn Bitfield(comptime bit_string: []const u8) type {
const StructField = std.builtin.Type.StructField;
@ -323,7 +301,7 @@ fn verify(comptime T: type, comptime bit_string: []const u8) void {
}
const pext = struct {
fn hardware(comptime T: type, value: T, mask: T) T {
fn hw(comptime T: type, value: T, mask: T) T {
return switch (T) {
u32 => asm ("pextl %[mask], %[value], %[ret]"
: [ret] "=r" (-> T),
@ -340,7 +318,7 @@ const pext = struct {
}
// why we need this: https://github.com/ziglang/zig/issues/14995 (ideally compiler-rt implements this for us)
fn software(comptime T: type, value: T, mask: T) T {
fn sw(comptime T: type, value: T, mask: T) T {
return switch (T) {
u32 => {
// TODO: Looks (and is) like C code :pensive:
@ -375,13 +353,13 @@ const pext = struct {
};
}
test "pext" {
test pext {
const builtin = @import("builtin");
switch (builtin.cpu.arch) {
.x86_64 => if (std.Target.x86.featureSetHas(builtin.cpu.features, .bmi2)) {
try std.testing.expectEqual(@as(u32, 0x0001_2567), pext.hardware(u32, 0x12345678, 0xFF00FFF0));
try std.testing.expectEqual(@as(u64, 0x0001_2567), pext.hardware(u64, 0x12345678, 0xFF00FFF0));
try std.testing.expectEqual(@as(u32, 0x0001_2567), pext.hw(u32, 0x12345678, 0xFF00FFF0));
try std.testing.expectEqual(@as(u64, 0x0001_2567), pext.hw(u64, 0x12345678, 0xFF00FFF0));
// random tests
// TODO: when implemented, test 64-bit fallback `PEXT` as well
@ -390,14 +368,14 @@ const pext = struct {
const value = rand_impl.random().int(u32);
const mask = rand_impl.random().int(u32);
try std.testing.expectEqual(pext.hardware(u32, value, mask), pext.software(u32, value, mask));
try std.testing.expectEqual(pext.hw(u32, value, mask), pext.sw(u32, value, mask));
}
},
else => {},
else => return error.SkipZigTest,
}
// example values from: https://en.wikipedia.org/w/index.php?title=X86_Bit_manipulation_instruction_set&oldid=1170426748
try std.testing.expectEqual(@as(u32, 0x0001_2567), pext.software(u32, 0x12345678, 0xFF00FFF0));
try std.testing.expectEqual(@as(u32, 0x0001_2567), pext.sw(u32, 0x12345678, 0xFF00FFF0));
}
};