2023-05-23 02:08:34 +02:00
|
|
|
const debug = @import("./debug.zig");
|
|
|
|
|
|
|
|
const io = @import("./io.zig");
|
|
|
|
|
|
|
|
const math = @import("./math.zig");
|
|
|
|
|
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
/// Returns a dynamically sized stack capable of holding `Value`.
|
2023-05-23 02:08:34 +02:00
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
pub fn Stack(comptime Value: type) type {
|
2023-05-23 02:08:34 +02:00
|
|
|
return struct {
|
2023-06-02 23:43:53 +02:00
|
|
|
capacity: usize = 0,
|
|
|
|
values: []Value = &.{},
|
2023-05-23 02:08:34 +02:00
|
|
|
|
2023-05-28 03:19:46 +02:00
|
|
|
///
|
|
|
|
/// Stack type.
|
|
|
|
///
|
2023-05-23 02:08:34 +02:00
|
|
|
const Self = @This();
|
|
|
|
|
2023-05-28 14:44:32 +02:00
|
|
|
///
|
|
|
|
/// Returns a [io.GrowableBuffer] bound to `self` and `allocator`.
|
|
|
|
///
|
|
|
|
/// The returned buffer may be used to write to the stack without needing to explicitly pass an allocator
|
|
|
|
/// context, as well decay further into a generic [io.Writer] type.
|
|
|
|
///
|
2023-06-02 23:43:53 +02:00
|
|
|
/// *Note* if `capacity` is a non-zero value, `allocator` must reference the same allocation strategy as the one
|
|
|
|
/// originally used to allocate the current internal buffer.
|
2023-05-28 14:44:32 +02:00
|
|
|
///
|
|
|
|
pub fn as_buffer(self: *Self, allocator: io.Allocator) io.GrowingBuffer {
|
|
|
|
return io.GrowingBuffer.bind(Self, allocator, self, push_all);
|
|
|
|
}
|
|
|
|
|
2023-05-23 02:08:34 +02:00
|
|
|
///
|
|
|
|
/// Clears all elements from `self` while preserving the current internal buffer.
|
|
|
|
///
|
|
|
|
/// To clean up memory allocations made by the stack and deinitialize it, see [deinit] instead.
|
|
|
|
///
|
|
|
|
pub fn clear(self: *Self) void {
|
|
|
|
self.values = self.values[0 .. 0];
|
|
|
|
}
|
|
|
|
|
|
|
|
///
|
|
|
|
/// Deinitializes `self` and sets it to an invalid state, freeing all memory allocated by `allocator`.
|
|
|
|
///
|
|
|
|
/// To clear all items from the stack while preserving the current internal buffer, see [clear] instead.
|
|
|
|
///
|
2023-06-02 23:43:53 +02:00
|
|
|
/// *Note* if the `capacity` field of `self` is a non-zero value, `allocator` must reference the same allocation
|
|
|
|
/// strategy as the one originally used to allocate the current internal buffer.
|
2023-05-23 02:08:34 +02:00
|
|
|
///
|
|
|
|
pub fn deinit(self: *Self, allocator: io.Allocator) void {
|
2023-06-02 23:43:53 +02:00
|
|
|
if (self.capacity == 0) {
|
|
|
|
return;
|
|
|
|
}
|
|
|
|
|
2023-06-04 03:34:21 +02:00
|
|
|
io.deallocate(allocator, self.values.ptr[0 .. self.capacity]);
|
2023-05-23 02:08:34 +02:00
|
|
|
|
2023-06-02 23:43:53 +02:00
|
|
|
self.values = &.{};
|
2023-05-23 02:08:34 +02:00
|
|
|
self.capacity = 0;
|
|
|
|
}
|
|
|
|
|
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
/// Attempts to remove `amount` number of `Value`s from the stack, returning `bool` if it was successful,
|
2023-05-23 02:08:34 +02:00
|
|
|
/// otherwise `false` if the stack contains fewer elements than `amount`.
|
|
|
|
///
|
|
|
|
pub fn drop(self: *Self, amount: usize) bool {
|
2023-05-28 03:19:46 +02:00
|
|
|
if (amount > self.values.len) {
|
|
|
|
return false;
|
|
|
|
}
|
2023-05-23 02:08:34 +02:00
|
|
|
|
|
|
|
self.values = self.values[0 .. self.values.len - amount];
|
|
|
|
|
|
|
|
return true;
|
|
|
|
}
|
|
|
|
|
|
|
|
///
|
|
|
|
/// Attempts to grow the internal buffer of `self` by `growth_amount` using `allocator`.
|
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
/// The function returns [io.AllocatorError] if `allocator` could not commit the memory required to grow the
|
2023-05-23 02:08:34 +02:00
|
|
|
/// internal buffer by `growth_amount`, leaving `self` in the same state that it was in prior to starting the
|
|
|
|
/// grow.
|
|
|
|
///
|
2023-06-03 21:55:59 +02:00
|
|
|
/// Growing ahead of multiple push operations is useful when the upper bound of pushes is well-understood, as it
|
|
|
|
/// can reduce the number of allocations required per push.
|
2023-05-23 02:08:34 +02:00
|
|
|
///
|
2023-06-02 23:43:53 +02:00
|
|
|
/// *Note* if the `capacity` field of `self` is a non-zero value, `allocator` must reference the same allocation
|
|
|
|
/// strategy as the one originally used to allocate the current internal buffer.
|
2023-05-23 02:08:34 +02:00
|
|
|
///
|
|
|
|
pub fn grow(self: *Self, allocator: io.Allocator, growth_amount: usize) io.AllocationError!void {
|
|
|
|
const grown_capacity = self.capacity + growth_amount;
|
2023-06-04 03:16:52 +02:00
|
|
|
const values = (try io.allocate_many(allocator, grown_capacity, Value))[0 .. self.values.len];
|
2023-05-23 02:08:34 +02:00
|
|
|
|
|
|
|
errdefer io.deallocate(allocator, values);
|
|
|
|
|
2023-06-02 23:43:53 +02:00
|
|
|
if (self.capacity != 0) {
|
|
|
|
for (0 .. self.values.len) |index| {
|
|
|
|
values[index] = self.values[index];
|
|
|
|
}
|
2023-05-23 02:08:34 +02:00
|
|
|
|
2023-06-04 03:16:52 +02:00
|
|
|
io.deallocate(allocator, self.values.ptr[0 .. self.capacity]);
|
2023-06-02 23:43:53 +02:00
|
|
|
}
|
2023-05-23 02:08:34 +02:00
|
|
|
|
|
|
|
self.values = values;
|
|
|
|
self.capacity = grown_capacity;
|
|
|
|
}
|
|
|
|
|
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
/// Attempts to remove the last element of `self` that was inserted, if one exists, returning it or `null` if
|
|
|
|
/// `self` is empty.
|
|
|
|
///
|
|
|
|
pub fn pop(self: *Self) ?Value {
|
|
|
|
if (self.values.len == 0) {
|
|
|
|
return null;
|
|
|
|
}
|
|
|
|
|
|
|
|
const last_index = self.values.len - 1;
|
|
|
|
|
|
|
|
defer self.values = self.values[0 .. last_index];
|
|
|
|
|
|
|
|
return self.values[last_index];
|
|
|
|
}
|
|
|
|
|
|
|
|
///
|
|
|
|
/// Attempts to push every `Value` in `values` to `self` using `allocator` to grow the internal buffer as
|
2023-05-23 02:08:34 +02:00
|
|
|
/// necessary.
|
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
/// The function returns [io.AllocationError] if `allocator` could not commit the memory required to grow the
|
2023-05-23 02:08:34 +02:00
|
|
|
/// internal buffer of `self` when necessary.
|
|
|
|
///
|
2023-06-02 23:43:53 +02:00
|
|
|
/// *Note* if the `capacity` field of `self` is a non-zero value, `allocator` must reference the same allocation
|
|
|
|
/// strategy as the one originally used to allocate the current internal buffer.
|
2023-05-23 02:08:34 +02:00
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
pub fn push_all(self: *Self, allocator: io.Allocator, values: []const Value) io.AllocationError!void {
|
2023-05-23 02:08:34 +02:00
|
|
|
const new_length = self.values.len + values.len;
|
|
|
|
|
2023-06-04 03:34:21 +02:00
|
|
|
if (new_length > self.capacity) {
|
2023-05-29 03:36:56 +02:00
|
|
|
try self.grow(allocator, values.len + values.len);
|
2023-05-23 02:08:34 +02:00
|
|
|
}
|
|
|
|
|
|
|
|
const offset_index = self.values.len;
|
|
|
|
|
|
|
|
self.values = self.values.ptr[0 .. new_length];
|
|
|
|
|
2023-05-28 03:19:46 +02:00
|
|
|
for (0 .. values.len) |index| {
|
|
|
|
self.values[offset_index + index] = values[index];
|
2023-05-23 02:08:34 +02:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
/// Attempts to push the `Value` in `value` to `self` by `amount` number of times using `allocator` to grow
|
2023-05-23 02:08:34 +02:00
|
|
|
/// the internal buffer as necessary.
|
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
/// The function returns [io.AllocationError] if `allocator` could not commit the memory required to grow the
|
2023-05-23 02:08:34 +02:00
|
|
|
/// internal buffer of `self` when necessary.
|
|
|
|
///
|
2023-06-02 23:43:53 +02:00
|
|
|
/// *Note* if the `capacity` field of `self` is a non-zero value, `allocator` must reference the same allocation
|
|
|
|
/// strategy as the one originally used to allocate the current internal buffer.
|
2023-05-23 02:08:34 +02:00
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
pub fn push_many(self: *Self, allocator: io.Allocator, value: Value, amount: usize) io.AllocationError!void {
|
2023-05-23 02:08:34 +02:00
|
|
|
const new_length = self.values.len + amount;
|
|
|
|
|
|
|
|
if (new_length >= self.capacity) {
|
2023-05-29 03:36:56 +02:00
|
|
|
try self.grow(allocator, amount + amount);
|
2023-05-23 02:08:34 +02:00
|
|
|
}
|
|
|
|
|
|
|
|
const offset_index = self.values.len;
|
|
|
|
|
|
|
|
self.values = self.values.ptr[0 .. new_length];
|
|
|
|
|
2023-05-28 03:19:46 +02:00
|
|
|
for (0 .. amount) |index| {
|
|
|
|
self.values[offset_index + index] = value;
|
2023-05-23 02:08:34 +02:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
/// Attempts to push the `Value` in `value` to `self` using `allocator` to grow the internal buffer as
|
2023-05-23 02:08:34 +02:00
|
|
|
/// necessary.
|
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
/// The function returns [io.AllocationError] if `allocator` could not commit the memory required to grow the
|
2023-05-23 02:08:34 +02:00
|
|
|
/// internal buffer of `self` when necessary.
|
|
|
|
///
|
2023-06-02 23:43:53 +02:00
|
|
|
/// *Note* if the `capacity` field of `self` is a non-zero value, `allocator` must reference the same allocation
|
|
|
|
/// strategy as the one originally used to allocate the current internal buffer.
|
2023-05-23 02:08:34 +02:00
|
|
|
///
|
2023-05-28 03:19:46 +02:00
|
|
|
pub fn push_one(self: *Self, allocator: io.Allocator, value: Value) io.AllocationError!void {
|
2023-05-23 02:08:34 +02:00
|
|
|
if (self.values.len == self.capacity) {
|
|
|
|
try self.grow(allocator, math.max(1, self.capacity));
|
|
|
|
}
|
|
|
|
|
|
|
|
const offset_index = self.values.len;
|
|
|
|
|
|
|
|
self.values = self.values.ptr[0 .. self.values.len + 1];
|
|
|
|
|
|
|
|
self.values[offset_index] = value;
|
|
|
|
}
|
|
|
|
};
|
|
|
|
}
|