deflate.go

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  package flate
     6  
     7  import (
     8  	"errors"
     9  	"fmt"
    10  	"io"
    11  	"math"
    12  )
    13  
    14  const (
    15  	NoCompression      = 0
    16  	BestSpeed          = 1
    17  	BestCompression    = 9
    18  	DefaultCompression = -1
    19  
    20  	// HuffmanOnly disables Lempel-Ziv match searching and only performs Huffman
    21  	// entropy encoding. This mode is useful in compressing data that has
    22  	// already been compressed with an LZ style algorithm (e.g. Snappy or LZ4)
    23  	// that lacks an entropy encoder. Compression gains are achieved when
    24  	// certain bytes in the input stream occur more frequently than others.
    25  	//
    26  	// Note that HuffmanOnly produces a compressed output that is
    27  	// RFC 1951 compliant. That is, any valid DEFLATE decompressor will
    28  	// continue to be able to decompress this output.
    29  	HuffmanOnly = -2
    30  )
    31  
    32  const (
    33  	logWindowSize = 15
    34  	windowSize    = 1 << logWindowSize
    35  	windowMask    = windowSize - 1
    36  
    37  	// The LZ77 step produces a sequence of literal tokens and <length, offset>
    38  	// pair tokens. The offset is also known as distance. The underlying wire
    39  	// format limits the range of lengths and offsets. For example, there are
    40  	// 256 legitimate lengths: those in the range [3, 258]. This package's
    41  	// compressor uses a higher minimum match length, enabling optimizations
    42  	// such as finding matches via 32-bit loads and compares.
    43  	baseMatchLength = 3       // The smallest match length per the RFC section 3.2.5
    44  	minMatchLength  = 4       // The smallest match length that the compressor actually emits
    45  	maxMatchLength  = 258     // The largest match length
    46  	baseMatchOffset = 1       // The smallest match offset
    47  	maxMatchOffset  = 1 << 15 // The largest match offset
    48  
    49  	// The maximum number of tokens we put into a single flate block, just to
    50  	// stop things from getting too large.
    51  	maxFlateBlockTokens = 1 << 14
    52  	maxStoreBlockSize   = 65535
    53  	hashBits            = 17 // After 17 performance degrades
    54  	hashSize            = 1 << hashBits
    55  	hashMask            = (1 << hashBits) - 1
    56  	maxHashOffset       = 1 << 24
    57  
    58  	skipNever = math.MaxInt32
    59  )
    60  
    61  type compressionLevel struct {
    62  	level, good, lazy, nice, chain, fastSkipHashing int
    63  }
    64  
    65  var levels = []compressionLevel{
    66  	{0, 0, 0, 0, 0, 0}, // NoCompression.
    67  	{1, 0, 0, 0, 0, 0}, // BestSpeed uses a custom algorithm; see deflatefast.go.
    68  	// For levels 2-3 we don't bother trying with lazy matches.
    69  	{2, 4, 0, 16, 8, 5},
    70  	{3, 4, 0, 32, 32, 6},
    71  	// Levels 4-9 use increasingly more lazy matching
    72  	// and increasingly stringent conditions for "good enough".
    73  	{4, 4, 4, 16, 16, skipNever},
    74  	{5, 8, 16, 32, 32, skipNever},
    75  	{6, 8, 16, 128, 128, skipNever},
    76  	{7, 8, 32, 128, 256, skipNever},
    77  	{8, 32, 128, 258, 1024, skipNever},
    78  	{9, 32, 258, 258, 4096, skipNever},
    79  }
    80  
    81  type compressor struct {
    82  	compressionLevel
    83  
    84  	w          *huffmanBitWriter
    85  	bulkHasher func([]byte, []uint32)
    86  
    87  	// compression algorithm
    88  	fill      func(*compressor, []byte) int // copy data to window
    89  	step      func(*compressor)             // process window
    90  	bestSpeed *deflateFast                  // Encoder for BestSpeed
    91  
    92  	// input window: unprocessed data is window[index:windowEnd]
    93  	index         int
    94  	window        []byte
    95  	windowEnd     int
    96  	blockStart    int  // window index where current tokens start
    97  	byteAvailable bool // if true, still need to process window[index-1].
    98  
    99  	sync bool // requesting flush
   100  
   101  	// queued output tokens
   102  	tokens []token
   103  
   104  	// deflate state
   105  	length         int
   106  	offset         int
   107  	maxInsertIndex int
   108  	err            error
   109  
   110  	// Input hash chains
   111  	// hashHead[hashValue] contains the largest inputIndex with the specified hash value
   112  	// If hashHead[hashValue] is within the current window, then
   113  	// hashPrev[hashHead[hashValue] & windowMask] contains the previous index
   114  	// with the same hash value.
   115  	// These are large and do not contain pointers, so put them
   116  	// near the end of the struct so the GC has to scan less.
   117  	chainHead  int
   118  	hashHead   [hashSize]uint32
   119  	hashPrev   [windowSize]uint32
   120  	hashOffset int
   121  
   122  	// hashMatch must be able to contain hashes for the maximum match length.
   123  	hashMatch [maxMatchLength - 1]uint32
   124  }
   125  
   126  func (d *compressor) fillDeflate(b []byte) int {
   127  	if d.index >= 2*windowSize-(minMatchLength+maxMatchLength) {
   128  		// shift the window by windowSize
   129  		copy(d.window, d.window[windowSize:2*windowSize])
   130  		d.index -= windowSize
   131  		d.windowEnd -= windowSize
   132  		if d.blockStart >= windowSize {
   133  			d.blockStart -= windowSize
   134  		} else {
   135  			d.blockStart = math.MaxInt32
   136  		}
   137  		d.hashOffset += windowSize
   138  		if d.hashOffset > maxHashOffset {
   139  			delta := d.hashOffset - 1
   140  			d.hashOffset -= delta
   141  			d.chainHead -= delta
   142  
   143  			// Iterate over slices instead of arrays to avoid copying
   144  			// the entire table onto the stack (Issue #18625).
   145  			for i, v := range d.hashPrev[:] {
   146  				if int(v) > delta {
   147  					d.hashPrev[i] = uint32(int(v) - delta)
   148  				} else {
   149  					d.hashPrev[i] = 0
   150  				}
   151  			}
   152  			for i, v := range d.hashHead[:] {
   153  				if int(v) > delta {
   154  					d.hashHead[i] = uint32(int(v) - delta)
   155  				} else {
   156  					d.hashHead[i] = 0
   157  				}
   158  			}
   159  		}
   160  	}
   161  	n := copy(d.window[d.windowEnd:], b)
   162  	d.windowEnd += n
   163  	return n
   164  }
   165  
   166  func (d *compressor) writeBlock(tokens []token, index int) error {
   167  	if index > 0 {
   168  		var window []byte
   169  		if d.blockStart <= index {
   170  			window = d.window[d.blockStart:index]
   171  		}
   172  		d.blockStart = index
   173  		d.w.writeBlock(tokens, false, window)
   174  		return d.w.err
   175  	}
   176  	return nil
   177  }
   178  
   179  // fillWindow will fill the current window with the supplied
   180  // dictionary and calculate all hashes.
   181  // This is much faster than doing a full encode.
   182  // Should only be used after a reset.
   183  func (d *compressor) fillWindow(b []byte) {
   184  	// Do not fill window if we are in store-only mode.
   185  	if d.compressionLevel.level < 2 {
   186  		return
   187  	}
   188  	if d.index != 0 || d.windowEnd != 0 {
   189  		panic("internal error: fillWindow called with stale data")
   190  	}
   191  
   192  	// If we are given too much, cut it.
   193  	if len(b) > windowSize {
   194  		b = b[len(b)-windowSize:]
   195  	}
   196  	// Add all to window.
   197  	n := copy(d.window, b)
   198  
   199  	// Calculate 256 hashes at the time (more L1 cache hits)
   200  	loops := (n + 256 - minMatchLength) / 256
   201  	for j := 0; j < loops; j++ {
   202  		index := j * 256
   203  		end := index + 256 + minMatchLength - 1
   204  		if end > n {
   205  			end = n
   206  		}
   207  		toCheck := d.window[index:end]
   208  		dstSize := len(toCheck) - minMatchLength + 1
   209  
   210  		if dstSize <= 0 {
   211  			continue
   212  		}
   213  
   214  		dst := d.hashMatch[:dstSize]
   215  		d.bulkHasher(toCheck, dst)
   216  		for i, val := range dst {
   217  			di := i + index
   218  			hh := &d.hashHead[val&hashMask]
   219  			// Get previous value with the same hash.
   220  			// Our chain should point to the previous value.
   221  			d.hashPrev[di&windowMask] = *hh
   222  			// Set the head of the hash chain to us.
   223  			*hh = uint32(di + d.hashOffset)
   224  		}
   225  	}
   226  	// Update window information.
   227  	d.windowEnd = n
   228  	d.index = n
   229  }
   230  
   231  // Try to find a match starting at index whose length is greater than prevSize.
   232  // We only look at chainCount possibilities before giving up.
   233  func (d *compressor) findMatch(pos int, prevHead int, prevLength int, lookahead int) (length, offset int, ok bool) {
   234  	minMatchLook := maxMatchLength
   235  	if lookahead < minMatchLook {
   236  		minMatchLook = lookahead
   237  	}
   238  
   239  	win := d.window[0 : pos+minMatchLook]
   240  
   241  	// We quit when we get a match that's at least nice long
   242  	nice := len(win) - pos
   243  	if d.nice < nice {
   244  		nice = d.nice
   245  	}
   246  
   247  	// If we've got a match that's good enough, only look in 1/4 the chain.
   248  	tries := d.chain
   249  	length = prevLength
   250  	if length >= d.good {
   251  		tries >>= 2
   252  	}
   253  
   254  	wEnd := win[pos+length]
   255  	wPos := win[pos:]
   256  	minIndex := pos - windowSize
   257  
   258  	for i := prevHead; tries > 0; tries-- {
   259  		if wEnd == win[i+length] {
   260  			n := matchLen(win[i:], wPos, minMatchLook)
   261  
   262  			if n > length && (n > minMatchLength || pos-i <= 4096) {
   263  				length = n
   264  				offset = pos - i
   265  				ok = true
   266  				if n >= nice {
   267  					// The match is good enough that we don't try to find a better one.
   268  					break
   269  				}
   270  				wEnd = win[pos+n]
   271  			}
   272  		}
   273  		if i == minIndex {
   274  			// hashPrev[i & windowMask] has already been overwritten, so stop now.
   275  			break
   276  		}
   277  		i = int(d.hashPrev[i&windowMask]) - d.hashOffset
   278  		if i < minIndex || i < 0 {
   279  			break
   280  		}
   281  	}
   282  	return
   283  }
   284  
   285  func (d *compressor) writeStoredBlock(buf []byte) error {
   286  	if d.w.writeStoredHeader(len(buf), false); d.w.err != nil {
   287  		return d.w.err
   288  	}
   289  	d.w.writeBytes(buf)
   290  	return d.w.err
   291  }
   292  
   293  const hashmul = 0x1e35a7bd
   294  
   295  // hash4 returns a hash representation of the first 4 bytes
   296  // of the supplied slice.
   297  // The caller must ensure that len(b) >= 4.
   298  func hash4(b []byte) uint32 {
   299  	return ((uint32(b[3]) | uint32(b[2])<<8 | uint32(b[1])<<16 | uint32(b[0])<<24) * hashmul) >> (32 - hashBits)
   300  }
   301  
   302  // bulkHash4 will compute hashes using the same
   303  // algorithm as hash4.
   304  func bulkHash4(b []byte, dst []uint32) {
   305  	if len(b) < minMatchLength {
   306  		return
   307  	}
   308  	hb := uint32(b[3]) | uint32(b[2])<<8 | uint32(b[1])<<16 | uint32(b[0])<<24
   309  	dst[0] = (hb * hashmul) >> (32 - hashBits)
   310  	end := len(b) - minMatchLength + 1
   311  	for i := 1; i < end; i++ {
   312  		hb = (hb << 8) | uint32(b[i+3])
   313  		dst[i] = (hb * hashmul) >> (32 - hashBits)
   314  	}
   315  }
   316  
   317  // matchLen returns the number of matching bytes in a and b
   318  // up to length 'max'. Both slices must be at least 'max'
   319  // bytes in size.
   320  func matchLen(a, b []byte, max int) int {
   321  	a = a[:max]
   322  	b = b[:len(a)]
   323  	for i, av := range a {
   324  		if b[i] != av {
   325  			return i
   326  		}
   327  	}
   328  	return max
   329  }
   330  
   331  // encSpeed will compress and store the currently added data,
   332  // if enough has been accumulated or we at the end of the stream.
   333  // Any error that occurred will be in d.err
   334  func (d *compressor) encSpeed() {
   335  	// We only compress if we have maxStoreBlockSize.
   336  	if d.windowEnd < maxStoreBlockSize {
   337  		if !d.sync {
   338  			return
   339  		}
   340  
   341  		// Handle small sizes.
   342  		if d.windowEnd < 128 {
   343  			switch {
   344  			case d.windowEnd == 0:
   345  				return
   346  			case d.windowEnd <= 16:
   347  				d.err = d.writeStoredBlock(d.window[:d.windowEnd])
   348  			default:
   349  				d.w.writeBlockHuff(false, d.window[:d.windowEnd])
   350  				d.err = d.w.err
   351  			}
   352  			d.windowEnd = 0
   353  			d.bestSpeed.reset()
   354  			return
   355  		}
   356  
   357  	}
   358  	// Encode the block.
   359  	d.tokens = d.bestSpeed.encode(d.tokens[:0], d.window[:d.windowEnd])
   360  
   361  	// If we removed less than 1/16th, Huffman compress the block.
   362  	if len(d.tokens) > d.windowEnd-(d.windowEnd>>4) {
   363  		d.w.writeBlockHuff(false, d.window[:d.windowEnd])
   364  	} else {
   365  		d.w.writeBlockDynamic(d.tokens, false, d.window[:d.windowEnd])
   366  	}
   367  	d.err = d.w.err
   368  	d.windowEnd = 0
   369  }
   370  
   371  func (d *compressor) initDeflate() {
   372  	d.window = make([]byte, 2*windowSize)
   373  	d.hashOffset = 1
   374  	d.tokens = make([]token, 0, maxFlateBlockTokens+1)
   375  	d.length = minMatchLength - 1
   376  	d.offset = 0
   377  	d.byteAvailable = false
   378  	d.index = 0
   379  	d.chainHead = -1
   380  	d.bulkHasher = bulkHash4
   381  }
   382  
   383  func (d *compressor) deflate() {
   384  	if d.windowEnd-d.index < minMatchLength+maxMatchLength && !d.sync {
   385  		return
   386  	}
   387  
   388  	d.maxInsertIndex = d.windowEnd - (minMatchLength - 1)
   389  
   390  Loop:
   391  	for {
   392  		if d.index > d.windowEnd {
   393  			panic("index > windowEnd")
   394  		}
   395  		lookahead := d.windowEnd - d.index
   396  		if lookahead < minMatchLength+maxMatchLength {
   397  			if !d.sync {
   398  				break Loop
   399  			}
   400  			if d.index > d.windowEnd {
   401  				panic("index > windowEnd")
   402  			}
   403  			if lookahead == 0 {
   404  				// Flush current output block if any.
   405  				if d.byteAvailable {
   406  					// There is still one pending token that needs to be flushed
   407  					d.tokens = append(d.tokens, literalToken(uint32(d.window[d.index-1])))
   408  					d.byteAvailable = false
   409  				}
   410  				if len(d.tokens) > 0 {
   411  					if d.err = d.writeBlock(d.tokens, d.index); d.err != nil {
   412  						return
   413  					}
   414  					d.tokens = d.tokens[:0]
   415  				}
   416  				break Loop
   417  			}
   418  		}
   419  		if d.index < d.maxInsertIndex {
   420  			// Update the hash
   421  			hash := hash4(d.window[d.index : d.index+minMatchLength])
   422  			hh := &d.hashHead[hash&hashMask]
   423  			d.chainHead = int(*hh)
   424  			d.hashPrev[d.index&windowMask] = uint32(d.chainHead)
   425  			*hh = uint32(d.index + d.hashOffset)
   426  		}
   427  		prevLength := d.length
   428  		prevOffset := d.offset
   429  		d.length = minMatchLength - 1
   430  		d.offset = 0
   431  		minIndex := d.index - windowSize
   432  		if minIndex < 0 {
   433  			minIndex = 0
   434  		}
   435  
   436  		if d.chainHead-d.hashOffset >= minIndex &&
   437  			(d.fastSkipHashing != skipNever && lookahead > minMatchLength-1 ||
   438  				d.fastSkipHashing == skipNever && lookahead > prevLength && prevLength < d.lazy) {
   439  			if newLength, newOffset, ok := d.findMatch(d.index, d.chainHead-d.hashOffset, minMatchLength-1, lookahead); ok {
   440  				d.length = newLength
   441  				d.offset = newOffset
   442  			}
   443  		}
   444  		if d.fastSkipHashing != skipNever && d.length >= minMatchLength ||
   445  			d.fastSkipHashing == skipNever && prevLength >= minMatchLength && d.length <= prevLength {
   446  			// There was a match at the previous step, and the current match is
   447  			// not better. Output the previous match.
   448  			if d.fastSkipHashing != skipNever {
   449  				d.tokens = append(d.tokens, matchToken(uint32(d.length-baseMatchLength), uint32(d.offset-baseMatchOffset)))
   450  			} else {
   451  				d.tokens = append(d.tokens, matchToken(uint32(prevLength-baseMatchLength), uint32(prevOffset-baseMatchOffset)))
   452  			}
   453  			// Insert in the hash table all strings up to the end of the match.
   454  			// index and index-1 are already inserted. If there is not enough
   455  			// lookahead, the last two strings are not inserted into the hash
   456  			// table.
   457  			if d.length <= d.fastSkipHashing {
   458  				var newIndex int
   459  				if d.fastSkipHashing != skipNever {
   460  					newIndex = d.index + d.length
   461  				} else {
   462  					newIndex = d.index + prevLength - 1
   463  				}
   464  				index := d.index
   465  				for index++; index < newIndex; index++ {
   466  					if index < d.maxInsertIndex {
   467  						hash := hash4(d.window[index : index+minMatchLength])
   468  						// Get previous value with the same hash.
   469  						// Our chain should point to the previous value.
   470  						hh := &d.hashHead[hash&hashMask]
   471  						d.hashPrev[index&windowMask] = *hh
   472  						// Set the head of the hash chain to us.
   473  						*hh = uint32(index + d.hashOffset)
   474  					}
   475  				}
   476  				d.index = index
   477  
   478  				if d.fastSkipHashing == skipNever {
   479  					d.byteAvailable = false
   480  					d.length = minMatchLength - 1
   481  				}
   482  			} else {
   483  				// For matches this long, we don't bother inserting each individual
   484  				// item into the table.
   485  				d.index += d.length
   486  			}
   487  			if len(d.tokens) == maxFlateBlockTokens {
   488  				// The block includes the current character
   489  				if d.err = d.writeBlock(d.tokens, d.index); d.err != nil {
   490  					return
   491  				}
   492  				d.tokens = d.tokens[:0]
   493  			}
   494  		} else {
   495  			if d.fastSkipHashing != skipNever || d.byteAvailable {
   496  				i := d.index - 1
   497  				if d.fastSkipHashing != skipNever {
   498  					i = d.index
   499  				}
   500  				d.tokens = append(d.tokens, literalToken(uint32(d.window[i])))
   501  				if len(d.tokens) == maxFlateBlockTokens {
   502  					if d.err = d.writeBlock(d.tokens, i+1); d.err != nil {
   503  						return
   504  					}
   505  					d.tokens = d.tokens[:0]
   506  				}
   507  			}
   508  			d.index++
   509  			if d.fastSkipHashing == skipNever {
   510  				d.byteAvailable = true
   511  			}
   512  		}
   513  	}
   514  }
   515  
   516  func (d *compressor) fillStore(b []byte) int {
   517  	n := copy(d.window[d.windowEnd:], b)
   518  	d.windowEnd += n
   519  	return n
   520  }
   521  
   522  func (d *compressor) store() {
   523  	if d.windowEnd > 0 && (d.windowEnd == maxStoreBlockSize || d.sync) {
   524  		d.err = d.writeStoredBlock(d.window[:d.windowEnd])
   525  		d.windowEnd = 0
   526  	}
   527  }
   528  
   529  // storeHuff compresses and stores the currently added data
   530  // when the d.window is full or we are at the end of the stream.
   531  // Any error that occurred will be in d.err
   532  func (d *compressor) storeHuff() {
   533  	if d.windowEnd < len(d.window) && !d.sync || d.windowEnd == 0 {
   534  		return
   535  	}
   536  	d.w.writeBlockHuff(false, d.window[:d.windowEnd])
   537  	d.err = d.w.err
   538  	d.windowEnd = 0
   539  }
   540  
   541  func (d *compressor) write(b []byte) (n int, err error) {
   542  	if d.err != nil {
   543  		return 0, d.err
   544  	}
   545  	n = len(b)
   546  	for len(b) > 0 {
   547  		d.step(d)
   548  		b = b[d.fill(d, b):]
   549  		if d.err != nil {
   550  			return 0, d.err
   551  		}
   552  	}
   553  	return n, nil
   554  }
   555  
   556  func (d *compressor) syncFlush() error {
   557  	if d.err != nil {
   558  		return d.err
   559  	}
   560  	d.sync = true
   561  	d.step(d)
   562  	if d.err == nil {
   563  		d.w.writeStoredHeader(0, false)
   564  		d.w.flush()
   565  		d.err = d.w.err
   566  	}
   567  	d.sync = false
   568  	return d.err
   569  }
   570  
   571  func (d *compressor) init(w io.Writer, level int) (err error) {
   572  	d.w = newHuffmanBitWriter(w)
   573  
   574  	switch {
   575  	case level == NoCompression:
   576  		d.window = make([]byte, maxStoreBlockSize)
   577  		d.fill = (*compressor).fillStore
   578  		d.step = (*compressor).store
   579  	case level == HuffmanOnly:
   580  		d.window = make([]byte, maxStoreBlockSize)
   581  		d.fill = (*compressor).fillStore
   582  		d.step = (*compressor).storeHuff
   583  	case level == BestSpeed:
   584  		d.compressionLevel = levels[level]
   585  		d.window = make([]byte, maxStoreBlockSize)
   586  		d.fill = (*compressor).fillStore
   587  		d.step = (*compressor).encSpeed
   588  		d.bestSpeed = newDeflateFast()
   589  		d.tokens = make([]token, maxStoreBlockSize)
   590  	case level == DefaultCompression:
   591  		level = 6
   592  		fallthrough
   593  	case 2 <= level && level <= 9:
   594  		d.compressionLevel = levels[level]
   595  		d.initDeflate()
   596  		d.fill = (*compressor).fillDeflate
   597  		d.step = (*compressor).deflate
   598  	default:
   599  		return fmt.Errorf("flate: invalid compression level %d: want value in range [-2, 9]", level)
   600  	}
   601  	return nil
   602  }
   603  
   604  func (d *compressor) reset(w io.Writer) {
   605  	d.w.reset(w)
   606  	d.sync = false
   607  	d.err = nil
   608  	switch d.compressionLevel.level {
   609  	case NoCompression:
   610  		d.windowEnd = 0
   611  	case BestSpeed:
   612  		d.windowEnd = 0
   613  		d.tokens = d.tokens[:0]
   614  		d.bestSpeed.reset()
   615  	default:
   616  		d.chainHead = -1
   617  		clear(d.hashHead[:])
   618  		clear(d.hashPrev[:])
   619  		d.hashOffset = 1
   620  		d.index, d.windowEnd = 0, 0
   621  		d.blockStart, d.byteAvailable = 0, false
   622  		d.tokens = d.tokens[:0]
   623  		d.length = minMatchLength - 1
   624  		d.offset = 0
   625  		d.maxInsertIndex = 0
   626  	}
   627  }
   628  
   629  func (d *compressor) close() error {
   630  	if d.err == errWriterClosed {
   631  		return nil
   632  	}
   633  	if d.err != nil {
   634  		return d.err
   635  	}
   636  	d.sync = true
   637  	d.step(d)
   638  	if d.err != nil {
   639  		return d.err
   640  	}
   641  	if d.w.writeStoredHeader(0, true); d.w.err != nil {
   642  		return d.w.err
   643  	}
   644  	d.w.flush()
   645  	if d.w.err != nil {
   646  		return d.w.err
   647  	}
   648  	d.err = errWriterClosed
   649  	return nil
   650  }
   651  
   652  // NewWriter returns a new [Writer] compressing data at the given level.
   653  // Following zlib, levels range from 1 ([BestSpeed]) to 9 ([BestCompression]);
   654  // higher levels typically run slower but compress more. Level 0
   655  // ([NoCompression]) does not attempt any compression; it only adds the
   656  // necessary DEFLATE framing.
   657  // Level -1 ([DefaultCompression]) uses the default compression level.
   658  // Level -2 ([HuffmanOnly]) will use Huffman compression only, giving
   659  // a very fast compression for all types of input, but sacrificing considerable
   660  // compression efficiency.
   661  //
   662  // If level is in the range [-2, 9] then the error returned will be nil.
   663  // Otherwise the error returned will be non-nil.
   664  func NewWriter(w io.Writer, level int) (*Writer, error) {
   665  	var dw Writer
   666  	if err := dw.d.init(w, level); err != nil {
   667  		return nil, err
   668  	}
   669  	return &dw, nil
   670  }
   671  
   672  // NewWriterDict is like [NewWriter] but initializes the new
   673  // [Writer] with a preset dictionary. The returned [Writer] behaves
   674  // as if the dictionary had been written to it without producing
   675  // any compressed output. The compressed data written to w
   676  // can only be decompressed by a reader initialized with the
   677  // same dictionary (see [NewReaderDict]).
   678  func NewWriterDict(w io.Writer, level int, dict []byte) (*Writer, error) {
   679  	dw := &dictWriter{w}
   680  	zw, err := NewWriter(dw, level)
   681  	if err != nil {
   682  		return nil, err
   683  	}
   684  	zw.d.fillWindow(dict)
   685  	zw.dict = append(zw.dict, dict...) // duplicate dictionary for Reset method.
   686  	return zw, nil
   687  }
   688  
   689  type dictWriter struct {
   690  	w io.Writer
   691  }
   692  
   693  func (w *dictWriter) Write(b []byte) (n int, err error) {
   694  	return w.w.Write(b)
   695  }
   696  
   697  var errWriterClosed = errors.New("flate: closed writer")
   698  
   699  // A Writer takes data written to it and writes the compressed
   700  // form of that data to an underlying writer (see [NewWriter]).
   701  type Writer struct {
   702  	d    compressor
   703  	dict []byte
   704  }
   705  
   706  // Write writes data to w, which will eventually write the
   707  // compressed form of data to its underlying writer.
   708  func (w *Writer) Write(data []byte) (n int, err error) {
   709  	return w.d.write(data)
   710  }
   711  
   712  // Flush flushes any pending data to the underlying writer.
   713  // It is useful mainly in compressed network protocols, to ensure that
   714  // a remote reader has enough data to reconstruct a packet.
   715  // Flush does not return until the data has been written.
   716  // Calling Flush when there is no pending data still causes the [Writer]
   717  // to emit a sync marker of at least 4 bytes.
   718  // If the underlying writer returns an error, Flush returns that error.
   719  //
   720  // In the terminology of the zlib library, Flush is equivalent to Z_SYNC_FLUSH.
   721  func (w *Writer) Flush() error {
   722  	// For more about flushing:
   723  	// https://www.bolet.org/~pornin/deflate-flush.html
   724  	return w.d.syncFlush()
   725  }
   726  
   727  // Close flushes and closes the writer.
   728  func (w *Writer) Close() error {
   729  	return w.d.close()
   730  }
   731  
   732  // Reset discards the writer's state and makes it equivalent to
   733  // the result of [NewWriter] or [NewWriterDict] called with dst
   734  // and w's level and dictionary.
   735  func (w *Writer) Reset(dst io.Writer) {
   736  	if dw, ok := w.d.w.writer.(*dictWriter); ok {
   737  		// w was created with NewWriterDict
   738  		dw.w = dst
   739  		w.d.reset(dw)
   740  		w.d.fillWindow(w.dict)
   741  	} else {
   742  		// w was created with NewWriter
   743  		w.d.reset(dst)
   744  	}
   745  }
   746
View as plain text