Merge pull request astaxie#210 from rujews/master

提交compress、compress/bzip2、compress/flate、compress/lzw包示例

compress/README.md

@@ -1,5 +1,9 @@
-# Comprss
-
-二级包列表
-
-- [compress/gzip](gzip)
+# compress
+
+二级包列表
+
+- [compress/bzip2](bzip2)
+- [compress/flate](flate)
+- [compress/gzip](gzip)
+- [compress/lzw](lzw)
+- [compress/zlib](zlib)

compress/bzip2/NewReader.md

@@ -0,0 +1,56 @@
+# func NewReader(r io.Reader) io.Reader
+
+参数列表：
+
+- r bzip2压缩数据
+
+返回值：解压后的数据
+
+功能说明：
+
+返回一个从r读取bzip2压缩数据，然后返回一个解压后io.Reader
+
+示例：
+
+	package main
+
+	import (
+		"archive/tar"
+		"compress/bzip2"
+		"fmt"
+		"io"
+		"os"
+		"path"
+	)
+
+	func main() {
+		//打开一个bz2压缩文件
+		bzip2File, _ := os.Open("demo.tar.bz2")
+		defer bzip2File.Close()
+
+		//进行解压
+		r := bzip2.NewReader(bzip2File)
+		//使用tar读取输出文件
+		tr := tar.NewReader(r)
+		for {
+			tarHead, err := tr.Next()
+			if err == io.EOF {
+				break
+			}
+			if err != nil {
+				fmt.Println("the tar file err is ", err)
+				continue
+			}
+			fmt.Println(tarHead.Name)
+
+			os.MkdirAll(path.Dir(tarHead.Name), os.ModePerm)
+			fw, _ := os.Create(tarHead.Name)
+			defer fw.Close()
+
+			_, err = io.Copy(fw, tr)
+			if err != nil {
+				fmt.Println("copy file err is ", err)
+				continue
+			}
+		}
+	}

compress/bzip2/README.md

@@ -1,6 +1,6 @@
-# 包名
-
-函数列表
-
-- xxx1
-- xxx2
+# 包名 compress/bzip2
+
+函数列表
+
+- [func NewReader(r io.Reader) io.Reader](NewReader.md)
+- [func (s StructuralError) Error() string](StructuralError.Error.md)

compress/bzip2/StructuralError.Error.md

@@ -0,0 +1,40 @@
+# func (s StructuralError) Error() string
+
+返回值：非法的bzip2数据错误信息
+
+功能说明：StructuralError其实是一个string，他实现了error接口，用于很方便的返回非法的bzip2数据的错误信息
+
+示例：
+
+	package main
+
+	import (
+		"archive/tar"
+		"compress/bzip2"
+		"fmt"
+		"io"
+		"log"
+		"os"
+		"reflect"
+	)
+
+	func main() {
+		//打开一个非bzip2压缩文件
+		bzip2File, _ := os.Open("main.go")
+		defer bzip2File.Close()
+
+		//尝试进行解压
+		r := bzip2.NewReader(bzip2File)
+		//使用tar读取输出文件
+		tr := tar.NewReader(r)
+		for {
+			_, err := tr.Next()
+			if err == io.EOF {
+				break
+			}
+			if err != nil {
+				fmt.Println("the type is ", reflect.TypeOf(err))
+				log.Fatalln(err)
+			}
+		}
+	}

compress/flate/CorruptInputError.Error.md

@@ -0,0 +1,9 @@
+# func (e CorruptInputError) Error() string
+
+返回值：在输入的指定偏移量位置存在损坏的错误信息
+
+功能说明：CorruptInputError其实是一个int64，他实现了error接口，用于很方便的返回输入的指定偏移量位置存在损坏的错误信息
+
+示例：
+
+可能是一些读取、写入、拷贝等函数返回的error信息，这里不再举例。

compress/flate/InternalError.Error.md

@@ -0,0 +1,9 @@
+# func (e InternalError) Error() string
+
+返回值：表示flate数据自身的错误信息
+
+功能说明：InternalError其实是一个string，他实现了error接口，用于很方便的返回flate数据自身的错误信息
+
+示例：
+
+函数返回的error信息，这里不再举例。

compress/flate/NewReader.md

@@ -0,0 +1,46 @@
+# func NewReader(r io.Reader) io.ReadCloser
+
+参数列表
+
+- r DEFLATE压缩的数据
+
+返回值：解压后的ReadCloser数据 
+
+功能说明：
+
+从r读取DEFLATE压缩数据，返回一个解压过的io.ReadCloser，使用后需要调用者关闭该io.ReadCloser
+
+示例：
+
+	package main
+
+	import (
+		"bytes"
+		"compress/flate"
+		"fmt"
+		"io"
+		"log"
+		"os"
+	)
+
+	func main() {
+		//一个缓冲区存储压缩的内容
+		buf := bytes.NewBuffer(nil)
+
+		//创建一个flate.Writer
+		flateWrite, err := flate.NewWriter(buf, flate.BestCompression)
+		if err != nil {
+			log.Fatalln(err)
+		}
+		defer flateWrite.Close()
+		//写入待压缩内容
+		flateWrite.Write([]byte("compress/flate\n"))
+		flateWrite.Flush()
+		fmt.Println(buf)
+
+		//解压刚刚压缩的内容
+		flateReader := flate.NewReader(buf)
+		defer flateReader.Close()
+		//输出
+		io.Copy(os.Stdout, flateReader)
+	}

compress/flate/NewReaderDict.md

@@ -0,0 +1,48 @@
+# func NewReaderDict(r io.Reader, dict []byte) io.ReadCloser
+
+参数列表
+
+- r DEFLATE压缩的数据
+- dict 解压数据时预设的字典，和NewWriterDict函数里的dict相同
+
+返回值：解压后的ReadCloser数据 
+
+功能说明：
+
+从r读取DEFLATE压缩数据，使用预设的dict字典解压数据，返回一个解压过的io.ReadCloser，使用后需要调用者关闭该io.ReadCloser。主要用来读取NewWriterDict压缩的数据
+
+示例：
+
+	package main
+
+	import (
+		"bytes"
+		"compress/flate"
+		"fmt"
+		"io"
+		"log"
+		"os"
+	)
+
+	func main() {
+		//一个缓冲区存储压缩的内容
+		buf := bytes.NewBuffer(nil)
+
+		//创建一个flate.Writer
+		flateWrite, err := flate.NewWriterDict(buf, flate.BestCompression, []byte("key"))
+		if err != nil {
+			log.Fatalln(err)
+		}
+		defer flateWrite.Close()
+		//写入待压缩内容
+		flateWrite.Write([]byte("compress/flate\n"))
+		flateWrite.Flush()
+		fmt.Println(buf)
+
+		//解压刚刚压缩的内容
+		flateReader := flate.NewReaderDict(buf, []byte("key"))
+		//flateReader := flate.NewReader(buf)
+		defer flateReader.Close()
+		//输出
+		io.Copy(os.Stdout, flateReader)
+	}

compress/flate/NewWriter.md

@@ -0,0 +1,44 @@
+# func NewWriter(w io.Writer, level int) (*Writer, error)
+
+参数列表；
+
+* w 输出数据的Writer
+* level 压缩级别
+
+返回列表：
+
+* *Writer 基于压缩级别新生成的压缩数据的Writer
+* error 该函数的错误信息
+
+功能说明：
+
+该函数返回一个压缩级别为level的新的压缩用的Writer。压缩级别的范围是1 (BestSpeed) to 9 (BestCompression)。压缩效果越好的意味着压缩速度越慢。0 (NoCompression)表示不做任何压缩；仅仅只需要添加必要的DEFLATE信息。-1 (DefaultCompression)表示用默认的压缩级别。
+如果压缩级别在-1到9的范围内，error返回nil，否则将返回非nil的错误信息
+
+示例：
+
+	package main
+
+	import (
+		"bytes"
+		"compress/flate"
+		"fmt"
+		"log"
+	)
+
+	func main() {
+		//一个缓冲区存储压缩的内容
+		buf := bytes.NewBuffer(nil)
+
+		//创建一个flate.Writer，压缩级别最好
+		flateWrite, err := flate.NewWriter(buf, flate.BestCompression)
+		if err != nil {
+			log.Fatalln(err)
+		}
+		defer flateWrite.Close()
+		//写入待压缩内容
+		flateWrite.Write([]byte("compress/flate\n"))
+		flateWrite.Flush()
+		fmt.Println(buf)
+
+	}

compress/flate/NewWriterDict.md

@@ -0,0 +1,44 @@
+# func NewWriterDict(w io.Writer, level int, dict []byte) (*Writer, error)
+
+参数列表；
+
+* w 输出数据的Writer
+* level 压缩级别
+* dict 压缩预设字典
+
+返回列表：
+
+* *Writer 基于压缩级别和预设字典新生成的压缩数据的Writer
+* error 该函数的错误信息
+
+功能说明：
+
+该函数和NewWriter差不多，只不过使用了预设字典进行初始化Writer，使用该Writer压缩的数据只能被使用同样字典初始化的Reader解压。可以实现基于密码的解压缩。
+
+示例：
+
+	package main
+
+	import (
+		"bytes"
+		"compress/flate"
+		"fmt"
+		"log"
+	)
+
+	func main() {
+		//一个缓冲区存储压缩的内容
+		buf := bytes.NewBuffer(nil)
+
+		//创建一个flate.Writer，压缩级别最好
+		flateWrite, err := flate.NewWriterDict(buf, flate.BestCompression,[]byte("key"))
+		if err != nil {
+			log.Fatalln(err)
+		}
+		defer flateWrite.Close()
+		//写入待压缩内容
+		flateWrite.Write([]byte("compress/flate\n"))
+		flateWrite.Flush()
+		fmt.Println(buf)
+
+	}

compress/flate/README.md

@@ -1,6 +1,26 @@
-# 包名
-
-函数列表
-
-- xxx1
-- xxx2
+# 包名 compress/flate
+
+常量列表
+
+    const (
+        NoCompression = 0//不压缩
+        BestSpeed     = 1//最快速度压缩
+
+        BestCompression    = 9//最佳压缩比压缩
+        DefaultCompression = -1//默认压缩
+    )
+
+函数列表
+
+- [func NewReader(r io.Reader) io.ReadCloser](NewReader.md)
+- [func NewReaderDict(r io.Reader, dict []byte) io.ReadCloser](NewReaderDict.md)
+- [func (e CorruptInputError) Error() string](CorruptInputError.Error.md)
+- [func (e InternalError) Error() string](InternalError.Error.md)
+- [func (e *ReadError) Error() string](ReadError.Error.md)
+- [func (e *WriteError) Error() string](WriteError.Error.md)
+- [func NewWriter(w io.Writer, level int) (*Writer, error)](NewWriter.md)
+- [func NewWriterDict(w io.Writer, level int, dict []byte) (*Writer, error)](NewWriterDict.md)
+- [func (w *Writer) Close() error](Writer.Close.md)
+- [func (w *Writer) Flush() error](Writer.Flush.md)
+- [func (w *Writer) Reset(dst io.Writer)](Writer.Reset.md)
+- [func (w *Writer) Write(data []byte) (n int, err error)](Writer.Write.md)

compress/flate/ReadError.Error.md

@@ -0,0 +1,9 @@
+# func (e *ReadError) Error() string
+
+返回值：表示flate读取拷贝数据时的错误信息
+
+功能说明：ReadError其实是一个struct，他实现了error接口，用于很方便的返回flate读取拷贝数据时的错误信息
+
+示例：
+
+flate读取拷贝数据时的错误信息，这里不再举例。

compress/flate/WriteError.Error.md

@@ -0,0 +1,9 @@
+# func (e *WriteError) Error() string
+
+返回值：表示flate输出数据的错误信息
+
+功能说明：WriteError是一个struct，他实现了error接口，用于很方便的返回flate输出数据的错误信息
+
+示例：
+
+返回输出数据的错误信息，这里不再举例。