matrix

type Constructor[T any] func() Interface[T]

type ErrDimension struct {
	Requested, Actual int // 1, 2, 3 or 4.
}

type ErrIndexOutOfRange struct {
	Index [4]int // x, y, w, z index attempted to access
	Range [4]int // width, height, depth, extent of each dimension
}

type ErrOffDiagonal struct {
	Index          [4]int // x, y, w, z index attempted to access
	Width          int
	Dimensionality int
}

type Interface[T any] interface {
	// Resize1D (and variants) updates a matrix, if necessary, so that it has
	// at least capacity for the given number of elements, and has the
	// appropriate dimensionality. It may return a new matrix, but reuses
	// underlying memory from the existing matrix where possible. All values
	// are cleared.
	Resize1D(index int)
	Resize2D(width, height int)
	Resize3D(width, height, depth int)
	Resize4D(width, height, depth, extent int)
	ResizeN(lengths ...int)

	// Width and Height and Depth, and Extent return the number of elements
	// in the x, y, z and w dimensions respectively.
	Width() int
	Height() int
	Depth() int
	Extent() int

	// Dimensions2D and Dimensions3D, and Dimensions4D return the number of
	// elements in the (x, y), (x, y, z), and (x, y, z, w) dimensions,
	// respectively.
	Dimensions2D() (width, height int)
	Dimensions3D() (width, height, depth int)
	Dimensions4D() (width, height, depth, extent int)

	// DimensionN returns the number of elements in the nth dimension.
	DimensionN(n int) int

	// Dimensionality returns the number of dimensions. For example, returns 1,
	// 2, 3 or 4 if the matrix is 1D, 2D, 3D or 4D, respectively.
	Dimensionality() int

	// Get1D (and variants) return the value at the given coordinate. This
	// will panic if out of bounds.
	Get1D(x int) T
	Get2D(x, y int) T
	Get3D(x, y, z int) T
	Get4D(x, y, z, w int) T

	// GetN returns the value at the given offsets with arbitrary dimension.
	// Must contain an offset for each dimension.
	GetN(offsets ...int) T

	// Set1D (and variants) writes a value at the given coordinate. This will
	// panic if out of bounds.
	Set1D(value T, x int)
	Set2D(value T, x, y int)
	Set3D(value T, x, y, z int)
	Set4D(value T, x, y, z, w int)

	// SetN writes a value at the given coordinate at the given offsets with
	// arbitrary dimension. Must contain one offset for each dimension.
	SetN(value T, offset ...int)

	// Clear sets all elements to zero.
	Clear()

	// Capacity returns the total number of elements in the matrix (across all
	// dimensions).
	Capacity() int
}