tiny.preserves.CowBytes

1/// A byte slice with a tag that says whether its holder owns the bytes. Code that keeps a string,2/// byte string or symbol apart from its value holds it in this type, so its ownership travels with3/// it. A new one borrows its bytes unless its builder says otherwise.4pub const CowBytes = struct {5    /// The bytes of the string, byte string or symbol.6    bytes: []const u8,7    /// Whether the holder owns `bytes`. It defaults to borrowed, so a struct written by hand never8    /// frees bytes it did not allocate.9    ownership: Ownership = .borrowed,1011    /// Wraps `bytes` as borrowed. Code that wraps bytes it keeps alive elsewhere calls it. `deinit`12    /// leaves the bytes alone, so they have to outlive the result.13    pub fn borrow(bytes: []const u8) CowBytes {14        return .{ .bytes = bytes, .ownership = .borrowed };15    }1617    /// Wraps `bytes` as owned. Code that wraps bytes it allocated calls it. `deinit` frees them18    /// with the allocator it is given, so they have to come from that allocator.19    pub fn own(bytes: []const u8) CowBytes {20        return .{ .bytes = bytes, .ownership = .owned };21    }2223    /// Frees the bytes with `allocator` when they are owned, and leaves them when they are24    /// borrowed. Code that holds the bytes calls it when it is done with them. The struct is25    /// undefined afterward.26    pub fn deinit(self: *CowBytes, allocator: Allocator) void {27        if (self.ownership == .owned) allocator.free(self.bytes);28        self.* = undefined;29    }3031    /// Returns a copy that owns its bytes. Code that must keep the bytes after their owner goes32    /// calls it. Borrowed bytes are copied into storage from `allocator`. Owned bytes come back as33    /// the same struct with no copy, so the result and the original share them and only one of the34    /// two may be freed. The call can fail only with `error.OutOfMemory`.35    pub fn intoOwned(self: CowBytes, allocator: Allocator) !CowBytes {36        return switch (self.ownership) {37            .owned => self,38            .borrowed => CowBytes.own(try allocator.dupe(u8, self.bytes)),39        };40    }41};

1pub const CowBytes = atom.CowBytes;