authorgravatar for 4678790+dweiller@users.noreply.github.comDominic <4678790+dweiller@users.noreply.github.com> 2023-01-27 23:50:23+11:00
committergravatar for 4678790+dweiller@users.noreply.github.comDominic <4678790+dweiller@users.noreply.github.com> 2023-02-20 09:09:06+11:00
log3c06e2e7d0de92c0674c16ae23e1462a3acbe718
tree37236bb1ab40749476159229bc992a72c3456fa7
parent1e5b8be5099d976628aaa3fc4208a0bbd45c7700

std.compress.zstandard: add doc comments for RingBuffer

1 files changed, 25 insertions(+), 4 deletions(-)

lib/std/compress/zstandard/RingBuffer.zig+25-4
...@@ -1,8 +1,8 @@...@@ -1,8 +1,8 @@
1//! This ring buffer stores read and write indices while being able to utilise the full1//! This ring buffer stores read and write indices while being able to utilise the full
2//! backing slice by incrementing the indices modulo twice the slice's length and reducing2//! backing slice by incrementing the indices modulo twice the slice's length and reducing
3//! indices modulo the slice's length on slice access. This means that the bit of information3//! indices modulo the slice's length on slice access. This means that whether the ring buffer
4//! distinguishing whether the buffer is full or empty in an implementation utilising4//! if full or empty can be distinguised by looking at the different between the read and write
5//! and extra flag is stored in difference of the indices.5//! indices without adding an extra boolean flag or having to reserve a slot in the buffer.
66
7const assert = @import("std").debug.assert;7const assert = @import("std").debug.assert;
88
...@@ -12,33 +12,45 @@ data: []u8,...@@ -12,33 +12,45 @@ data: []u8,
12read_index: usize,12read_index: usize,
13write_index: usize,13write_index: usize,
1414
15/// Returns `index` modulo the length of the backing slice.
15pub fn mask(self: RingBuffer, index: usize) usize {16pub fn mask(self: RingBuffer, index: usize) usize {
16 return index % self.data.len;17 return index % self.data.len;
17}18}
1819
20/// Returns `index` module twice the length of the backing slice.
19pub fn mask2(self: RingBuffer, index: usize) usize {21pub fn mask2(self: RingBuffer, index: usize) usize {
20 return index % (2 * self.data.len);22 return index % (2 * self.data.len);
21}23}
2224
25/// Write `byte` into the ring buffer. Returns `error.Full` if the ring
26/// buffer is full.
23pub fn write(self: *RingBuffer, byte: u8) !void {27pub fn write(self: *RingBuffer, byte: u8) !void {
24 if (self.isFull()) return error.Full;28 if (self.isFull()) return error.Full;
25 self.writeAssumeCapacity(byte);29 self.writeAssumeCapacity(byte);
26}30}
2731
32/// Write `byte` into the ring buffer. If the ring buffer is full, the
33/// oldest byte is overwritten.
28pub fn writeAssumeCapacity(self: *RingBuffer, byte: u8) void {34pub fn writeAssumeCapacity(self: *RingBuffer, byte: u8) void {
29 self.data[self.mask(self.write_index)] = byte;35 self.data[self.mask(self.write_index)] = byte;
30 self.write_index = self.mask2(self.write_index + 1);36 self.write_index = self.mask2(self.write_index + 1);
31}37}
3238
39/// Write `bytes` into the ring bufffer. Returns `error.Full` if the ring
40/// buffer does not have enough space, without writing any data.
33pub fn writeSlice(self: *RingBuffer, bytes: []const u8) !void {41pub fn writeSlice(self: *RingBuffer, bytes: []const u8) !void {
34 if (self.len() + bytes.len > self.data.len) return error.Full;42 if (self.len() + bytes.len > self.data.len) return error.Full;
35 self.writeSliceAssumeCapacity(bytes);43 self.writeSliceAssumeCapacity(bytes);
36}44}
3745
46/// Write `bytes` into the ring buffer. If there is not enough space, older
47/// bytes will be overwritten.
38pub fn writeSliceAssumeCapacity(self: *RingBuffer, bytes: []const u8) void {48pub fn writeSliceAssumeCapacity(self: *RingBuffer, bytes: []const u8) void {
39 for (bytes) |b| self.writeAssumeCapacity(b);49 for (bytes) |b| self.writeAssumeCapacity(b);
40}50}
4151
52/// Consume a byte from the ring buffer and return it. Returns `null` if the
53/// ring buffer is empty.
42pub fn read(self: *RingBuffer) ?u8 {54pub fn read(self: *RingBuffer) ?u8 {
43 if (self.isEmpty()) return null;55 if (self.isEmpty()) return null;
44 const byte = self.data[self.mask(self.read_index)];56 const byte = self.data[self.mask(self.read_index)];
...@@ -46,24 +58,32 @@ pub fn read(self: *RingBuffer) ?u8 {...@@ -46,24 +58,32 @@ pub fn read(self: *RingBuffer) ?u8 {
46 return byte;58 return byte;
47}59}
4860
61/// Returns `true` if the ring buffer is empty and `false` otherwise.
49pub fn isEmpty(self: RingBuffer) bool {62pub fn isEmpty(self: RingBuffer) bool {
50 return self.write_index == self.read_index;63 return self.write_index == self.read_index;
51}64}
5265
66/// Returns `true` if the ring buffer is full and `false` otherwise.
53pub fn isFull(self: RingBuffer) bool {67pub fn isFull(self: RingBuffer) bool {
54 return self.mask2(self.write_index + self.data.len) == self.read_index;68 return self.mask2(self.write_index + self.data.len) == self.read_index;
55}69}
5670
71/// Returns the length
57pub fn len(self: RingBuffer) usize {72pub fn len(self: RingBuffer) usize {
58 const adjusted_write_index = self.write_index + @boolToInt(self.write_index < self.read_index) * 2 * self.data.len;73 const adjusted_write_index = self.write_index + @boolToInt(self.write_index < self.read_index) * 2 * self.data.len;
59 return adjusted_write_index - self.read_index;74 return adjusted_write_index - self.read_index;
60}75}
6176
62const Slice = struct {77/// A `Slice` represents a region of a ring buffer. The region is split into two
78/// sections as the ring buffer data will not be contiguous if the desired region
79/// wraps to the start of the backing slice.
80pub const Slice = struct {
63 first: []u8,81 first: []u8,
64 second: []u8,82 second: []u8,
65};83};
6684
85/// Returns a `Slice` for the region of the ring buffer staring at `self.mask(start_unmasked)`
86/// with the specified length.
67pub fn sliceAt(self: RingBuffer, start_unmasked: usize, length: usize) Slice {87pub fn sliceAt(self: RingBuffer, start_unmasked: usize, length: usize) Slice {
68 assert(length <= self.data.len);88 assert(length <= self.data.len);
69 const slice1_start = self.mask(start_unmasked);89 const slice1_start = self.mask(start_unmasked);
...@@ -76,6 +96,7 @@ pub fn sliceAt(self: RingBuffer, start_unmasked: usize, length: usize) Slice {...@@ -76,6 +96,7 @@ pub fn sliceAt(self: RingBuffer, start_unmasked: usize, length: usize) Slice {
76 };96 };
77}97}
7898
99/// Returns a `Slice` for the last `length` bytes written to the ring buffer.
79pub fn sliceLast(self: RingBuffer, length: usize) Slice {100pub fn sliceLast(self: RingBuffer, length: usize) Slice {
80 return self.sliceAt(self.write_index + self.data.len - length, length);101 return self.sliceAt(self.write_index + self.data.len - length, length);
81}102}