Refactor std/flate comments.

This commit is contained in:
Nigel Tao committed 2017-07-28 16:03:26 +10:00
1 parent 6b019831ad
commit 3a8106daa5
1 file changed
+61 -50
+61 -50
View File
@@ -81,9 +81,14 @@ pub struct decoder?(
huffs[2][512] u32,
n_huffs_bits[2] u32[..9],
// These fields are used as scratch space when constructing the huffs
// tables.
// code_lengths is used to pass out-of-band data to init_huff.
//
// code_lengths[in.n_codes0 + i] holds the number of bits in the i'th code.
code_lengths[320] u8[..15],
// These fields are used as init_huff scratch space.
//
// TODO: make these local variables, not fields.
counts[16] u16[..320],
symbols[320] u16[..319],
)
@@ -446,6 +451,16 @@ pri func decoder.init_huff?(which u32[..1], n_codes0 u32[..320], n_codes1 u32[..
// - code_lengths[17] = 4
// - code_lengths[18] = 5
// Calculate counts.
//
// For the clcode example in this package's README.md:
// - counts[0] = 9
// - counts[1] = 0
// - counts[2] = 0
// - counts[3] = 7
// - counts[4] = 1
// - counts[5] = 2
// - all other counts elements are 0.
var i u32
while i < 16 {
this.counts[i] = 0
@@ -466,15 +481,6 @@ pri func decoder.init_huff?(which u32[..1], n_codes0 u32[..320], n_codes1 u32[..
return error "no Huffman codes"
}
// For the clcode example in this package's README.md:
// - counts[0] = 9
// - counts[1] = 0
// - counts[2] = 0
// - counts[3] = 7
// - counts[4] = 1
// - counts[5] = 2
// - all other counts elements are 0.
// Check that the Huffman code completely covers all possible input bits.
var remaining u32 = 1 // There is 1 possible 0-bit code.
i = 1
@@ -495,6 +501,18 @@ pri func decoder.init_huff?(which u32[..1], n_codes0 u32[..320], n_codes1 u32[..
return error "bad Huffman code (under-subscribed)"
}
// Calculate offsets and n_symbols.
//
// For the clcode example in this package's README.md:
// - offsets[0] = 0
// - offsets[1] = 0
// - offsets[2] = 0
// - offsets[3] = 0
// - offsets[4] = 7
// - offsets[5] = 8
// - offsets[6] = 10
// - all other offsets elements are 10.
// - n_symbols = 10
var offsets[16] u16[..320]
var n_symbols u32[..320]
i = 1
@@ -514,16 +532,24 @@ pri func decoder.init_huff?(which u32[..1], n_codes0 u32[..320], n_codes1 u32[..
return error "internal error: inconsistent Huffman decoder state"
}
// Calculate symbols.
//
// For the clcode example in this package's README.md:
// - offsets[0] = 0
// - offsets[1] = 0
// - offsets[2] = 0
// - offsets[3] = 0
// - offsets[4] = 7
// - offsets[5] = 8
// - offsets[6] = 10
// - all other offsets elements are 10.
// - symbols[0] = 0
// - symbols[1] = 4
// - symbols[2] = 5
// - symbols[3] = 6
// - symbols[4] = 7
// - symbols[5] = 8
// - symbols[6] = 9
// - symbols[7] = 17
// - symbols[8] = 3
// - symbols[9] = 18
//
// As a (local variable) side effect, offsets' values will be updated:
// - offsets[3] = 7, formerly 0
// - offsets[4] = 8, formerly 7
// - offsets[5] = 10, formerly 8
i = in.n_codes0
while i < in.n_codes1,
inv n_symbols <= 288,
@@ -543,23 +569,10 @@ pri func decoder.init_huff?(which u32[..1], n_codes0 u32[..320], n_codes1 u32[..
i += 1
}
// For the clcode example in this package's README.md:
// - symbols[0] = 0
// - symbols[1] = 4
// - symbols[2] = 5
// - symbols[3] = 6
// - symbols[4] = 7
// - symbols[5] = 8
// - symbols[6] = 9
// - symbols[7] = 17
// - symbols[8] = 3
// - symbols[9] = 18
// Calculate max_cl.
//
// As a (local variable) side effect, offsets' values have been updated:
// - offsets[3] = 7, formerly 0
// - offsets[4] = 8, formerly 7
// - offsets[5] = 10, formerly 8
// For the clcode example in this package's README.md:
// - max_cl = 5
var max_cl u32[1..15] = 15
while true,
inv n_symbols <= 288,
@@ -577,9 +590,19 @@ pri func decoder.init_huff?(which u32[..1], n_codes0 u32[..320], n_codes1 u32[..
return error "TODO: indirect Huffman tables"
}
// Calculate this.huffs[in.which].
//
// For the clcode example in this package's README.md:
// - max_cl = 5
// - this.huffs[0][0b..000] = 0x40000003 (literal, symbols[0]=0x00, code_length=3)
// - this.huffs[0][0b..100] = 0x40000403 (literal, symbols[1]=0x04, code_length=3)
// - this.huffs[0][0b..010] = 0x40000503 (literal, symbols[2]=0x05, code_length=3)
// - this.huffs[0][0b..110] = 0x40000603 (literal, symbols[3]=0x06, code_length=3)
// - this.huffs[0][0b..001] = 0x40000703 (literal, symbols[4]=0x07, code_length=3)
// - this.huffs[0][0b..101] = 0x40000803 (literal, symbols[5]=0x08, code_length=3)
// - this.huffs[0][0b..011] = 0x40000903 (literal, symbols[6]=0x09, code_length=3)
// - this.huffs[0][0b.0111] = 0x40001104 (literal, symbols[7]=0x11, code_length=4)
// - this.huffs[0][0b01111] = 0x40000305 (literal, symbols[8]=0x03, code_length=5)
// - this.huffs[0][0b11111] = 0x40001805 (literal, symbols[9]=0x18, code_length=5)
i = 0
if (n_symbols != (offsets[max_cl] as u32)) or (n_symbols != (offsets[15] as u32)) {
return error "internal error: inconsistent Huffman decoder state"
@@ -660,16 +683,4 @@ pri func decoder.init_huff?(which u32[..1], n_codes0 u32[..320], n_codes1 u32[..
prev_cl = cl
}
this.n_huffs_bits[in.which] = max_cl
// For the clcode example in this package's README.md:
// - huffs[0][0b..000] maps to value 0x40000003 (literal, symbols[0]=0x00, code_length=3)
// - huffs[0][0b..100] maps to value 0x40000403 (literal, symbols[1]=0x04, code_length=3)
// - huffs[0][0b..010] maps to value 0x40000503 (literal, symbols[2]=0x05, code_length=3)
// - huffs[0][0b..110] maps to value 0x40000603 (literal, symbols[3]=0x06, code_length=3)
// - huffs[0][0b..001] maps to value 0x40000703 (literal, symbols[4]=0x07, code_length=3)
// - huffs[0][0b..101] maps to value 0x40000803 (literal, symbols[5]=0x08, code_length=3)
// - huffs[0][0b..011] maps to value 0x40000903 (literal, symbols[6]=0x09, code_length=3)
// - huffs[0][0b.0111] maps to value 0x40001104 (literal, symbols[7]=0x11, code_length=4)
// - huffs[0][0b01111] maps to value 0x40000305 (literal, symbols[8]=0x03, code_length=5)
// - huffs[0][0b11111] maps to value 0x40001805 (literal, symbols[9]=0x18, code_length=5)
}