stl

type Bytes struct {
	Data   []byte
	Offset []uint32
	Length []uint32
}

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

type MemAllocator interface {
	Alloc(size int) MemNode
	Free(n MemNode)
	Usage() int
	String() string
}

type MemNode interface {
	GetBuf() []byte
	Size() int
}

type Vector[T any] interface {
	// Close free the vector allocated memory
	// Caller must call Close() or a memory leak will occur
	Close()

	// Clone deep copy data from offset to offset+length and create a new vector
	Clone(offset, length int, allocator ...MemAllocator) Vector[T]

	// If share is true, vector release allocated memory and use the buf and its data storage
	// If share is false, vector will copy the data from buf to its own data storage
	ReadBytes(buf *Bytes, share bool)

	// Reset resets the buffer to be empty
	// but it retains the underlying storage for use by future writes
	Reset()

	// IsView returns true if the vector shares the data storage with external buffer
	IsView() bool
	// Bytes returns the underlying data storage buffer
	Bytes() *Bytes
	// Data returns the underlying data storage buffer
	// For Vector[[]byte], it only returns the data buffer
	Data() []byte
	// DataWindow returns a data window [offset, offset+length)
	DataWindow(offset, length int) []byte
	// Slice returns the underlying data storage of type T
	Slice() []T
	SliceWindow(offset, length int) []T

	// Get returns the specified element at i
	// Note: If T is []byte, make sure not to use v after the vector is closed
	Get(i int) (v T)
	// GetCopy returns the copy of the specified element at i
	GetCopy(i int) (v T)
	// Append appends a element into the vector
	// If the prediction length is large than Capacity, it will cause the underlying memory reallocation.
	// Reallocation:
	// 1. Apply a new memory node from allocator
	// 2. Copy existing data into new buffer
	// 3. Swap owned memory node
	// 4. Free old memory node
	Append(v T)
	// Append appends many elements into the vector
	AppendMany(vals ...T)
	// Append updates a element at i to a new value
	// For T=[]byte, Update may introduce a underlying memory reallocation
	Update(i int, v T)
	// Delete deletes a element at i
	Delete(i int) (deleted T)
	// Delete deletes elements in [offset, offset+length)
	RangeDelete(offset, length int)

	// Returns the underlying memory allocator
	GetAllocator() MemAllocator
	// Returns the capacity, which is always >= Length().
	// It is related to the number of elements. Same as C++ std::vector::capacity
	Capacity() int
	// Returns the number of elements in the vertor
	Length() int
	// Return the space allocted
	Allocated() int

	String() string
	Desc() string

	// WriteTo writes data to w until the buffer is drained or an error occurs
	WriteTo(io.Writer) (int64, error)
	// ReadFrom reads data from r until EOF and appends it to the buffer, growing
	// the buffer as needed.
	ReadFrom(io.Reader) (int64, error)
	InitFromSharedBuf(buf []byte) (int64, error)
}