tiny.preserves.AnyEmbedded

1/// An embedded value that points to a payload of the host program, with optional functions to2/// compare, hash, free and copy it. Code that places host objects inside values uses this type, as3/// the text parser, the JSON codec and every function at the package root do. Every optional part4/// defaults to `null`, so `.{ .value = ptr }` is a borrowed payload that compares by address.5pub const AnyEmbedded = struct {6    /// An untyped pointer to the payload.7    value: *anyopaque,8    /// The payload's table of equality, hash and order functions, or `null` to compare, order and9    /// hash by address.10    semantic_ops: ?*const SemanticOps = null,11    /// The function that frees the payload, or `null` for a payload the tree borrows. `deinit`12    /// calls it with the payload and the allocator.13    deinit_fn: ?*const fn (*anyopaque, Allocator) void = null,14    /// The function that copies the payload with an allocator and returns a pointer to the copy, or15    /// `null`. A payload with a free function and no copy function makes `clone` panic.16    clone_fn: ?*const fn (*anyopaque, Allocator) Allocator.Error!*anyopaque = null,1718    /// Returns whether two embedded values are equal. `Value.eql` calls it for two embedded values.19    /// Two values with no table are equal when they point to the same payload. A value with a table20    /// never equals one without a table or one with a different table. Two values with the same21    /// table are equal when the table's equality says so.22    pub fn eql(a: AnyEmbedded, b: AnyEmbedded) bool {23        const a_ops = a.semantic_ops orelse {24            if (b.semantic_ops != null) return false;25            return a.value == b.value;26        };27        const b_ops = b.semantic_ops orelse return false;28        if (a_ops != b_ops) return false;29        return a_ops.eql(a.value, b.value);30    }3132    /// Returns the order of one embedded value against another. `Value.compare` calls it for two33    /// embedded values. A value with no table orders before one with a table, and two values with34    /// no table order by payload address. Values with different tables order by the tables'35    /// addresses, and values with the same table order by that table's order. The order is total36    /// whenever each table's order is.37    pub fn order(a: AnyEmbedded, b: AnyEmbedded) std.math.Order {38        const a_ops = a.semantic_ops orelse {39            if (b.semantic_ops != null) return .lt;40            return std.math.order(@intFromPtr(a.value), @intFromPtr(b.value));41        };42        const b_ops = b.semantic_ops orelse return .gt;43        if (a_ops != b_ops) {44            return std.math.order(@intFromPtr(a_ops), @intFromPtr(b_ops));45        }46        return a_ops.order(a.value, b.value);47    }4849    /// Returns the table's hash of the payload, or the payload's address when there is no table.50    /// `Value.hash` calls it for an embedded value.51    pub fn hash(self: AnyEmbedded) u64 {52        if (self.semantic_ops) |ops| return ops.hash(self.value);53        return @intFromPtr(self.value);54    }5556    /// Calls the free function with the payload and `allocator` when there is one, and does nothing57    /// otherwise. `Value.deinit` calls it for an embedded value.58    pub fn deinit(self: *AnyEmbedded, allocator: Allocator) void {59        if (self.deinit_fn) |deinit_payload| deinit_payload(self.value, allocator);60    }6162    /// Returns a copy that keeps the same table and functions. `cloneValueDeep` calls it for an63    /// embedded value. With a copy function, the copy points to a new payload from that function.64    /// With no copy function and no free function, the copy points to the same payload. With a free65    /// function and no copy function, the call panics, because two trees would then free one66    /// payload.67    pub fn clone(self: AnyEmbedded, allocator: Allocator) Allocator.Error!AnyEmbedded {68        var cloned = self;69        if (self.clone_fn) |clone_payload| {70            cloned.value = try clone_payload(self.value, allocator);71            return cloned;72        }73        if (self.deinit_fn != null) @panic("owned embedded value missing clone hook");74        return cloned;75    }76};

1pub const AnyEmbedded = embedded_mod.AnyEmbedded;