package gzip · Go 標準庫中文參考

# package gzip `import "compress/gzip"` gzip包實現了gzip格式壓縮文件的讀寫，參見[RFC 1952](http://tools.ietf.org/html/rfc1952)。 ## Index * [Constants](#pkg-constants) * [Variables](#pkg-variables) * [type Header](#Header) * [type Reader](#Reader) * [func NewReader(r io.Reader) (\*Reader, error)](#NewReader) * [func (z \*Reader) Reset(r io.Reader) error](#Reader.Reset) * [func (z \*Reader) Read(p []byte) (n int, err error)](#Reader.Read) * [func (z \*Reader) Close() error](#Reader.Close) * [type Writer](#Writer) * [func NewWriter(w io.Writer) \*Writer](#NewWriter) * [func NewWriterLevel(w io.Writer, level int) (\*Writer, error)](#NewWriterLevel) * [func (z \*Writer) Reset(w io.Writer)](#Writer.Reset) * [func (z \*Writer) Write(p []byte) (int, error)](#Writer.Write) * [func (z \*Writer) Flush() error](#Writer.Flush) * [func (z \*Writer) Close() error](#Writer.Close) ## Constants ``` const ( NoCompression = flate.NoCompression BestSpeed = flate.BestSpeed BestCompression = flate.BestCompression DefaultCompression = flate.DefaultCompression ) ``` 這些常量都是拷貝自flate包，因此導入"compress/gzip"后，就不必再導入"compress/flate"了。 ## Variables ``` var ( // 當讀取的gzip數據的校驗和錯誤時，會返回ErrChecksum ErrChecksum = errors.New("gzip: invalid checksum") // 當讀取的gzip數據的頭域錯誤時，會返回ErrHeader ErrHeader = errors.New("gzip: invalid header") ) ``` ## type [Header](https://github.com/golang/go/blob/master/src/compress/gzip/gunzip.go#L46 "View Source") ``` type Header struct { Comment string // 注釋 Extra []byte // 額外數據 ModTime time.Time // 修改時間 Name string // 文件名 OS byte // 操作系統類型 } ``` gzip文件保存一個頭域，提供關于被壓縮的文件的一些元數據。該頭域作為Writer和Reader類型的一個可導出字段，可以提供給調用者訪問。 ## type [Reader](https://github.com/golang/go/blob/master/src/compress/gzip/gunzip.go#L68 "View Source") ``` type Reader struct { Header // 內含隱藏或非導出字段 } ``` Reader類型滿足io.Reader接口，可以從gzip格式壓縮文件讀取并解壓數據。一般，一個gzip文件可以是多個gzip文件的串聯，每一個都有自己的頭域。從Reader讀取數據會返回串聯的每個文件的解壓數據，但只有第一個文件的頭域被記錄在Reader的Header字段里。 gzip文件會保存未壓縮數據的長度與校驗和。當讀取到未壓縮數據的結尾時，如果數據的長度或者校驗和不正確，Reader會返回ErrCheckSum。因此，調用者應該將Read方法返回的數據視為暫定的，直到他們在數據結尾獲得了一個io.EOF。 ### func [NewReader](https://github.com/golang/go/blob/master/src/compress/gzip/gunzip.go#L82 "View Source") ``` func NewReader(r io.Reader) (*Reader, error) ``` NewReader返回一個從r讀取并解壓數據的\*Reader。其實現會緩沖輸入流的數據，并可能從r中讀取比需要的更多的數據。調用者有責任在讀取完畢后調用返回值的Close方法。 ### func (\*Reader) [Reset](https://github.com/golang/go/blob/master/src/compress/gzip/gunzip.go#L95 "View Source") ``` func (z *Reader) Reset(r io.Reader) error ``` Reset將z重置，丟棄當前的讀取狀態，并將下層讀取目標設為r。效果上等價于將z設為使用r重新調用NewReader返回的Reader。這讓我們可以重用z而不是再申請一個新的。（因此效率更高） ### func (\*Reader) [Read](https://github.com/golang/go/blob/master/src/compress/gzip/gunzip.go#L214 "View Source") ``` func (z *Reader) Read(p []byte) (n int, err error) ``` ### func (\*Reader) [Close](https://github.com/golang/go/blob/master/src/compress/gzip/gunzip.go#L255 "View Source") ``` func (z *Reader) Close() error ``` 調用Close會關閉z，但不會關閉下層io.Reader接口。 ## type [Writer](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L27 "View Source") ``` type Writer struct { Header // 內含隱藏或非導出字段 } ``` Writer滿足io.WriteCloser接口。它會將提供給它的數據壓縮后寫入下層io.Writer接口。 ### func [NewWriter](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L51 "View Source") ``` func NewWriter(w io.Writer) *Writer ``` NewWriter創建并返回一個Writer。寫入返回值的數據都會在壓縮后寫入w。調用者有責任在結束寫入后調用返回值的Close方法。因為寫入的數據可能保存在緩沖中沒有刷新入下層。如要設定Writer.Header字段，調用者必須在第一次調用Write方法或者Close方法之前設置。Header字段的Comment和Name字段是go的utf-8字符串，但下層格式要求為NUL中止的ISO 8859-1 (Latin-1)序列。如果這兩個字段的字符串包含NUL或非Latin-1字符，將導致Write方法返回錯誤。 ### func [NewWriterLevel](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L62 "View Source") ``` func NewWriterLevel(w io.Writer, level int) (*Writer, error) ``` NewWriterLevel類似NewWriter但指定了壓縮水平而不是采用默認的DefaultCompression。參數level可以是DefaultCompression、NoCompression或BestSpeed與BestCompression之間包括二者的任何整數。如果level合法，返回的錯誤值為nil。 ### func (\*Writer) [Reset](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L97 "View Source") ``` func (z *Writer) Reset(w io.Writer) ``` Reset將z重置，丟棄當前的寫入狀態，并將下層輸出目標設為dst。效果上等價于將w設為使用dst和w的壓縮水平重新調用NewWriterLevel返回的\*Writer。這讓我們可以重用z而不是再申請一個新的。（因此效率更高） ### func (\*Writer) [Write](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L161 "View Source") ``` func (z *Writer) Write(p []byte) (int, error) ``` Write將p壓縮后寫入下層io.Writer接口。壓縮后的數據不一定會立刻刷新，除非Writer被關閉或者顯式的刷新。 ### func (\*Writer) [Flush](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L231 "View Source") ``` func (z *Writer) Flush() error ``` Flush將緩沖中的壓縮數據刷新到下層io.Writer接口中。本方法主要用在傳輸壓縮數據的網絡連接中，以保證遠端的接收者可以獲得足夠的數據來重構數據報。Flush會阻塞直到所有緩沖中的數據都寫入下層io.Writer接口后才返回。如果下層的io.Writetr接口返回一個錯誤，Flush也會返回該錯誤。在zlib包的術語中，Flush方法等價于Z_SYNC_FLUSH。 ### func (\*Writer) [Close](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L250 "View Source") ``` func (z *Writer) Close() error ``` 調用Close會關閉z，但不會關閉下層io.Writer接口。