package flate

import "compress/flate"

Package flate 实现了 RFC 1951 中描述的 DEFLATE 压缩数据格式。 compress/gzip 和 compress/zlib 包实现了对基于 DEFLATE 的文件格式的访问。

Example (Dictionary)

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.

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)
	}

}

Output:

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)

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.

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)
		}
	}

}

Output:

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)

DEFLATE is suitable for transmitting compressed data across the network.

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)
		}
	}()

}

Output:

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

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,而无需分配新的。

type WriteError deprecated

type WriteError struct {
	Offset int64 // 错误发生处的字节偏移量
	Err    error // 底层 Write 返回的错误
}

WriteError 报告写入输出时遇到的错误。

Deprecated: 不再返回。

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。