1 // Package lz4 implements reading and writing lz4 compressed data. 2 // 3 // The package supports both the LZ4 stream format, 4 // as specified in http://fastcompression.blogspot.fr/2013/04/lz4-streaming-format-final.html, 5 // and the LZ4 block format, defined at 6 // http://fastcompression.blogspot.fr/2011/05/lz4-explained.html. 7 // 8 // See https://github.com/lz4/lz4 for the reference C implementation. 9 package lz4 10 11 import ( 12 "github.com/pierrec/lz4/v4/internal/lz4block" 13 "github.com/pierrec/lz4/v4/internal/lz4errors" 14 ) 15 16 func _() { 17 // Safety checks for duplicated elements. 18 var x [1]struct{} 19 _ = x[lz4block.CompressionLevel(Fast)-lz4block.Fast] 20 _ = x[Block64Kb-BlockSize(lz4block.Block64Kb)] 21 _ = x[Block256Kb-BlockSize(lz4block.Block256Kb)] 22 _ = x[Block1Mb-BlockSize(lz4block.Block1Mb)] 23 _ = x[Block4Mb-BlockSize(lz4block.Block4Mb)] 24 } 25 26 // CompressBlockBound returns the maximum size of a given buffer of size n, when not compressible. 27 func CompressBlockBound(n int) int { 28 return lz4block.CompressBlockBound(n) 29 } 30 31 // UncompressBlock uncompresses the source buffer into the destination one, 32 // and returns the uncompressed size. 33 // 34 // The destination buffer must be sized appropriately. 35 // 36 // An error is returned if the source data is invalid or the destination buffer is too small. 37 func UncompressBlock(src, dst []byte) (int, error) { 38 return lz4block.UncompressBlock(src, dst, nil) 39 } 40 41 // UncompressBlockWithDict uncompresses the source buffer into the destination one using a 42 // dictionary, and returns the uncompressed size. 43 // 44 // The destination buffer must be sized appropriately. 45 // 46 // An error is returned if the source data is invalid or the destination buffer is too small. 47 func UncompressBlockWithDict(src, dst, dict []byte) (int, error) { 48 return lz4block.UncompressBlock(src, dst, dict) 49 } 50 51 // A Compressor compresses data into the LZ4 block format. 52 // It uses a fast compression algorithm. 53 // 54 // A Compressor is not safe for concurrent use by multiple goroutines. 55 // 56 // Use a Writer to compress into the LZ4 stream format. 57 type Compressor struct{ c lz4block.Compressor } 58 59 // CompressBlock compresses the source buffer src into the destination dst. 60 // 61 // If compression is successful, the first return value is the size of the 62 // compressed data, which is always >0. 63 // 64 // If dst has length at least CompressBlockBound(len(src)), compression always 65 // succeeds. Otherwise, the first return value is zero. The error return is 66 // non-nil if the compressed data does not fit in dst, but it might fit in a 67 // larger buffer that is still smaller than CompressBlockBound(len(src)). The 68 // return value (0, nil) means the data is likely incompressible and a buffer 69 // of length CompressBlockBound(len(src)) should be passed in. 70 func (c *Compressor) CompressBlock(src, dst []byte) (int, error) { 71 return c.c.CompressBlock(src, dst) 72 } 73 74 // CompressBlock compresses the source buffer into the destination one. 75 // This is the fast version of LZ4 compression and also the default one. 76 // 77 // The argument hashTable is scratch space for a hash table used by the 78 // compressor. If provided, it should have length at least 1<<16. If it is 79 // shorter (or nil), CompressBlock allocates its own hash table. 80 // 81 // The size of the compressed data is returned. 82 // 83 // If the destination buffer size is lower than CompressBlockBound and 84 // the compressed size is 0 and no error, then the data is incompressible. 85 // 86 // An error is returned if the destination buffer is too small. 87 88 // CompressBlock is equivalent to Compressor.CompressBlock. 89 // The final argument is ignored and should be set to nil. 90 // 91 // This function is deprecated. Use a Compressor instead. 92 func CompressBlock(src, dst []byte, _ []int) (int, error) { 93 return lz4block.CompressBlock(src, dst) 94 } 95 96 // A CompressorHC compresses data into the LZ4 block format. 97 // Its compression ratio is potentially better than that of a Compressor, 98 // but it is also slower and requires more memory. 99 // 100 // A Compressor is not safe for concurrent use by multiple goroutines. 101 // 102 // Use a Writer to compress into the LZ4 stream format. 103 type CompressorHC struct { 104 // Level is the maximum search depth for compression. 105 // Values <= 0 mean no maximum. 106 Level CompressionLevel 107 c lz4block.CompressorHC 108 } 109 110 // CompressBlock compresses the source buffer src into the destination dst. 111 // 112 // If compression is successful, the first return value is the size of the 113 // compressed data, which is always >0. 114 // 115 // If dst has length at least CompressBlockBound(len(src)), compression always 116 // succeeds. Otherwise, the first return value is zero. The error return is 117 // non-nil if the compressed data does not fit in dst, but it might fit in a 118 // larger buffer that is still smaller than CompressBlockBound(len(src)). The 119 // return value (0, nil) means the data is likely incompressible and a buffer 120 // of length CompressBlockBound(len(src)) should be passed in. 121 func (c *CompressorHC) CompressBlock(src, dst []byte) (int, error) { 122 return c.c.CompressBlock(src, dst, lz4block.CompressionLevel(c.Level)) 123 } 124 125 // CompressBlockHC is equivalent to CompressorHC.CompressBlock. 126 // The final two arguments are ignored and should be set to nil. 127 // 128 // This function is deprecated. Use a CompressorHC instead. 129 func CompressBlockHC(src, dst []byte, depth CompressionLevel, _, _ []int) (int, error) { 130 return lz4block.CompressBlockHC(src, dst, lz4block.CompressionLevel(depth)) 131 } 132 133 const ( 134 // ErrInvalidSourceShortBuffer is returned by UncompressBlock or CompressBLock when a compressed 135 // block is corrupted or the destination buffer is not large enough for the uncompressed data. 136 ErrInvalidSourceShortBuffer = lz4errors.ErrInvalidSourceShortBuffer 137 // ErrInvalidFrame is returned when reading an invalid LZ4 archive. 138 ErrInvalidFrame = lz4errors.ErrInvalidFrame 139 // ErrInternalUnhandledState is an internal error. 140 ErrInternalUnhandledState = lz4errors.ErrInternalUnhandledState 141 // ErrInvalidHeaderChecksum is returned when reading a frame. 142 ErrInvalidHeaderChecksum = lz4errors.ErrInvalidHeaderChecksum 143 // ErrInvalidBlockChecksum is returned when reading a frame. 144 ErrInvalidBlockChecksum = lz4errors.ErrInvalidBlockChecksum 145 // ErrInvalidFrameChecksum is returned when reading a frame. 146 ErrInvalidFrameChecksum = lz4errors.ErrInvalidFrameChecksum 147 // ErrOptionInvalidCompressionLevel is returned when the supplied compression level is invalid. 148 ErrOptionInvalidCompressionLevel = lz4errors.ErrOptionInvalidCompressionLevel 149 // ErrOptionClosedOrError is returned when an option is applied to a closed or in error object. 150 ErrOptionClosedOrError = lz4errors.ErrOptionClosedOrError 151 // ErrOptionInvalidBlockSize is returned when 152 ErrOptionInvalidBlockSize = lz4errors.ErrOptionInvalidBlockSize 153 // ErrOptionNotApplicable is returned when trying to apply an option to an object not supporting it. 154 ErrOptionNotApplicable = lz4errors.ErrOptionNotApplicable 155 // ErrWriterNotClosed is returned when attempting to reset an unclosed writer. 156 ErrWriterNotClosed = lz4errors.ErrWriterNotClosed 157 ) 158