authorgravatar for 4678790+dweiller@users.noreply.github.comDominic <4678790+dweiller@users.noreply.github.com> 2024-03-10 18:13:53+11:00
committergravatar for 4678790+dweiller@users.noreply.github.comDominic <4678790+dweiller@users.noreply.github.com> 2024-03-10 18:13:53+11:00
logd942096a448d70f7dd8be747c120df8f10c6c723
tree14a5342dfcc1863c108b52e2d39169f0bfc180e6
parent4ba4f94c93d5eb1945f1b2c8c53a45cbee609d3b

std.RingBuffer: improve doc comments and assertions

1 files changed, 5 insertions(+), 1 deletions(-)

lib/std/RingBuffer.zig+5-1
...@@ -74,6 +74,7 @@ pub fn writeSlice(self: *RingBuffer, bytes: []const u8) Error!void {...@@ -74,6 +74,7 @@ pub fn writeSlice(self: *RingBuffer, bytes: []const u8) Error!void {
74/// bytes will be overwritten.74/// bytes will be overwritten.
75/// Uses memcpy and so `bytes` must not overlap ring buffer data.75/// Uses memcpy and so `bytes` must not overlap ring buffer data.
76pub fn writeSliceAssumeCapacity(self: *RingBuffer, bytes: []const u8) void {76pub fn writeSliceAssumeCapacity(self: *RingBuffer, bytes: []const u8) void {
77 assert(bytes.len <= self.data.len);
77 const data_start = self.mask(self.write_index);78 const data_start = self.mask(self.write_index);
78 const part1_data_end = @min(data_start + bytes.len, self.data.len);79 const part1_data_end = @min(data_start + bytes.len, self.data.len);
79 const part1_len = part1_data_end - data_start;80 const part1_len = part1_data_end - data_start;
...@@ -104,6 +105,7 @@ pub fn writeSliceForwards(self: *RingBuffer, bytes: []const u8) Error!void {...@@ -104,6 +105,7 @@ pub fn writeSliceForwards(self: *RingBuffer, bytes: []const u8) Error!void {
104/// bytes will be overwritten.105/// bytes will be overwritten.
105/// Uses copyForwards and can write slices from this RingBuffer into itself.106/// Uses copyForwards and can write slices from this RingBuffer into itself.
106pub fn writeSliceForwardsAssumeCapacity(self: *RingBuffer, bytes: []const u8) void {107pub fn writeSliceForwardsAssumeCapacity(self: *RingBuffer, bytes: []const u8) void {
108 assert(bytes.len <= self.data.len);
107 const data_start = self.mask(self.write_index);109 const data_start = self.mask(self.write_index);
108 const part1_data_end = @min(data_start + bytes.len, self.data.len);110 const part1_data_end = @min(data_start + bytes.len, self.data.len);
109 const part1_len = part1_data_end - data_start;111 const part1_len = part1_data_end - data_start;
...@@ -160,6 +162,7 @@ pub fn readFirstAssumeLength(self: *RingBuffer, dest: []u8, length: usize) void...@@ -160,6 +162,7 @@ pub fn readFirstAssumeLength(self: *RingBuffer, dest: []u8, length: usize) void
160/// Reads last `length` bytes written to the ring buffer into `dest`; Returns162/// Reads last `length` bytes written to the ring buffer into `dest`; Returns
161/// Error.ReadLengthInvalid if length greater than ring or dest length163/// Error.ReadLengthInvalid if length greater than ring or dest length
162/// Uses memcpy and so `dest` must not overlap ring buffer data.164/// Uses memcpy and so `dest` must not overlap ring buffer data.
165/// Reduces write index by `length`.
163pub fn readLast(self: *RingBuffer, dest: []u8, length: usize) Error!void {166pub fn readLast(self: *RingBuffer, dest: []u8, length: usize) Error!void {
164 if (length > self.len() or length > dest.len) return error.ReadLengthInvalid;167 if (length > self.len() or length > dest.len) return error.ReadLengthInvalid;
165 self.readLastAssumeLength(dest, length);168 self.readLastAssumeLength(dest, length);
...@@ -168,6 +171,7 @@ pub fn readLast(self: *RingBuffer, dest: []u8, length: usize) Error!void {...@@ -168,6 +171,7 @@ pub fn readLast(self: *RingBuffer, dest: []u8, length: usize) Error!void {
168/// Reads last `length` bytes written to the ring buffer into `dest`;171/// Reads last `length` bytes written to the ring buffer into `dest`;
169/// Asserts that length not greater than ring buffer or dest length172/// Asserts that length not greater than ring buffer or dest length
170/// Uses memcpy and so `dest` must not overlap ring buffer data.173/// Uses memcpy and so `dest` must not overlap ring buffer data.
174/// Reduces write index by `length`.
171pub fn readLastAssumeLength(self: *RingBuffer, dest: []u8, length: usize) void {175pub fn readLastAssumeLength(self: *RingBuffer, dest: []u8, length: usize) void {
172 assert(length <= self.len() and length <= dest.len);176 assert(length <= self.len() and length <= dest.len);
173 const data_start = self.mask(self.write_index + self.data.len - length);177 const data_start = self.mask(self.write_index + self.data.len - length);
...@@ -189,7 +193,7 @@ pub fn isFull(self: RingBuffer) bool {...@@ -189,7 +193,7 @@ pub fn isFull(self: RingBuffer) bool {
189 return self.mask2(self.write_index + self.data.len) == self.read_index;193 return self.mask2(self.write_index + self.data.len) == self.read_index;
190}194}
191195
192/// Returns the length196/// Returns the length of data available for reading
193pub fn len(self: RingBuffer) usize {197pub fn len(self: RingBuffer) usize {
194 const wrap_offset = 2 * self.data.len * @intFromBool(self.write_index < self.read_index);198 const wrap_offset = 2 * self.data.len * @intFromBool(self.write_index < self.read_index);
195 const adjusted_write_index = self.write_index + wrap_offset;199 const adjusted_write_index = self.write_index + wrap_offset;