ioKit

Documentation

Index

• Variables
• func Close(closers ...io.Closer) error
• func CloseSingle(closer io.Closer) error
• func CountLines(r io.Reader) (count int, err error)
• func CountLines1(r io.Reader) (int, error)
• func MultiWriteCloser(writeClosers ...io.WriteCloser) io.WriteCloser
• func NewBufferedReader(reader io.Reader, bufSizeArgs ...int) *bufio.Reader
• func NewDailyWriteCloser(filePath string, options ...LumberJackOption) (io.WriteCloser, error)
• func NewLumberJackWriteCloser(filePath string, maxSize int64, options ...LumberJackOption) (*lumberjack.Roller, error)
• func NewReaderFromPath(path string) (*os.File, error)
• func NewRotatableWriteCloserWithSpec(filePath string, spec string, options ...LumberJackOption) (io.WriteCloser, error)
• func NopCloserToReadSeeker(readSeeker io.ReadSeeker) io.ReadSeekCloser
• func ReadAllToString(reader io.Reader) (string, error)
• func ReadAllWithBuffer(reader io.Reader, bufSizeArgs ...int) ([]byte, error)
• func SeekToStart(seeker io.Seeker) (int64, error)
• func TryToClose(objs ...any) error
• type DailyWriteCloser
  • func (dwc *DailyWriteCloser) Close() error
  • func (dwc *DailyWriteCloser) Write(p []byte) (int, error)
• type LumberJackOption
  • func WithCompress(compress bool) LumberJackOption
  • func WithLocalTime(localTime bool) LumberJackOption
  • func WithMaxAge(maxAge time.Duration) LumberJackOption
  • func WithMaxBackups(maxBackups int) LumberJackOption

Variables

var (
	MultiReader func(readers ...io.Reader) io.Reader = io.MultiReader

	MultiWriter func(writers ...io.Writer) io.Writer = io.MultiWriter
)

var (
	NewBuffer func(s []byte) *bytes.Buffer = bytes.NewBuffer

	NewBufferString func(str string) *bytes.Buffer = bytes.NewBufferString

	// NewReadWriter bytes.Buffer 结构体 实现了 io.ReadWriter 接口
	/*
		@param s 可以为nil
	*/
	NewReadWriter func(s []byte) *bytes.Buffer = bytes.NewBuffer

	// NewReadWriterFromString bytes.Buffer 结构体 实现了 io.ReadWriter 接口
	/*
		@param str 可以为""
	*/
	NewReadWriterFromString func(str string) *bytes.Buffer = bytes.NewBufferString
)

var (
	// NewReader
	/*
		PS: bytes.Reader 结构体实现了 io.Reader 接口.
	*/
	NewReader func(b []byte) *bytes.Reader = bytes.NewReader

	// NewReaderFromString
	/*
		PS: strings.Reader 结构体实现了 io.Reader 接口.
	*/
	NewReaderFromString func(s string) *strings.Reader = strings.NewReader
)

var Copy func(dst io.Writer, src io.Reader) (written int64, err error) = io.Copy

Copy 读取 io.Reader实例 的数据并写入 io.Writer实例.

复制会持续进行直到 src 没有更多的数据可读（即 src.Read() 返回 io.EOF 错误），或者发生错误.

PS: (1) 适用场景: 当不需要限制复制数据量时，直接使用 io.Copy 即可; (2) 会"读"reader.

@param dst (1) 实现了 io.Writer 接口的对象

(2) 一般是 *bytes.Buffer 类型

@param src 实现了 io.Reader 接口的对象，如文件、网络连接或字节缓冲 @return written 表示实际复制的数据量（以字节为单位） @return err 在复制过程中遇到的第一个非 EOF 错误

var CopyBuffer func(dst io.Writer, src io.Reader, buf []byte) (written int64, err error) = io.CopyBuffer

CopyBuffer 从 源src 向 目标dst 复制数据（带缓冲区）.

此函数与 Copy 功能相同，但是允许用户传递一个预分配的缓冲区 buf。这样，在复制数据的过程中，CopyBuffer 会使用提供的缓冲区暂存数据，避免每次系统调用时都需要临时分配新的缓冲区，从而提高了性能。对于那些不支持零拷贝或者其他优化机制的 Reader 或 Writer，手动提供缓冲区能够更有效地处理大量数据传输，尤其是当频繁进行小块数据传输时。

PS: (1) 适用场景: 对于性能敏感且可以预估缓冲区合理大小的情况，使用 io.CopyBuffer 可以减少内存分配带来的开销; (2) 会"读"reader.

@param buf 暂存数据的缓冲区

var CopyN func(dst io.Writer, src io.Reader, n int64) (written int64, err error) = io.CopyN

CopyN 从 源src 向 目标dst 复制数据（仅复制指定的字节数）.

此函数与 Copy 类似，但仅尝试复制指定数量 n 的字节。当复制了 n 字节后，或者源读取达到 EOF，或者发生错误时，复制停止。无论哪种情况，CopyN 都会返回已成功复制的字节数以及可能发生的任何错误。

PS: (1) 适用场景: 如果需要精确控制复制特定数量的数据，应选用 io.CopyN; (2) 会"读"reader.

@param n 要复制的字节数

var NopCloser func(reader io.Reader) io.ReadCloser = io.NopCloser

NopCloser

PS: 返回值调用Close()将什么都不会做，直接返回nil.

var (
	// Pipe
	/*
		pipe: 管道
		这个管道可以在不同的协程之间同步地进行数据传输，通常用于数据流的处理，例如在数据被处理（比如过滤、压缩等）的同时开始传输。

		(1) 数据同步：PipeReader 和 PipeWriter 是同步的，这意味着当 PipeWriter 写入数据时，PipeReader 可以立即读取到这些数据，反之亦然。这使得在不同的协程间可以同时进行读写操作而不会丢失数据。
		(2) 非阻塞操作：Pipe 提供了一种非阻塞的方式进行读写。如果写端关闭，读端会立即知道并能检测到这个状态；同样，如果读端关闭，写端在尝试写入时也会立即得到通知。
		(3) 数据流处理：io.Pipe 常用于构建数据处理管道，例如在数据被读取后经过一系列中间处理步骤，然后被写入到最终目的地，比如网络连接或文件。
	*/
	Pipe func() (*io.PipeReader, *io.PipeWriter) = io.Pipe
)

var ReadAll func(reader io.Reader) ([]byte, error) = io.ReadAll

ReadAll 读取 io.Reader实例 的内容（从 io.Reader实例 中读取所有可用的数据直到 EOF（文件结束符），并返回一个包含所有读取数据的字节切片）.

!!!: 由于 io.ReadAll 将整个文件内容加载到内存中，因此对于大文件或资源有限的情况，请谨慎使用，以免造成"内存溢出".在这种情况下，应考虑采用逐块读取数据的流式处理方式.

var ReadAtLeast func(reader io.Reader, buf []byte, min int) (n int, err error) = io.ReadAtLeast

ReadAtLeast 试图从 io.Reader 中读取至少指定数量的字节，如果实际读取的数量少于最小要求值，则返回错误.

PS: 不同于 ReadFull 要求读取确切长度的数据，ReadAtLeast 只保证最少读到多少字节，所以即使读取到了超过 min 字节的数据，也可能会立即返回.

var ReadFull func(reader io.Reader, buf []byte) (n int, err error) = io.ReadFull

ReadFull 尝试从 io.Reader 中读取指定长度的数据，并确保至少读取这么多数据，否则它会返回一个错误.

PS: 这个函数通常用于需要固定长度数据块的协议或格式中，例如在处理网络包或解码结构化的二进制数据时.

Functions

func Close

func Close(closers ...io.Closer) error

Close

PS: 就算循环过程中返回了非nil的error，也要继续向下循环（尽可能多地关闭）.

@param closers (1) 可以为nil（即不传参）；(2) 其中可以有nil @return 发生error的话，返回第一个

func CloseSingle

func CloseSingle(closer io.Closer) error

func CountLines

func CountLines(r io.Reader) (count int, err error)

CountLines 读取内容的行数

PS: (1) 如果最后一行只有'\n'，会被视作1行； (2) 不要重复调用，否则第二次开始行数将不准确.

func CountLines1

func CountLines1(r io.Reader) (int, error)

CountLines1 读取内容的行数

PS: (1) 如果最后一行只有'\n'，不会被视作1行； (2) 不要重复调用，否则第二次开始行数将不准确.

func MultiWriteCloser

func MultiWriteCloser(writeClosers ...io.WriteCloser) io.WriteCloser

MultiWriteCloser

PS: 参考了 io.MultiWriter().

func NewBufferedReader

func NewBufferedReader(reader io.Reader, bufSizeArgs ...int) *bufio.Reader

NewBufferedReader 带缓冲的Reader.

PS: bufio.Reader 结构体 实现了 io.Reader 接口.

func NewDailyWriteCloser

func NewDailyWriteCloser(filePath string, options ...LumberJackOption) (io.WriteCloser, error)

NewDailyWriteCloser 每天凌晨0点，执行Rotate().

@param options 可选配置，参考 NewLumberJackWriteCloser()

func NewLumberJackWriteCloser

func NewLumberJackWriteCloser(filePath string, maxSize int64, options ...LumberJackOption) (*lumberjack.Roller, error)

NewLumberJackWriteCloser 可rotate（依据传参maxSize）的io.WriteCloser.

PS: (1) 如果 当前目标文件 被人为删了，会丢失部分输出直至再次调用Rotate(). (2) 可以同时配置 MaxBackups 和 MaxAge.

@param maxSize unit: byte @param options 可选配置: WithCompress() [默认: 不压缩] 是否压缩被rotate的文件？ WithMaxBackups() [默认: 保留所有旧日志] 旧日志保存的最多数量 WithMaxAge() [默认: 保留所有旧日志] 旧日志保存的最长时间 WithLocalTime() [默认: true] true: 使用本地时间; false: 使用UTC时间

func NewReaderFromPath

func NewReaderFromPath(path string) (*os.File, error)

NewReaderFromPath

!!!: 要在外部手动调用 *os.File 的Close方法.

PS: os.File 结构体 实现了 io.Reader 接口.

@param path 文件（或目录）的路径

func NewRotatableWriteCloserWithSpec

func NewRotatableWriteCloserWithSpec(filePath string, spec string, options ...LumberJackOption) (io.WriteCloser, error)

NewRotatableWriteCloserWithSpec 满足条件（spec），执行Rotate().

PS: (1) 可能存在情况，Rotate()后，生成的旧日志文件大小为0B.

func NopCloserToReadSeeker

func NopCloserToReadSeeker(readSeeker io.ReadSeeker) io.ReadSeekCloser

NopCloserToReadSeeker 给 io.ReadSeeker 实例加上Close()（虽然这个Close()什么都不做）.

func ReadAllToString

func ReadAllToString(reader io.Reader) (string, error)

func ReadAllWithBuffer

func ReadAllWithBuffer(reader io.Reader, bufSizeArgs ...int) ([]byte, error)

ReadAllWithBuffer

@param bufSizeArgs 可以不传参（默认缓冲大小为4096）

func SeekToStart

func SeekToStart(seeker io.Seeker) (int64, error)

SeekToStart 回到最前面.

func TryToClose

func TryToClose(objs ...any) error

TryToClose 尝试关闭（如果实现了io.Closer接口的话）.

@param writers (1) 可以为nil（即不传参）

(2) 其中可以有nil

@return 发生error的话，返回第一个

Types

type DailyWriteCloser

type DailyWriteCloser struct {
	// contains filtered or unexported fields
}

func (*DailyWriteCloser) Close

func (dwc *DailyWriteCloser) Close() error

func (*DailyWriteCloser) Write

func (dwc *DailyWriteCloser) Write(p []byte) (int, error)

type LumberJackOption

type LumberJackOption func(opts *lumberjackOptions)

func WithCompress

func WithCompress(compress bool) LumberJackOption

func WithLocalTime

func WithLocalTime(localTime bool) LumberJackOption

func WithMaxAge

func WithMaxAge(maxAge time.Duration) LumberJackOption

func WithMaxBackups

func WithMaxBackups(maxBackups int) LumberJackOption