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,18 +1,18 @@
1/// 64K buffer of uncompressed data created in inflate (decompression). Has enough1//! 64K buffer of uncompressed data created in inflate (decompression). Has enough
2/// history to support writing match<length, distance>; copying length of bytes2//! history to support writing match<length, distance>; copying length of bytes
3/// from the position distance backward from current.3//! from the position distance backward from current.
4///4//!
5/// Reads can return less than available bytes if they are spread across5//! Reads can return less than available bytes if they are spread across
6/// different circles. So reads should repeat until get required number of bytes6//! different circles. So reads should repeat until get required number of bytes
7/// or until returned slice is zero length.7//! or until returned slice is zero length.
8///8//!
9/// Note on deflate limits:9//! Note on deflate limits:
10/// * non-compressible block is limited to 65,535 bytes.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.11//! * backward pointer is limited in distance to 32K bytes and in length to 258 bytes.
12///12//!
13/// Whole non-compressed block can be written without overlap. We always have13//! Whole non-compressed block can be written without overlap. We always have
14/// history of up to 64K, more then 32K needed.14//! history of up to 64K, more then 32K needed.
15///15//!
16const std = @import("std");16const std = @import("std");
17const assert = std.debug.assert;17const assert = std.debug.assert;
18const testing = std.testing;18const testing = std.testing;
...@@ -32,15 +32,15 @@ fn writeAll(self: *Self, buf: []const u8) void {...@@ -32,15 +32,15 @@ fn writeAll(self: *Self, buf: []const u8) void {
32 for (buf) |c| self.write(c);32 for (buf) |c| self.write(c);
33}33}
3434
35// Write literal.35/// Write literal.
36pub fn write(self: *Self, b: u8) void {36pub fn write(self: *Self, b: u8) void {
37 assert(self.wp - self.rp < mask);37 assert(self.wp - self.rp < mask);
38 self.buffer[self.wp & mask] = b;38 self.buffer[self.wp & mask] = b;
39 self.wp += 1;39 self.wp += 1;
40}40}
4141
42// Write match (back-reference to the same data slice) starting at `distance`42/// Write match (back-reference to the same data slice) starting at `distance`
43// back from current write position, and `length` of bytes.43/// back from current write position, and `length` of bytes.
44pub fn writeMatch(self: *Self, length: u16, distance: u16) !void {44pub fn writeMatch(self: *Self, length: u16, distance: u16) !void {
45 if (self.wp < distance or45 if (self.wp < distance or
46 length < consts.base_length or length > consts.max_length or46 length < consts.base_length or length > consts.max_length or
...@@ -74,8 +74,8 @@ pub fn writeMatch(self: *Self, length: u16, distance: u16) !void {...@@ -74,8 +74,8 @@ pub fn writeMatch(self: *Self, length: u16, distance: u16) !void {
74 }74 }
75}75}
7676
77// Returns writable part of the internal buffer of size `n` at most. Advances77/// 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.78/// write pointer, assumes that returned buffer will be filled with data.
79pub fn getWritable(self: *Self, n: usize) []u8 {79pub fn getWritable(self: *Self, n: usize) []u8 {
80 const wp = self.wp & mask;80 const wp = self.wp & mask;
81 const len = @min(n, buffer_len - wp);81 const len = @min(n, buffer_len - wp);
...@@ -83,14 +83,14 @@ pub fn getWritable(self: *Self, n: usize) []u8 {...@@ -83,14 +83,14 @@ pub fn getWritable(self: *Self, n: usize) []u8 {
83 return self.buffer[wp .. wp + len];83 return self.buffer[wp .. wp + len];
84}84}
8585
86// Read available data. Can return part of the available data if it is86/// 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.87/// spread across two circles. So read until this returns zero length.
88pub fn read(self: *Self) []const u8 {88pub fn read(self: *Self) []const u8 {
89 return self.readAtMost(buffer_len);89 return self.readAtMost(buffer_len);
90}90}
9191
92// Read part of available data. Can return less than max even if there are92/// Read part of available data. Can return less than max even if there are
93// more than max decoded data.93/// more than max decoded data.
94pub fn readAtMost(self: *Self, limit: usize) []const u8 {94pub fn readAtMost(self: *Self, limit: usize) []const u8 {
95 const rb = self.readBlock(if (limit == 0) buffer_len else limit);95 const rb = self.readBlock(if (limit == 0) buffer_len else limit);
96 defer self.rp += rb.len;96 defer self.rp += rb.len;
...@@ -103,7 +103,7 @@ const ReadBlock = struct {...@@ -103,7 +103,7 @@ const ReadBlock = struct {
103 len: usize,103 len: usize,
104};104};
105105
106// Returns position of continous read block data.106/// Returns position of continous read block data.
107fn readBlock(self: *Self, max: usize) ReadBlock {107fn readBlock(self: *Self, max: usize) ReadBlock {
108 const r = self.rp & mask;108 const r = self.rp & mask;
109 const w = self.wp & mask;109 const w = self.wp & mask;
...@@ -118,13 +118,13 @@ fn readBlock(self: *Self, max: usize) ReadBlock {...@@ -118,13 +118,13 @@ fn readBlock(self: *Self, max: usize) ReadBlock {
118 };118 };
119}119}
120120
121// Number of free bytes for write.121/// Number of free bytes for write.
122pub fn free(self: *Self) usize {122pub fn free(self: *Self) usize {
123 return buffer_len - (self.wp - self.rp);123 return buffer_len - (self.wp - self.rp);
124}124}
125125
126// Full if largest match can't fit. 258 is largest match length. That much bytes126/// Full if largest match can't fit. 258 is largest match length. That much
127// can be produced in single decode step.127/// bytes can be produced in single decode step.
128pub fn full(self: *Self) bool {128pub fn full(self: *Self) bool {
129 return self.free() < 258 + 1;129 return self.free() < 258 + 1;
130}130}
lib/std/compress/flate/SlidingWindow.zig+23-23
...@@ -1,6 +1,6 @@...@@ -1,6 +1,6 @@
1/// Used in deflate (compression), holds uncompressed data form which Tokens are1//! 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.2//! produces. In combination with Lookup it is used to find matches in history data.
3///3//!
4const std = @import("std");4const std = @import("std");
5const consts = @import("consts.zig");5const consts = @import("consts.zig");
66
...@@ -20,7 +20,7 @@ wp: usize = 0, // write position...@@ -20,7 +20,7 @@ wp: usize = 0, // write position
20rp: usize = 0, // read position20rp: usize = 0, // read position
21fp: isize = 0, // last flush position, tokens are build from fp..rp21fp: 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.
24pub fn write(self: *Self, buf: []const u8) usize {24pub fn write(self: *Self, buf: []const u8) usize {
25 if (self.rp >= max_rp) return 0; // need to slide25 if (self.rp >= max_rp) return 0; // need to slide
2626
...@@ -30,9 +30,9 @@ pub fn write(self: *Self, buf: []const u8) usize {...@@ -30,9 +30,9 @@ pub fn write(self: *Self, buf: []const u8) usize {
30 return n;30 return n;
31}31}
3232
33// Slide buffer for hist_len.33/// Slide buffer for hist_len.
34// Drops old history, preserves between hist_len and hist_len - min_lookahead.34/// Drops old history, preserves between hist_len and hist_len - min_lookahead.
35// Returns number of bytes removed.35/// Returns number of bytes removed.
36pub fn slide(self: *Self) u16 {36pub fn slide(self: *Self) u16 {
37 assert(self.rp >= max_rp and self.wp >= self.rp);37 assert(self.rp >= max_rp and self.wp >= self.rp);
38 const n = self.wp - hist_len;38 const n = self.wp - hist_len;
...@@ -43,41 +43,41 @@ pub fn slide(self: *Self) u16 {...@@ -43,41 +43,41 @@ pub fn slide(self: *Self) u16 {
43 return @intCast(n);43 return @intCast(n);
44}44}
4545
46// Data from the current position (read position). Those part of the buffer is46/// Data from the current position (read position). Those part of the buffer is
47// not converted to tokens yet.47/// not converted to tokens yet.
48fn lookahead(self: *Self) []const u8 {48fn lookahead(self: *Self) []const u8 {
49 assert(self.wp >= self.rp);49 assert(self.wp >= self.rp);
50 return self.buffer[self.rp..self.wp];50 return self.buffer[self.rp..self.wp];
51}51}
5252
53// Returns part of the lookahead buffer. If should_flush is set no lookahead is53/// Returns part of the lookahead buffer. If should_flush is set no lookahead is
54// preserved otherwise preserves enough data for the longest match. Returns54/// preserved otherwise preserves enough data for the longest match. Returns
55// null if there is not enough data.55/// null if there is not enough data.
56pub fn activeLookahead(self: *Self, should_flush: bool) ?[]const u8 {56pub fn activeLookahead(self: *Self, should_flush: bool) ?[]const u8 {
57 const min: usize = if (should_flush) 0 else min_lookahead;57 const min: usize = if (should_flush) 0 else min_lookahead;
58 const lh = self.lookahead();58 const lh = self.lookahead();
59 return if (lh.len > min) lh else null;59 return if (lh.len > min) lh else null;
60}60}
6161
62// Advances read position, shrinks lookahead.62/// Advances read position, shrinks lookahead.
63pub fn advance(self: *Self, n: u16) void {63pub fn advance(self: *Self, n: u16) void {
64 assert(self.wp >= self.rp + n);64 assert(self.wp >= self.rp + n);
65 self.rp += n;65 self.rp += n;
66}66}
6767
68// Returns writable part of the buffer, where new uncompressed data can be68/// Returns writable part of the buffer, where new uncompressed data can be
69// written.69/// written.
70pub fn writable(self: *Self) []u8 {70pub fn writable(self: *Self) []u8 {
71 return self.buffer[self.wp..];71 return self.buffer[self.wp..];
72}72}
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.
75pub fn written(self: *Self, n: usize) void {75pub fn written(self: *Self, n: usize) void {
76 self.wp += n;76 self.wp += n;
77}77}
7878
79// Finds match length between previous and current position.79/// Finds match length between previous and current position.
80// Used in hot path!80/// Used in hot path!
81pub fn match(self: *Self, prev_pos: u16, curr_pos: u16, min_len: u16) u16 {81pub fn match(self: *Self, prev_pos: u16, curr_pos: u16, min_len: u16) u16 {
82 const max_len: usize = @min(self.wp - curr_pos, consts.match.max_length);82 const max_len: usize = @min(self.wp - curr_pos, consts.match.max_length);
83 // lookahead buffers from previous and current positions83 // 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 {...@@ -103,19 +103,19 @@ pub fn match(self: *Self, prev_pos: u16, curr_pos: u16, min_len: u16) u16 {
103 return if (i >= consts.match.min_length) @intCast(i) else 0;103 return if (i >= consts.match.min_length) @intCast(i) else 0;
104}104}
105105
106// Current position of non-compressed data. Data before rp are already converted106/// Current position of non-compressed data. Data before rp are already converted
107// to tokens.107/// to tokens.
108pub fn pos(self: *Self) u16 {108pub fn pos(self: *Self) u16 {
109 return @intCast(self.rp);109 return @intCast(self.rp);
110}110}
111111
112// Notification that token list is cleared.112/// Notification that token list is cleared.
113pub fn flush(self: *Self) void {113pub fn flush(self: *Self) void {
114 self.fp = @intCast(self.rp);114 self.fp = @intCast(self.rp);
115}115}
116116
117// Part of the buffer since last flush or null if there was slide in between (so117/// Part of the buffer since last flush or null if there was slide in between (so
118// fp becomes negative).118/// fp becomes negative).
119pub fn tokensBuffer(self: *Self) ?[]const u8 {119pub fn tokensBuffer(self: *Self) ?[]const u8 {
120 assert(self.fp <= self.rp);120 assert(self.fp <= self.rp);
121 if (self.fp < 0) return null;121 if (self.fp < 0) return null;
lib/std/compress/flate/Token.zig+4-4
...@@ -1,7 +1,7 @@...@@ -1,7 +1,7 @@
1/// Token cat be literal: single byte of data or match; reference to the slice of1//! 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 length2//! data in the same stream represented with <length, distance>. Where length
3/// can be 3 - 258 bytes, and distance 1 - 32768 bytes.3//! can be 3 - 258 bytes, and distance 1 - 32768 bytes.
4///4//!
5const std = @import("std");5const std = @import("std");
6const assert = std.debug.assert;6const assert = std.debug.assert;
7const print = std.debug.print;7const print = std.debug.print;
lib/std/compress/flate/bit_reader.zig+32-32
...@@ -34,15 +34,15 @@ pub fn BitReader(comptime ReaderType: type) type {...@@ -34,15 +34,15 @@ pub fn BitReader(comptime ReaderType: type) type {
34 return self;34 return self;
35 }35 }
3636
37 // Try to have `nice` bits are available in buffer. Reads from37 /// Try to have `nice` bits are available in buffer. Reads from
38 // forward reader if there is no `nice` bits in buffer. Returns error38 /// 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.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 when40 /// 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 the41 /// 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 less42 /// 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 have43 /// 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 reached44 /// that number of bits available. If end of forward stream is reached
45 // it may be some extra zero bits in buffer.45 /// it may be some extra zero bits in buffer.
46 pub inline fn fill(self: *Self, nice: u6) !void {46 pub inline fn fill(self: *Self, nice: u6) !void {
47 if (self.nbits >= nice) {47 if (self.nbits >= nice) {
48 return; // We have enought bits48 return; // We have enought bits
...@@ -67,7 +67,7 @@ pub fn BitReader(comptime ReaderType: type) type {...@@ -67,7 +67,7 @@ pub fn BitReader(comptime ReaderType: type) type {
67 return error.EndOfStream;67 return error.EndOfStream;
68 }68 }
6969
70 // Read exactly buf.len bytes into buf.70 /// Read exactly buf.len bytes into buf.
71 pub fn readAll(self: *Self, buf: []u8) !void {71 pub fn readAll(self: *Self, buf: []u8) !void {
72 assert(self.alignBits() == 0); // internal bits must be at byte boundary72 assert(self.alignBits() == 0); // internal bits must be at byte boundary
7373
...@@ -87,17 +87,17 @@ pub fn BitReader(comptime ReaderType: type) type {...@@ -87,17 +87,17 @@ pub fn BitReader(comptime ReaderType: type) type {
87 pub const reverse: u3 = 0b100; // bit reverse readed bits87 pub const reverse: u3 = 0b100; // bit reverse readed bits
88 };88 };
8989
90 // Alias for readF(U, 0).90 /// Alias for readF(U, 0).
91 pub fn read(self: *Self, comptime U: type) !U {91 pub fn read(self: *Self, comptime U: type) !U {
92 return self.readF(U, 0);92 return self.readF(U, 0);
93 }93 }
9494
95 // Alias for readF with flag.peak set.95 /// Alias for readF with flag.peak set.
96 pub inline fn peekF(self: *Self, comptime U: type, comptime how: u3) !U {96 pub inline fn peekF(self: *Self, comptime U: type, comptime how: u3) !U {
97 return self.readF(U, how | flag.peek);97 return self.readF(U, how | flag.peek);
98 }98 }
9999
100 // Read with flags provided.100 /// Read with flags provided.
101 pub fn readF(self: *Self, comptime U: type, comptime how: u3) !U {101 pub fn readF(self: *Self, comptime U: type, comptime how: u3) !U {
102 const n: u6 = @bitSizeOf(U);102 const n: u6 = @bitSizeOf(U);
103 switch (how) {103 switch (how) {
...@@ -140,8 +140,8 @@ pub fn BitReader(comptime ReaderType: type) type {...@@ -140,8 +140,8 @@ pub fn BitReader(comptime ReaderType: type) type {
140 }140 }
141 }141 }
142142
143 // Read n number of bits.143 /// Read n number of bits.
144 // Only buffered flag can be used in how.144 /// Only buffered flag can be used in how.
145 pub fn readN(self: *Self, n: u4, comptime how: u3) !u16 {145 pub fn readN(self: *Self, n: u4, comptime how: u3) !u16 {
146 switch (how) {146 switch (how) {
147 0 => {147 0 => {
...@@ -156,14 +156,14 @@ pub fn BitReader(comptime ReaderType: type) type {...@@ -156,14 +156,14 @@ pub fn BitReader(comptime ReaderType: type) type {
156 return u;156 return u;
157 }157 }
158158
159 // Advance buffer for n bits.159 /// Advance buffer for n bits.
160 pub fn shift(self: *Self, n: u6) !void {160 pub fn shift(self: *Self, n: u6) !void {
161 if (n > self.nbits) return error.EndOfStream;161 if (n > self.nbits) return error.EndOfStream;
162 self.bits >>= n;162 self.bits >>= n;
163 self.nbits -= n;163 self.nbits -= n;
164 }164 }
165165
166 // Skip n bytes.166 /// Skip n bytes.
167 pub fn skipBytes(self: *Self, n: u16) !void {167 pub fn skipBytes(self: *Self, n: u16) !void {
168 for (0..n) |_| {168 for (0..n) |_| {
169 try self.fill(8);169 try self.fill(8);
...@@ -176,32 +176,32 @@ pub fn BitReader(comptime ReaderType: type) type {...@@ -176,32 +176,32 @@ pub fn BitReader(comptime ReaderType: type) type {
176 return @intCast(self.nbits & 0x7);176 return @intCast(self.nbits & 0x7);
177 }177 }
178178
179 // Align stream to the byte boundary.179 /// Align stream to the byte boundary.
180 pub fn alignToByte(self: *Self) void {180 pub fn alignToByte(self: *Self) void {
181 const ab = self.alignBits();181 const ab = self.alignBits();
182 if (ab > 0) self.shift(ab) catch unreachable;182 if (ab > 0) self.shift(ab) catch unreachable;
183 }183 }
184184
185 // Skip zero terminated string.185 /// Skip zero terminated string.
186 pub fn skipStringZ(self: *Self) !void {186 pub fn skipStringZ(self: *Self) !void {
187 while (true) {187 while (true) {
188 if (try self.readF(u8, 0) == 0) break;188 if (try self.readF(u8, 0) == 0) break;
189 }189 }
190 }190 }
191191
192 // Read deflate fixed fixed code.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.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-12194 /// ref: https://datatracker.ietf.org/doc/html/rfc1951#page-12
195 // Lit Value Bits Codes195 /// Lit Value Bits Codes
196 // --------- ---- -----196 /// --------- ---- -----
197 // 0 - 143 8 00110000 through197 /// 0 - 143 8 00110000 through
198 // 10111111198 /// 10111111
199 // 144 - 255 9 110010000 through199 /// 144 - 255 9 110010000 through
200 // 111111111200 /// 111111111
201 // 256 - 279 7 0000000 through201 /// 256 - 279 7 0000000 through
202 // 0010111202 /// 0010111
203 // 280 - 287 8 11000000 through203 /// 280 - 287 8 11000000 through
204 // 11000111204 /// 11000111
205 pub fn readFixedCode(self: *Self) !u16 {205 pub fn readFixedCode(self: *Self) !u16 {
206 try self.fill(7 + 2);206 try self.fill(7 + 2);
207 const code7 = try self.readF(u7, flag.buffered | flag.reverse);207 const code7 = try self.readF(u7, flag.buffered | flag.reverse);
lib/std/compress/flate/container.zig+15-14
...@@ -1,19 +1,20 @@...@@ -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
1const std = @import("std");16const 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///
17pub const Container = enum {18pub const Container = enum {
18 raw, // no header or footer19 raw, // no header or footer
19 gzip, // gzip header and footer20 gzip, // gzip header and footer