Golang標準庫——io-有解無憂

原文：Golang標準庫——io

1、io

io包提供了對I/O原語的基本介面，本包的基本任務是包裝這些原語已有的實作（如os包里的原語），使之成為共享的公共介面，這些公共介面抽象出了泛用的函式并附加了一些相關的原語的操作，

因為這些介面和原語是對底層實作完全不同的低水平操作的包裝，除非得到其它方面的通知，客戶端不應假設它們是并發執行安全的，

1.1 常量

Seek 值，

const (
        SeekStart   = 0 // 尋找相對于檔案的起源
        SeekCurrent = 1 // 尋找相對于當前的偏移量
        SeekEnd     = 2 // 尋求相對于目的
)

1.2 Variables

var EOF = errors.New("EOF")

EOF當無法得到更多輸入時，Read方法回傳EOF，當函式一切正常的到達輸入的結束時，就應回傳EOF，如果在一個結構化資料流中EOF在不期望的位置出現了，則應回傳錯誤ErrUnexpectedEOF或者其它給出更多細節的錯誤，

var ErrClosedPipe = errors.New("io: read/write on closed pipe")

當從一個已關閉的Pipe讀取或者寫入時，會回傳ErrClosedPipe，

var ErrNoProgress = errors.New("multiple Read calls return no data or error")

某些使用io.Reader介面的客戶端如果多次呼叫Read都不回傳資料也不回傳錯誤時，就會回傳本錯誤，一般來說是io.Reader的實作有問題的標志，

var ErrShortBuffer = errors.New("short buffer")

ErrShortBuffer表示讀取操作需要大緩沖，但提供的緩沖不夠大，

var ErrShortWrite = errors.New("short write")

ErrShortWrite表示寫入操作寫入的資料比提供的少，卻沒有顯式的回傳錯誤，

var ErrUnexpectedEOF = errors.New("unexpected EOF")

ErrUnexpectedEOF表示在讀取一個固定尺寸的塊或者資料結構時，在讀取未完全時遇到了EOF，

1.3 type Reader

type Reader interface {
    Read(p []byte) (n int, err error)
}

Reader介面用于包裝基本的讀取方法，

Read方法讀取len(p)位元組資料寫入p，它回傳寫入的位元組數和遇到的任何錯誤，即使Read方法回傳值n < len(p)，本方法在被呼叫時仍可能使用p的全部長度作為暫存空間，如果有部分可用資料，但不夠len(p)位元組，Read按慣例會回傳可以讀取到的資料，而不是等待更多資料，

當Read在讀取n > 0個位元組后遭遇錯誤或者到達檔案結尾時，會回傳讀取的位元組數，它可能會在該次呼叫回傳一個非nil的錯誤，或者在下一次呼叫時回傳0和該錯誤，一個常見的例子，Reader介面會在輸入流的結尾回傳非0的位元組數，回傳值err == EOF或err == nil，但不管怎樣，下一次Read呼叫必然回傳(0, EOF)，呼叫者應該總是先處理讀取的n > 0位元組再處理錯誤值，這么做可以正確的處理發生在讀取部分資料后的I/O錯誤，也能正確處理EOF事件，

如果Read的某個實作回傳0位元組數和nil錯誤值，表示被阻礙；呼叫者應該將這種情況視為未進行操作，

1.4 type Writer

type Writer interface {
    Write(p []byte) (n int, err error)
}

Writer介面用于包裝基本的寫入方法，

Write方法len(p) 位元組資料從p寫入底層的資料流，它會回傳寫入的位元組數(0 <= n <= len(p))和遇到的任何導致寫入提前結束的錯誤，Write必須回傳非nil的錯誤，如果它回傳的 n < len(p)，Write不能修改切片p中的資料，即使臨時修改也不行，

1.5 type Closer

type Closer interface {
    Close() error
}

Closer介面用于包裝基本的關閉方法，

在第一次呼叫之后再次被呼叫時，Close方法的的行為是未定義的，某些實作可能會說明他們自己的行為，

1.6 type Seeker

type Seeker interface {
    Seek(offset int64, whence int) (int64, error)
}

Seeker介面用于包裝基本的移位方法，

Seek方法設定下一次讀寫的位置：偏移量為offset，校準點由whence確定：0表示相對于檔案起始；1表示相對于當前位置；2表示相對于檔案結尾，Seek方法回傳新的位置以及可能遇到的錯誤，

移動到一個絕對偏移量為負數的位置會導致錯誤，移動到任何偏移量為正數的位置都是合法的，但其下一次I/O操作的具體行為則要看底層的實作，

1.7 type ReadCloser

type ReadCloser interface {
    Reader
    Closer
}

ReadCloser介面聚合了基本的讀取和關閉操作，

1.8 type ReadSeeker

type ReadSeeker interface {
    Reader
    Seeker
}

ReadSeeker介面聚合了基本的讀取和移位操作，

1.9 type WriteCloser

type WriteCloser interface {
    Writer
    Closer
}

WriteCloser介面聚合了基本的寫入和關閉操作，

1.10 type WriteSeeker

type WriteSeeker interface {
    Writer
    Seeker
}

WriteSeeker介面聚合了基本的寫入和移位操作，

1.11 type ReadWriter

type ReadWriter interface {
    Reader
    Writer
}

ReadWriter介面聚合了基本的讀寫操作，

1.12 type ReadWriteCloser

type ReadWriteCloser interface {
    Reader
    Writer
    Closer
}

ReadWriteCloser介面聚合了基本的讀寫和關閉操作，

1.13 type ReadWriteSeeker

type ReadWriteSeeker interface {
    Reader
    Writer
    Seeker
}

ReadWriteSeeker介面聚合了基本的讀寫和移位操作，

1.14 type ReaderAt

type ReaderAt interface {
    ReadAt(p []byte, off int64) (n int, err error)
}

ReaderAt介面包裝了基本的ReadAt方法，

ReadAt從底層輸入流的偏移量off位置讀取len(p)位元組資料寫入p，它回傳讀取的位元組數(0 <= n <= len(p))和遇到的任何錯誤，當ReadAt方法回傳值n < len(p)時，它會回傳一個非nil的錯誤來說明為啥沒有讀取更多的位元組，在這方面，ReadAt是比Read要嚴格的，即使ReadAt方法回傳值 n < len(p)，它在被呼叫時仍可能使用p的全部長度作為暫存空間，如果有部分可用資料，但不夠len(p)位元組，ReadAt會阻塞直到獲取len(p)個位元組資料或者遇到錯誤，在這方面，ReadAt和Read是不同的，如果ReadAt回傳時到達輸入流的結尾，而回傳值n == len(p)，其回傳值err既可以是EOF也可以是nil，

如果ReadAt是從某個有偏移量的底層輸入流（的Reader包裝）讀取，ReadAt方法既不應影響底層的偏移量，也不應被底層的偏移量影響，

ReadAt方法的呼叫者可以對同一輸入流執行并行的ReadAt呼叫，

1.15 type WriterAt

type WriterAt interface {
    WriteAt(p []byte, off int64) (n int, err error)
}

WriterAt介面包裝了基本的WriteAt方法，

WriteAt將p全部len(p)位元組資料寫入底層資料流的偏移量off位置，它回傳寫入的位元組數(0 <= n <= len(p))和遇到的任何導致寫入提前中止的錯誤，當其回傳值n < len(p)時，WriteAt必須放哪會一個非nil的錯誤，

如果WriteAt寫入的物件是某個有偏移量的底層輸出流（的Writer包裝），WriteAt方法既不應影響底層的偏移量，也不應被底層的偏移量影響，

ReadAt方法的呼叫者可以對同一輸入流執行并行的WriteAt呼叫，（前提是寫入范圍不重疊）

1.16 type ByteReader

type ByteReader interface {
    ReadByte() (c byte, err error)
}

ByteReader是基本的ReadByte方法的包裝，

ReadByte讀取輸入中的單個位元組并回傳，如果沒有位元組可讀取，會回傳錯誤，

1.17 type ByteScanner

type ByteScanner interface {
    ByteReader
    UnreadByte() error
}

ByteScanner介面在基本的ReadByte方法之外還添加了UnreadByte方法，

UnreadByte方法讓下一次呼叫ReadByte時回傳之前呼叫ReadByte時回傳的同一個位元組，連續呼叫兩次UnreadByte方法而中間沒有呼叫ReadByte時，可能會導致錯誤，

1.18 type RuneReader

type RuneReader interface {
    ReadRune() (r rune, size int, err error)
}

RuneReader是基本的ReadRune方法的包裝，

ReadRune讀取單個utf-8編碼的字符，回傳該字符和它的位元組長度，如果沒有有效的字符，會回傳錯誤，

1.19 type RuneScanner

type RuneScanner interface {
    RuneReader
    UnreadRune() error
}

RuneScanner介面在基本的ReadRune方法之外還添加了UnreadRune方法，

UnreadRune方法讓下一次呼叫ReadRune時回傳之前呼叫ReadRune時回傳的同一個utf-8字符，連續呼叫兩次UnreadRune方法而中間沒有呼叫ReadRune時，可能會導致錯誤，

1.20 type ByteWriter

type ByteWriter interface {
    WriteByte(c byte) error
}

ByteWriter是基本的WriteByte方法的包裝，

1.21 type ReaderFrom

type ReaderFrom interface {
    ReadFrom(r Reader) (n int64, err error)
}

ReaderFrom介面包裝了基本的ReadFrom方法，

ReadFrom方法從r讀取資料直到EOF或者遇到錯誤，回傳值n是讀取的位元組數，執行時遇到的錯誤（EOF除外）也會被回傳，

1.22 type WriterTo

type WriterTo interface {
    WriteTo(w Writer) (n int64, err error)
}

WriterTo介面包裝了基本的WriteTo方法，

WriteTo方法將資料寫入w直到沒有資料可以寫入或者遇到錯誤，回傳值n是寫入的位元組數，執行時遇到的任何錯誤也會被回傳，

1.23 type LimitedReader

type LimitedReader struct {
    R   Reader // 底層Reader介面
    N   int64  // 剩余可讀取位元組數
}

LimitedReader從R中讀取資料，但限制可以讀取的資料的量為最多N位元組，每次呼叫Read方法都會更新N以標記剩余可以讀取的位元組數，

1.23.1 func LimitReader

func LimitReader(r Reader, n int64) Reader

回傳一個Reader，它從r中讀取n個位元組后以EOF停止，回傳值介面的底層為*LimitedReader型別，

1.23.2 func (*LimitedReader) Read

func (l *LimitedReader) Read(p []byte) (n int, err error)

1.24 type SectionReader

type SectionReader struct {
    // 內含隱藏或非匯出欄位
}

SectionReader實作了對底層滿足ReadAt介面的輸入流某個片段的Read、ReadAt、Seek方法，

1.24.1 func NewSectionReader

func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader

回傳一個從r中的偏移量off處為起始，讀取n個位元組后以EOF停止的SectionReader，

1.24.2 func (*SectionReader) Size

func (s *SectionReader) Size() int64

Size回傳該片段的位元組數，

1.24.3 func (*SectionReader) Read

func (s *SectionReader) Read(p []byte) (n int, err error)

1.24.4 func (*SectionReader) ReadAt

func (s *SectionReader) ReadAt(p []byte, off int64) (n int, err error)

1.24.5 func (*SectionReader) Seek

func (s *SectionReader) Seek(offset int64, whence int) (int64, error)

1.25 type PipeReader

type PipeReader struct {
    // 內含隱藏或非匯出欄位
}

PipeReader是一個管道的讀取端，

1.25.1 func Pipe

func Pipe() (*PipeReader, *PipeWriter)

Pipe創建一個同步的記憶體中的管道，它可以用于連接期望io.Reader的代碼和期望io.Writer的代碼，一端的讀取對應另一端的寫入，直接在兩端拷貝資料，沒有內部緩沖，可以安全的并行呼叫Read和Write或者Read/Write與Close方法，Close方法會在最后一次阻塞中的I/O操作結束后完成，并行呼叫Read或并行呼叫Write也是安全的：每一個獨立的呼叫會依次進行，

1.25.2 func (*PipeReader) Read

func (r *PipeReader) Read(data []byte) (n int, err error)

Read實作了標準Reader介面：它從管道中讀取資料，會阻塞直到寫入端開始寫入或寫入端被關閉，

1.25.3 func (*PipeReader) Close

func (r *PipeReader) Close() error

Close關閉讀取器；關閉后如果對管道的寫入端進行寫入操作，就會回傳(0, ErrClosedPip)，

1.25.4 func (*PipeReader) CloseWithError

func (r *PipeReader) CloseWithError(err error) error

CloseWithError類似Close方法，但將呼叫Write時回傳的錯誤改為err，

1.26 type PipeWriter

type PipeWriter struct {
    // 內含隱藏或非匯出欄位
}

PipeWriter是一個管道的寫入端，

1.26.1 func (*PipeWriter) Write

func (w *PipeWriter) Write(data []byte) (n int, err error)

Write實作了標準Writer介面：它將資料寫入到管道中，會阻塞直到讀取器讀完所有的資料或讀取端被關閉，

1.26.2 func (*PipeWriter) Close

func (w *PipeWriter) Close() error

Close關閉寫入器；關閉后如果對管道的讀取端進行讀取操作，就會回傳(0, EOF)，

1.26.3 func (*PipeWriter) CloseWithError

func (w *PipeWriter) CloseWithError(err error) error

CloseWithError類似Close方法，但將呼叫Read時回傳的錯誤改為err，

1.27 func TeeReader

func TeeReader(r Reader, w Writer) Reader

TeeReader回傳一個將其從r讀取的資料寫入w的Reader介面，所有通過該介面對r的讀取都會執行對應的對w的寫入，沒有內部的緩沖：寫入必須在讀取完成前完成，寫入時遇到的任何錯誤都會作為讀取錯誤回傳，

1.28 func MultiReader

func MultiReader(readers ...Reader) Reader

MultiReader回傳一個將提供的Reader在邏輯上串聯起來的Reader介面，他們依次被讀取，當所有的輸入流都讀取完畢，Read才會回傳EOF，如果readers中任一個回傳了非nil非EOF的錯誤，Read方法會回傳該錯誤，

1.29 func MultiWriter

func MultiWriter(writers ...Writer) Writer

MultiWriter創建一個Writer介面，會將提供給其的資料寫入所有創建時提供的Writer介面，

1.30 func Copy

func Copy(dst Writer, src Reader) (written int64, err error)

將src的資料拷貝到dst，直到在src上到達EOF或發生錯誤，回傳拷貝的位元組數和遇到的第一個錯誤，

對成功的呼叫，回傳值err為nil而非EOF，因為Copy定義為從src讀取直到EOF，它不會將讀取到EOF視為應報告的錯誤，如果src實作了WriterTo介面，本函式會呼叫src.WriteTo(dst)進行拷貝；否則如果dst實作了ReaderFrom介面，本函式會呼叫dst.ReadFrom(src)進行拷貝，

1.31 func CopyN

func CopyN(dst Writer, src Reader, n int64) (written int64, err error)

從src拷貝n個位元組資料到dst，直到在src上到達EOF或發生錯誤，回傳復制的位元組數和遇到的第一個錯誤，

只有err為nil時，written才會等于n，如果dst實作了ReaderFrom介面，本函式很呼叫它實作拷貝，

1.32 func ReadAtLeast

func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error)

ReadAtLeast從r至少讀取min位元組資料填充進buf，函式回傳寫入的位元組數和錯誤（如果沒有讀取足夠的位元組），只有沒有讀取到位元組時才可能回傳EOF；如果讀取了有但不夠的位元組時遇到了EOF，函式會回傳ErrUnexpectedEOF，如果min比buf的長度還大，函式會回傳ErrShortBuffer，只有回傳值err為nil時，回傳值n才會不小于min，

1.33 func ReadFull

func ReadFull(r Reader, buf []byte) (n int, err error)

ReadFull從r精確地讀取len(buf)位元組資料填充進buf，函式回傳寫入的位元組數和錯誤（如果沒有讀取足夠的位元組），只有沒有讀取到位元組時才可能回傳EOF；如果讀取了有但不夠的位元組時遇到了EOF，函式會回傳ErrUnexpectedEOF，只有回傳值err為nil時，回傳值n才會等于len(buf)，

1.34 func WriteString

func WriteString(w Writer, s string) (n int, err error)

WriteString函式將字串s的內容寫入w中，如果w已經實作了WriteString方法，函式會直接呼叫該方法，

2、ioutil

ioutil包實作了一些實用的io介面，

2.1 Variables

var Discard io.Writer = devNull(0)

Discard是一個io.Writer介面，對它的所有Write呼叫都會無實際操作的成功回傳，

2.2 func NopCloser

func NopCloser(r io.Reader) io.ReadCloser

NopCloser用一個無操作的Close方法包裝r回傳一個ReadCloser介面，

2.3 func ReadAll

func ReadAll(r io.Reader) ([]byte, error)

ReadAll從r讀取資料直到EOF或遇到error，回傳讀取的資料和遇到的錯誤，成功的呼叫回傳的err為nil而非EOF，因為本函式定義為讀取r直到EOF，它不會將讀取回傳的EOF視為應報告的錯誤，

2.4 func ReadFile

func ReadFile(filename string) ([]byte, error)

ReadFile 從filename指定的檔案中讀取資料并回傳檔案的內容，成功的呼叫回傳的err為nil而非EOF，因為本函式定義為讀取整個檔案，它不會將讀取回傳的EOF視為應報告的錯誤，

2.5 func WriteFile

func WriteFile(filename string, data []byte, perm os.FileMode) error

函式向filename指定的檔案中寫入資料，如果檔案不存在將按給出的權限創建檔案，否則在寫入資料之前清空檔案，

2.6 func ReadDir

func ReadDir(dirname string) ([]os.FileInfo, error)

回傳dirname指定的目錄的目錄資訊的有序串列，

func main() {
   rd, err := ioutil.ReadDir("D://")
   fmt.Println(err)
   for _, fi := range rd {
      if fi.IsDir() {
         fmt.Printf("[%s]\n", fi.Name())

      } else {
         fmt.Println(fi.Name())
      }
   }
}

2.7 func TempDir

func TempDir(dir, prefix string) (name string, err error)

在dir目錄里創建一個新的、使用prfix作為前綴的臨時檔案夾，并回傳檔案夾的路徑，如果dir是空字串，TempDir使用默認用于臨時檔案的目錄（參見os.TempDir函式），不同程式同時呼叫該函式會創建不同的臨時目錄，呼叫本函式的程式有責任在不需要臨時檔案夾時摧毀它，

2.8 func TempFile

func TempFile(dir, prefix string) (f *os.File, err error)

在dir目錄下創建一個新的、使用prefix為前綴的臨時檔案，以讀寫模式打開該檔案并回傳os.File指標，如果dir是空字串，TempFile使用默認用于臨時檔案的目錄（參見os.TempDir函式），不同程式同時呼叫該函式會創建不同的臨時檔案，呼叫本函式的程式有責任在不需要臨時檔案時摧毀它，

// 示例：臨時目錄、臨時檔案
func main() {
   // 創建臨時目錄
   dir, err := ioutil.TempDir("", "Test")
   if err != nil {
      fmt.Println(err)
   }
   defer os.Remove(dir) // 用完洗掉
   fmt.Printf("%s\n", dir)

   // 創建臨時檔案
   f, err := ioutil.TempFile(dir, "Test")
   if err != nil {
      fmt.Println(err)
   }
   defer os.Remove(f.Name()) // 用完洗掉
   fmt.Printf("%s\n", f.Name())
}

轉載請註明出處，本文鏈接：https://www.uj5u.com/qita/554231.html

標籤：其他

上一篇：2023年18個最佳的ChatGPT AI插件

下一篇：返回列表