mirror of
https://github.com/wneessen/go-mail.git
synced 2024-11-14 09:52:54 +01:00
Winni Neessen
5d79ff69c3
Improved documentation for the Reader struct, its methods, and error handling. Added detailed explanations for `Read`, `Error`, `Reset`, and `empty` functions to better describe their parameters, return values, and behavior.
78 lines
2.6 KiB
Go
78 lines
2.6 KiB
Go
// SPDX-FileCopyrightText: 2022-2023 The go-mail Authors
|
|
//
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package mail
|
|
|
|
import (
|
|
"io"
|
|
)
|
|
|
|
// Reader is a type that implements the io.Reader interface for a Msg.
|
|
//
|
|
// This struct represents a reader that reads from a byte slice buffer. It keeps track of the
|
|
// current read position (offset) and any initialization error. The buffer holds the data to be
|
|
// read from the message.
|
|
type Reader struct {
|
|
buffer []byte // contents are the bytes buffer[offset : len(buffer)]
|
|
offset int // read at &buffer[offset], write at &buffer[len(buffer)]
|
|
err error // initialization error
|
|
}
|
|
|
|
// Error returns an error if the Reader err field is not nil.
|
|
//
|
|
// This function checks the Reader's err field and returns it if it is not nil. If no error
|
|
// occurred during initialization, it returns nil.
|
|
//
|
|
// Returns:
|
|
// - The error stored in the err field, or nil if no error is present.
|
|
func (r *Reader) Error() error {
|
|
return r.err
|
|
}
|
|
|
|
// Read reads the content of the Msg buffer into the provided payload to satisfy the io.Reader interface.
|
|
//
|
|
// This function reads data from the Reader's buffer into the provided byte slice (payload).
|
|
// It checks for errors or an empty buffer and resets the Reader if necessary. If no data is available,
|
|
// it returns io.EOF. Otherwise, it copies the content from the buffer into the payload and updates
|
|
// the read offset.
|
|
//
|
|
// Parameters:
|
|
// - payload: A byte slice where the data will be copied.
|
|
//
|
|
// Returns:
|
|
// - n: The number of bytes copied into the payload.
|
|
// - err: An error if any issues occurred during the read operation or io.EOF if the buffer is empty.
|
|
func (r *Reader) Read(payload []byte) (n int, err error) {
|
|
if r.err != nil {
|
|
return 0, r.err
|
|
}
|
|
if r.empty() || r.buffer == nil {
|
|
r.Reset()
|
|
if len(payload) == 0 {
|
|
return 0, nil
|
|
}
|
|
return 0, io.EOF
|
|
}
|
|
n = copy(payload, r.buffer[r.offset:])
|
|
r.offset += n
|
|
return n, err
|
|
}
|
|
|
|
// Reset resets the Reader buffer to be empty, but it retains the underlying storage for future use.
|
|
//
|
|
// This function clears the Reader's buffer by setting its length to 0 and resets the read offset
|
|
// to the beginning. The underlying storage is retained, allowing future writes to reuse the buffer.
|
|
func (r *Reader) Reset() {
|
|
r.buffer = r.buffer[:0]
|
|
r.offset = 0
|
|
}
|
|
|
|
// empty reports whether the unread portion of the Reader buffer is empty.
|
|
//
|
|
// This function checks if the unread portion of the Reader's buffer is empty by comparing
|
|
// the length of the buffer to the current read offset.
|
|
//
|
|
// Returns:
|
|
// - true if the unread portion is empty, false otherwise.
|
|
func (r *Reader) empty() bool { return len(r.buffer) <= r.offset }
|