package flate
import "compress/flate"
Package flate 实现了 RFC 1951 中描述的 DEFLATE 压缩数据格式。
compress/gzip 和 compress/zlib 包实现了对基于 DEFLATE 的文件格式的访问。
A preset dictionary can be used to improve the compression ratio.
The downside to using a dictionary is that the compressor and decompressor
must agree in advance what dictionary to use.
Output: In performance critical applications, Reset can be used to discard the
current compressor or decompressor state and reinitialize them quickly
by taking advantage of previously allocated memory.
Output: DEFLATE is suitable for transmitting compressed data across the network.
Output:Example (Dictionary)
package main
import (
"bytes"
"compress/flate"
"fmt"
"io"
"log"
"os"
"strings"
)
func main() {
// The dictionary is a string of bytes. When compressing some input data,
// the compressor will attempt to substitute substrings with matches found
// in the dictionary. As such, the dictionary should only contain substrings
// that are expected to be found in the actual data stream.
const dict = `<?xml version="1.0"?>` + `<book>` + `<data>` + `<meta name="` + `" content="`
// The data to compress should (but is not required to) contain frequent
// substrings that match those in the dictionary.
const data = `<?xml version="1.0"?>
<book>
<meta name="title" content="The Go Programming Language"/>
<meta name="authors" content="Alan Donovan and Brian Kernighan"/>
<meta name="published" content="2015-10-26"/>
<meta name="isbn" content="978-0134190440"/>
<data>...</data>
</book>
`
var b bytes.Buffer
// Compress the data using the specially crafted dictionary.
zw, err := flate.NewWriterDict(&b, flate.DefaultCompression, []byte(dict))
if err != nil {
log.Fatal(err)
}
if _, err := io.Copy(zw, strings.NewReader(data)); err != nil {
log.Fatal(err)
}
if err := zw.Close(); err != nil {
log.Fatal(err)
}
// The decompressor must use the same dictionary as the compressor.
// Otherwise, the input may appear as corrupted.
fmt.Println("Decompressed output using the dictionary:")
zr := flate.NewReaderDict(bytes.NewReader(b.Bytes()), []byte(dict))
if _, err := io.Copy(os.Stdout, zr); err != nil {
log.Fatal(err)
}
if err := zr.Close(); err != nil {
log.Fatal(err)
}
fmt.Println()
// Substitute all of the bytes in the dictionary with a '#' to visually
// demonstrate the approximate effectiveness of using a preset dictionary.
fmt.Println("Substrings matched by the dictionary are marked with #:")
hashDict := []byte(dict)
for i := range hashDict {
hashDict[i] = '#'
}
zr = flate.NewReaderDict(&b, hashDict)
if _, err := io.Copy(os.Stdout, zr); err != nil {
log.Fatal(err)
}
if err := zr.Close(); err != nil {
log.Fatal(err)
}
}
Decompressed output using the dictionary:
<?xml version="1.0"?>
<book>
<meta name="title" content="The Go Programming Language"/>
<meta name="authors" content="Alan Donovan and Brian Kernighan"/>
<meta name="published" content="2015-10-26"/>
<meta name="isbn" content="978-0134190440"/>
<data>...</data>
</book>
Substrings matched by the dictionary are marked with #:
#####################
######
############title###########The Go Programming Language"/#
############authors###########Alan Donovan and Brian Kernighan"/#
############published###########2015-10-26"/#
############isbn###########978-0134190440"/#
######...</#####
</#####
Example (Reset)
package main
import (
"bytes"
"compress/flate"
"io"
"log"
"os"
"strings"
)
func main() {
proverbs := []string{
"Don't communicate by sharing memory, share memory by communicating.\n",
"Concurrency is not parallelism.\n",
"The bigger the interface, the weaker the abstraction.\n",
"Documentation is for users.\n",
}
var r strings.Reader
var b bytes.Buffer
buf := make([]byte, 32<<10)
zw, err := flate.NewWriter(nil, flate.DefaultCompression)
if err != nil {
log.Fatal(err)
}
zr := flate.NewReader(nil)
for _, s := range proverbs {
r.Reset(s)
b.Reset()
// Reset the compressor and encode from some input stream.
zw.Reset(&b)
if _, err := io.CopyBuffer(zw, &r, buf); err != nil {
log.Fatal(err)
}
if err := zw.Close(); err != nil {
log.Fatal(err)
}
// Reset the decompressor and decode to some output stream.
if err := zr.(flate.Resetter).Reset(&b, nil); err != nil {
log.Fatal(err)
}
if _, err := io.CopyBuffer(os.Stdout, zr, buf); err != nil {
log.Fatal(err)
}
if err := zr.Close(); err != nil {
log.Fatal(err)
}
}
}
Don't communicate by sharing memory, share memory by communicating.
Concurrency is not parallelism.
The bigger the interface, the weaker the abstraction.
Documentation is for users.
Example (Synchronization)
package main
import (
"compress/flate"
"fmt"
"io"
"log"
"strings"
"sync"
)
func main() {
var wg sync.WaitGroup
defer wg.Wait()
// Use io.Pipe to simulate a network connection.
// A real network application should take care to properly close the
// underlying connection.
rp, wp := io.Pipe()
// Start a goroutine to act as the transmitter.
wg.Add(1)
go func() {
defer wg.Done()
zw, err := flate.NewWriter(wp, flate.BestSpeed)
if err != nil {
log.Fatal(err)
}
b := make([]byte, 256)
for m := range strings.FieldsSeq("A long time ago in a galaxy far, far away...") {
// We use a simple framing format where the first byte is the
// message length, followed the message itself.
b[0] = uint8(copy(b[1:], m))
if _, err := zw.Write(b[:1+len(m)]); err != nil {
log.Fatal(err)
}
// Flush ensures that the receiver can read all data sent so far.
if err := zw.Flush(); err != nil {
log.Fatal(err)
}
}
if err := zw.Close(); err != nil {
log.Fatal(err)
}
}()
// Start a goroutine to act as the receiver.
wg.Add(1)
go func() {
defer wg.Done()
zr := flate.NewReader(rp)
b := make([]byte, 256)
for {
// Read the message length.
// This is guaranteed to return for every corresponding
// Flush and Close on the transmitter side.
if _, err := io.ReadFull(zr, b[:1]); err != nil {
if err == io.EOF {
break // The transmitter closed the stream
}
log.Fatal(err)
}
// Read the message content.
n := int(b[0])
if _, err := io.ReadFull(zr, b[:n]); err != nil {
log.Fatal(err)
}
fmt.Printf("Received %d bytes: %s\n", n, b[:n])
}
fmt.Println()
if err := zr.Close(); err != nil {
log.Fatal(err)
}
}()
}
Received 1 bytes: A
Received 4 bytes: long
Received 4 bytes: time
Received 3 bytes: ago
Received 2 bytes: in
Received 1 bytes: a
Received 6 bytes: galaxy
Received 4 bytes: far,
Received 3 bytes: far
Received 7 bytes: away...
Index
- Constants
- func NewReader(r io.Reader) io.ReadCloser
- func NewReaderDict(r io.Reader, dict []byte) io.ReadCloser
- type CorruptInputError
- type InternalError
- type ReadError deprecated
- type Reader
- type Resetter
- type WriteError deprecated
- type Writer
Examples
Constants
const ( NoCompression = 0 BestSpeed = 1 BestCompression = 9 DefaultCompression = -1 // HuffmanOnly 禁用 Lempel-Ziv 匹配搜索,仅执行 Huffman // 熵编码。该模式适用于压缩那些已经用 // LZ 风格算法(例如 Snappy 或 LZ4)压缩过、 // 但没有熵编码器的数据。当输入流中某些字节 // 出现的频率高于其他字节时,可以获得压缩收益。 // // 注意,HuffmanOnly 产生的压缩输出符合 // RFC 1951 规范。也就是说,任何有效的 DEFLATE 解压器 // 都能继续解压该输出。 HuffmanOnly = -2 )
Functions
func NewReader
func NewReader(r io.Reader) io.ReadCloser
NewReader 返回一个新的 ReadCloser,可用于 读取 r 的解压版本。 如果 r 没有同时实现 io.ByteReader, 解压器可能会从 r 读取比所需更多的数据。 在遇到 DEFLATE 流中的最后一个块之后, reader 返回 io.EOF。最后一个块之后的任何尾随数据都会被忽略。
NewReader 返回的 io.ReadCloser 还实现了 Resetter。
func NewReaderDict
func NewReaderDict(r io.Reader, dict []byte) io.ReadCloser
NewReaderDict 类似于 NewReader,但使用预设字典 初始化 reader。返回的 reader 的行为就像 未压缩数据流以给定的字典开头, 且该字典已被读取一样。NewReaderDict 通常用于 读取由 NewWriterDict 压缩的数据。
NewReaderDict 返回的 ReadCloser 还实现了 Resetter。
Types
type CorruptInputError
type CorruptInputError int64
CorruptInputError 报告在给定偏移处存在损坏的输入。
func (CorruptInputError) Error
func (e CorruptInputError) Error() string
type InternalError
type InternalError string
InternalError 报告 flate 代码自身中的错误。
func (InternalError) Error
func (e InternalError) Error() string
type ReadError deprecated
type ReadError struct { Offset int64 // 错误发生处的字节偏移量 Err error // 底层 Read 返回的错误 }
ReadError 报告读取输入时遇到的错误。
Deprecated: 不再返回。
func (*ReadError) Error
func (e *ReadError) Error() string
type Reader
type Reader interface { io.Reader io.ByteReader }
NewReader 所需的实际读取接口。 如果传入的 io.Reader 没有 ReadByte, NewReader 将引入自己的缓冲。
type Resetter
type Resetter interface { // Reset 丢弃所有缓冲数据,并将 Resetter 重置为 // 如同用给定 reader 新初始化一样。 Reset(r io.Reader, dict []byte) error }
Resetter 重置由 NewReader 或 NewReaderDict 返回的 ReadCloser,
以切换到新的底层 Reader。这样可以复用 ReadCloser,而无需分配新的。
WriteError 报告写入输出时遇到的错误。
Deprecated: 不再返回。
type WriteError deprecated
type WriteError struct {
Offset int64 // 错误发生处的字节偏移量
Err error // 底层 Write 返回的错误
}
func (*WriteError) Error
func (e *WriteError) Error() string
type Writer
type Writer struct { // contains filtered or unexported fields }
Writer 接收写入其中的数据,并将该数据的压缩 形式写入一个底层 writer(参见 NewWriter)。
func NewWriter
func NewWriter(w io.Writer, level int) (*Writer, error)
NewWriter 返回一个新的 Writer,它按给定等级压缩数据。 遵循 zlib 的规范,等级范围从 1(BestSpeed)到 9(BestCompression); 等级越高通常运行越慢,但压缩率越高。等级 0 (NoCompression)不尝试任何压缩;它只添加 必要的 DEFLATE 帧。 等级 -1(DefaultCompression)使用默认压缩等级。 等级 -2(HuffmanOnly)将仅使用 Huffman 压缩,从而 对所有类型的输入都提供非常快的压缩,但会牺牲相当多的 压缩效率。
若 level 在范围 [-2, 9] 内,返回的错误将为 nil。 否则返回的错误将非 nil。
func NewWriterDict
func NewWriterDict(w io.Writer, level int, dict []byte) (*Writer, error)
NewWriterDict 类似于 NewWriter,但会用预设的字典 初始化新的 Writer。返回的 Writer 的行为就如同 该字典已被写入其中且未产生任何压缩输出。 写入 w 的压缩数据只能由一个用相同字典 初始化的读取器解压(参见 NewReaderDict)。
func (*Writer) Close
func (w *Writer) Close() error
Close 刷新并关闭该 writer。
func (*Writer) Flush
func (w *Writer) Flush() error
Flush 将所有待处理的数据刷新到底层 writer。 它主要用于压缩网络协议中,以确保 远程读取器有足够的数据来重建一个数据包。 Flush 直到数据被写入后才返回。 在没有待处理数据时调用 Flush 仍会使 Writer 发出至少 4 个字节的同步标记。 如果底层 writer 返回错误,Flush 会返回该错误。
在 zlib 库的术语中,Flush 等价于 Z_SYNC_FLUSH。
func (*Writer) Reset
func (w *Writer) Reset(dst io.Writer)
Reset 丢弃 writer 的状态,使其等同于用 dst 以及 w 的等级和字典调用 NewWriter 或 NewWriterDict 所得到的结果。
func (*Writer) Write
func (w *Writer) Write(data []byte) (n int, err error)
Write 将数据写入 w,w 最终会将数据的压缩 形式写入其底层 writer。