authorgravatar for igor.anic@gmail.comIgor Anić <igor.anic@gmail.com> 2024-02-14 18:24:40+01:00
committergravatar for igor.anic@gmail.comIgor Anić <igor.anic@gmail.com> 2024-02-14 18:28:20+01:00
logc2361bf54808da49393e892b81bdff45c68c4c51
tree0cf75f67f23f46982126004db7676ac77748e851
parent5fbc371b418ff51c3681e29d8ec3f53b78bd8a59

fix top level docs comments

I didn't understand the difference. ref: https://ziglang.org/documentation/0.11.0/#Comments

5 files changed, 102 insertions(+), 101 deletions(-)

lib/std/compress/flate/CircularBuffer.zig+28-28
......@@ -1,18 +1,18 @@
1/// 64K buffer of uncompressed data created in inflate (decompression). Has enough
2/// history to support writing match<length, distance>; copying length of bytes
3/// from the position distance backward from current.
4///
5/// Reads can return less than available bytes if they are spread across
6/// different circles. So reads should repeat until get required number of bytes
7/// or until returned slice is zero length.
8///
9/// Note on deflate limits:
10/// * non-compressible block is limited to 65,535 bytes.
11/// * backward pointer is limited in distance to 32K bytes and in length to 258 bytes.
12///
13/// Whole non-compressed block can be written without overlap. We always have
14/// history of up to 64K, more then 32K needed.
15///
1//! 64K buffer of uncompressed data created in inflate (decompression). Has enough
2//! history to support writing match<length, distance>; copying length of bytes
3//! from the position distance backward from current.
4//!
5//! Reads can return less than available bytes if they are spread across
6//! different circles. So reads should repeat until get required number of bytes
7//! or until returned slice is zero length.
8//!
9//! Note on deflate limits:
10//! * non-compressible block is limited to 65,535 bytes.
11//! * backward pointer is limited in distance to 32K bytes and in length to 258 bytes.
12//!
13//! Whole non-compressed block can be written without overlap. We always have
14//! history of up to 64K, more then 32K needed.
15//!
1616const std = @import("std");
1717const assert = std.debug.assert;
1818const testing = std.testing;
......@@ -32,15 +32,15 @@ fn writeAll(self: *Self, buf: []const u8) void {
3232 for (buf) |c| self.write(c);
3333}
3434
35// Write literal.
35/// Write literal.
3636pub fn write(self: *Self, b: u8) void {
3737 assert(self.wp - self.rp < mask);
3838 self.buffer[self.wp & mask] = b;
3939 self.wp += 1;
4040}
4141
42// Write match (back-reference to the same data slice) starting at `distance`
43// back from current write position, and `length` of bytes.
42/// Write match (back-reference to the same data slice) starting at `distance`
43/// back from current write position, and `length` of bytes.
4444pub fn writeMatch(self: *Self, length: u16, distance: u16) !void {
4545 if (self.wp < distance or
4646 length < consts.base_length or length > consts.max_length or
......@@ -74,8 +74,8 @@ pub fn writeMatch(self: *Self, length: u16, distance: u16) !void {
7474 }
7575}
7676
77// Returns writable part of the internal buffer of size `n` at most. Advances
78// write pointer, assumes that returned buffer will be filled with data.
77/// Returns writable part of the internal buffer of size `n` at most. Advances
78/// write pointer, assumes that returned buffer will be filled with data.
7979pub fn getWritable(self: *Self, n: usize) []u8 {
8080 const wp = self.wp & mask;
8181 const len = @min(n, buffer_len - wp);
......@@ -83,14 +83,14 @@ pub fn getWritable(self: *Self, n: usize) []u8 {
8383 return self.buffer[wp .. wp + len];
8484}
8585
86// Read available data. Can return part of the available data if it is
87// spread across two circles. So read until this returns zero length.
86/// Read available data. Can return part of the available data if it is
87/// spread across two circles. So read until this returns zero length.
8888pub fn read(self: *Self) []const u8 {
8989 return self.readAtMost(buffer_len);
9090}
9191
92// Read part of available data. Can return less than max even if there are
93// more than max decoded data.
92/// Read part of available data. Can return less than max even if there are
93/// more than max decoded data.
9494pub fn readAtMost(self: *Self, limit: usize) []const u8 {
9595 const rb = self.readBlock(if (limit == 0) buffer_len else limit);
9696 defer self.rp += rb.len;
......@@ -103,7 +103,7 @@ const ReadBlock = struct {
103103 len: usize,
104104};
105105
106// Returns position of continous read block data.
106/// Returns position of continous read block data.
107107fn readBlock(self: *Self, max: usize) ReadBlock {
108108 const r = self.rp & mask;
109109 const w = self.wp & mask;
......@@ -118,13 +118,13 @@ fn readBlock(self: *Self, max: usize) ReadBlock {
118118 };
119119}
120120
121// Number of free bytes for write.
121/// Number of free bytes for write.
122122pub fn free(self: *Self) usize {
123123 return buffer_len - (self.wp - self.rp);
124124}
125125
126// Full if largest match can't fit. 258 is largest match length. That much bytes
127// can be produced in single decode step.
126/// Full if largest match can't fit. 258 is largest match length. That much
127/// bytes can be produced in single decode step.
128128pub fn full(self: *Self) bool {
129129 return self.free() < 258 + 1;
130130}
lib/std/compress/flate/SlidingWindow.zig+23-23
......@@ -1,6 +1,6 @@
1/// Used in deflate (compression), holds uncompressed data form which Tokens are
2/// produces. In combination with Lookup it is used to find matches in history data.
3///
1//! Used in deflate (compression), holds uncompressed data form which Tokens are
2//! produces. In combination with Lookup it is used to find matches in history data.
3//!
44const std = @import("std");
55const consts = @import("consts.zig");
66
......@@ -20,7 +20,7 @@ wp: usize = 0, // write position
2020rp: usize = 0, // read position
2121fp: isize = 0, // last flush position, tokens are build from fp..rp
2222
23// Returns number of bytes written, or 0 if buffer is full and need to slide.
23/// Returns number of bytes written, or 0 if buffer is full and need to slide.
2424pub fn write(self: *Self, buf: []const u8) usize {
2525 if (self.rp >= max_rp) return 0; // need to slide
2626
......@@ -30,9 +30,9 @@ pub fn write(self: *Self, buf: []const u8) usize {
3030 return n;
3131}
3232
33// Slide buffer for hist_len.
34// Drops old history, preserves between hist_len and hist_len - min_lookahead.
35// Returns number of bytes removed.
33/// Slide buffer for hist_len.
34/// Drops old history, preserves between hist_len and hist_len - min_lookahead.
35/// Returns number of bytes removed.
3636pub fn slide(self: *Self) u16 {
3737 assert(self.rp >= max_rp and self.wp >= self.rp);
3838 const n = self.wp - hist_len;
......@@ -43,41 +43,41 @@ pub fn slide(self: *Self) u16 {
4343 return @intCast(n);
4444}
4545
46// Data from the current position (read position). Those part of the buffer is
47// not converted to tokens yet.
46/// Data from the current position (read position). Those part of the buffer is
47/// not converted to tokens yet.
4848fn lookahead(self: *Self) []const u8 {
4949 assert(self.wp >= self.rp);
5050 return self.buffer[self.rp..self.wp];
5151}
5252
53// Returns part of the lookahead buffer. If should_flush is set no lookahead is
54// preserved otherwise preserves enough data for the longest match. Returns
55// null if there is not enough data.
53/// Returns part of the lookahead buffer. If should_flush is set no lookahead is
54/// preserved otherwise preserves enough data for the longest match. Returns
55/// null if there is not enough data.
5656pub fn activeLookahead(self: *Self, should_flush: bool) ?[]const u8 {
5757 const min: usize = if (should_flush) 0 else min_lookahead;
5858 const lh = self.lookahead();
5959 return if (lh.len > min) lh else null;
6060}
6161
62// Advances read position, shrinks lookahead.
62/// Advances read position, shrinks lookahead.
6363pub fn advance(self: *Self, n: u16) void {
6464 assert(self.wp >= self.rp + n);
6565 self.rp += n;
6666}
6767
68// Returns writable part of the buffer, where new uncompressed data can be
69// written.
68/// Returns writable part of the buffer, where new uncompressed data can be
69/// written.
7070pub fn writable(self: *Self) []u8 {
7171 return self.buffer[self.wp..];
7272}
7373
74// Notification of what part of writable buffer is filled with data.
74/// Notification of what part of writable buffer is filled with data.
7575pub fn written(self: *Self, n: usize) void {
7676 self.wp += n;
7777}
7878
79// Finds match length between previous and current position.
80// Used in hot path!
79/// Finds match length between previous and current position.
80/// Used in hot path!
8181pub fn match(self: *Self, prev_pos: u16, curr_pos: u16, min_len: u16) u16 {
8282 const max_len: usize = @min(self.wp - curr_pos, consts.match.max_length);
8383 // lookahead buffers from previous and current positions
......@@ -103,19 +103,19 @@ pub fn match(self: *Self, prev_pos: u16, curr_pos: u16, min_len: u16) u16 {
103103 return if (i >= consts.match.min_length) @intCast(i) else 0;
104104}
105105
106// Current position of non-compressed data. Data before rp are already converted
107// to tokens.
106/// Current position of non-compressed data. Data before rp are already converted
107/// to tokens.
108108pub fn pos(self: *Self) u16 {
109109 return @intCast(self.rp);
110110}
111111
112// Notification that token list is cleared.
112/// Notification that token list is cleared.
113113pub fn flush(self: *Self) void {
114114 self.fp = @intCast(self.rp);
115115}
116116
117// Part of the buffer since last flush or null if there was slide in between (so
118// fp becomes negative).
117/// Part of the buffer since last flush or null if there was slide in between (so
118/// fp becomes negative).
119119pub fn tokensBuffer(self: *Self) ?[]const u8 {
120120 assert(self.fp <= self.rp);
121121 if (self.fp < 0) return null;
lib/std/compress/flate/Token.zig+4-4
......@@ -1,7 +1,7 @@
1/// Token cat be literal: single byte of data or match; reference to the slice of
2/// data in the same stream represented with <length, distance>. Where length
3/// can be 3 - 258 bytes, and distance 1 - 32768 bytes.
4///
1//! Token cat be literal: single byte of data or match; reference to the slice of
2//! data in the same stream represented with <length, distance>. Where length
3//! can be 3 - 258 bytes, and distance 1 - 32768 bytes.
4//!
55const std = @import("std");
66const assert = std.debug.assert;
77const print = std.debug.print;
lib/std/compress/flate/bit_reader.zig+32-32
......@@ -34,15 +34,15 @@ pub fn BitReader(comptime ReaderType: type) type {
3434 return self;
3535 }
3636
37 // Try to have `nice` bits are available in buffer. Reads from
38 // forward reader if there is no `nice` bits in buffer. Returns error
39 // if end of forward stream is reached and internal buffer is empty.
40 // It will not error if less than `nice` bits are in buffer, only when
41 // all bits are exhausted. During inflate we usually know what is the
42 // maximum bits for the next step but usually that step will need less
43 // bits to decode. So `nice` is not hard limit, it will just try to have
44 // that number of bits available. If end of forward stream is reached
45 // it may be some extra zero bits in buffer.
37 /// Try to have `nice` bits are available in buffer. Reads from
38 /// forward reader if there is no `nice` bits in buffer. Returns error
39 /// if end of forward stream is reached and internal buffer is empty.
40 /// It will not error if less than `nice` bits are in buffer, only when
41 /// all bits are exhausted. During inflate we usually know what is the
42 /// maximum bits for the next step but usually that step will need less
43 /// bits to decode. So `nice` is not hard limit, it will just try to have
44 /// that number of bits available. If end of forward stream is reached
45 /// it may be some extra zero bits in buffer.
4646 pub inline fn fill(self: *Self, nice: u6) !void {
4747 if (self.nbits >= nice) {
4848 return; // We have enought bits
......@@ -67,7 +67,7 @@ pub fn BitReader(comptime ReaderType: type) type {
6767 return error.EndOfStream;
6868 }
6969
70 // Read exactly buf.len bytes into buf.
70 /// Read exactly buf.len bytes into buf.
7171 pub fn readAll(self: *Self, buf: []u8) !void {
7272 assert(self.alignBits() == 0); // internal bits must be at byte boundary
7373
......@@ -87,17 +87,17 @@ pub fn BitReader(comptime ReaderType: type) type {
8787 pub const reverse: u3 = 0b100; // bit reverse readed bits
8888 };
8989
90 // Alias for readF(U, 0).
90 /// Alias for readF(U, 0).
9191 pub fn read(self: *Self, comptime U: type) !U {
9292 return self.readF(U, 0);
9393 }
9494
95 // Alias for readF with flag.peak set.
95 /// Alias for readF with flag.peak set.
9696 pub inline fn peekF(self: *Self, comptime U: type, comptime how: u3) !U {
9797 return self.readF(U, how | flag.peek);
9898 }
9999
100 // Read with flags provided.
100 /// Read with flags provided.
101101 pub fn readF(self: *Self, comptime U: type, comptime how: u3) !U {
102102 const n: u6 = @bitSizeOf(U);
103103 switch (how) {
......@@ -140,8 +140,8 @@ pub fn BitReader(comptime ReaderType: type) type {
140140 }
141141 }
142142
143 // Read n number of bits.
144 // Only buffered flag can be used in how.
143 /// Read n number of bits.
144 /// Only buffered flag can be used in how.
145145 pub fn readN(self: *Self, n: u4, comptime how: u3) !u16 {
146146 switch (how) {
147147 0 => {
......@@ -156,14 +156,14 @@ pub fn BitReader(comptime ReaderType: type) type {
156156 return u;
157157 }
158158
159 // Advance buffer for n bits.
159 /// Advance buffer for n bits.
160160 pub fn shift(self: *Self, n: u6) !void {
161161 if (n > self.nbits) return error.EndOfStream;
162162 self.bits >>= n;
163163 self.nbits -= n;
164164 }
165165
166 // Skip n bytes.
166 /// Skip n bytes.
167167 pub fn skipBytes(self: *Self, n: u16) !void {
168168 for (0..n) |_| {
169169 try self.fill(8);
......@@ -176,32 +176,32 @@ pub fn BitReader(comptime ReaderType: type) type {
176176 return @intCast(self.nbits & 0x7);
177177 }
178178
179 // Align stream to the byte boundary.
179 /// Align stream to the byte boundary.
180180 pub fn alignToByte(self: *Self) void {
181181 const ab = self.alignBits();
182182 if (ab > 0) self.shift(ab) catch unreachable;
183183 }
184184
185 // Skip zero terminated string.
185 /// Skip zero terminated string.
186186 pub fn skipStringZ(self: *Self) !void {
187187 while (true) {
188188 if (try self.readF(u8, 0) == 0) break;
189189 }
190190 }
191191
192 // Read deflate fixed fixed code.
193 // Reads first 7 bits, and then mybe 1 or 2 more to get full 7,8 or 9 bit code.
194 // ref: https://datatracker.ietf.org/doc/html/rfc1951#page-12
195 // Lit Value Bits Codes
196 // --------- ---- -----
197 // 0 - 143 8 00110000 through
198 // 10111111
199 // 144 - 255 9 110010000 through
200 // 111111111
201 // 256 - 279 7 0000000 through
202 // 0010111
203 // 280 - 287 8 11000000 through
204 // 11000111
192 /// Read deflate fixed fixed code.
193 /// Reads first 7 bits, and then mybe 1 or 2 more to get full 7,8 or 9 bit code.
194 /// ref: https://datatracker.ietf.org/doc/html/rfc1951#page-12
195 /// Lit Value Bits Codes
196 /// --------- ---- -----
197 /// 0 - 143 8 00110000 through
198 /// 10111111
199 /// 144 - 255 9 110010000 through
200 /// 111111111
201 /// 256 - 279 7 0000000 through
202 /// 0010111
203 /// 280 - 287 8 11000000 through
204 /// 11000111
205205 pub fn readFixedCode(self: *Self) !u16 {
206206 try self.fill(7 + 2);
207207 const code7 = try self.readF(u7, flag.buffered | flag.reverse);
lib/std/compress/flate/container.zig+15-14
......@@ -1,19 +1,20 @@
1//! Container of the deflate bit stream body. Container adds header before
2//! deflate bit stream and footer after. It can bi gzip, zlib or raw (no header,
3//! no footer, raw bit stream).
4//!
5//! Zlib format is defined in rfc 1950. Header has 2 bytes and footer 4 bytes
6//! addler 32 checksum.
7//!
8//! Gzip format is defined in rfc 1952. Header has 10+ bytes and footer 4 bytes
9//! crc32 checksum and 4 bytes of uncompressed data length.
10//!
11//!
12//! rfc 1950: https://datatracker.ietf.org/doc/html/rfc1950#page-4
13//! rfc 1952: https://datatracker.ietf.org/doc/html/rfc1952#page-5
14//!
15
116const std = @import("std");
217
3/// Container of the deflate bit stream body. Container adds header before
4/// deflate bit stream and footer after. It can bi gzip, zlib or raw (no header,
5/// no footer, raw bit stream).
6///
7/// Zlib format is defined in rfc 1950. Header has 2 bytes and footer 4 bytes
8/// addler 32 checksum.
9///
10/// Gzip format is defined in rfc 1952. Header has 10+ bytes and footer 4 bytes
11/// crc32 checksum and 4 bytes of uncompressed data length.
12///
13///
14/// rfc 1950: https://datatracker.ietf.org/doc/html/rfc1950#page-4
15/// rfc 1952: https://datatracker.ietf.org/doc/html/rfc1952#page-5
16///
1718pub const Container = enum {
1819 raw, // no header or footer
1920 gzip, // gzip header and footer