Documentation
¶
Overview ¶
Package bits provides a 2D bit matrix. Logically it is similar to a 2-dimensional array of booleans, but has some significant differences:
- It is optimised for operating on blocks of data in the matrix, including: a. Batch copies from one matrix to another b. Batch bitwise operations (And, Not, Or, Xor)
- It provides some simple structures to facilitate reading along columns and rows.
- Unlike a [][]bool, A bits.Matrix cannot represent a jagged array.
Index ¶
- Variables
- func Copy(source *Matrix, sourceRow, sourceCol int, dest *Matrix, ...) (int, int)
- func Write(writer io.Writer, matrix *Matrix) error
- type BitMatrixReader
- type BitMatrixReaderWriter
- type BitMatrixWriter
- type Cursor
- func (c *Cursor) Position() (row, col int)
- func (c *Cursor) ReadDown() (bit, ok bool)
- func (c *Cursor) ReadDownByte() (b byte, bits int)
- func (c *Cursor) ReadLeft() (bit, ok bool)
- func (c *Cursor) ReadLeftByte() (b byte, bits int)
- func (c *Cursor) ReadRight() (bit, ok bool)
- func (c *Cursor) ReadRightByte() (b byte, bits int)
- func (c *Cursor) ReadUp() (bit, ok bool)
- func (c *Cursor) ReadUpByte() (b byte, bits int)
- type HumanReadable
- type Matrix
- func (m *Matrix) And(other *Matrix)
- func (m *Matrix) Clear()
- func (m *Matrix) Clone() *Matrix
- func (m *Matrix) Encode() []uint32
- func (m *Matrix) Equals(other *Matrix) bool
- func (m *Matrix) Get(row, col int) bool
- func (m *Matrix) Not()
- func (m *Matrix) Or(other *Matrix)
- func (m *Matrix) Put(row, col int, value bool)
- func (m *Matrix) Reset(row, col int)
- func (m *Matrix) Set(row, col int)
- func (m *Matrix) Size() (height, width int)
- func (m *Matrix) String() string
- func (m *Matrix) Xor(other *Matrix)
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidMatrixFormat = errors.New("invalid serialisation format for bits.Matrix")
Functions ¶
func Copy ¶
func Copy(source *Matrix, sourceRow, sourceCol int, dest *Matrix, destRow, destCol, height, width int) (int, int)
Copy copies a sub-range of bits from one matrix to another. All the bits in the range are overwritten in the destination matrix.
Copies from source matrix, at origin (sourceRow, sourceCol) to the dest matrix ar (destRow, destCol). Copy will panic if either the source origin or the destination origin are out of bounds. Copies a rectangle up to the size given by height and width. If the maximum-sized rectangle exceeds the bonds of either the source or destination matrix, it is trimmed. Returns the actual height and width of the rectangle copied as a result.
Copying is a read-only operation with respect to the source matrix, with the usual implications for concurrency.
Types ¶
type BitMatrixReader ¶ added in v1.2.0
type BitMatrixReaderWriter ¶ added in v1.2.0
type BitMatrixReaderWriter interface {
BitMatrixReader
BitMatrixWriter
}
func DefaultReaderWriter ¶ added in v1.2.0
func DefaultReaderWriter() BitMatrixReaderWriter
type BitMatrixWriter ¶ added in v1.2.0
type Cursor ¶
type Cursor struct {
// contains filtered or unexported fields
}
A Cursor allows a BitMatrix to be traversed by reading across, or up and down the matrix.
The type provides a mechanism to traverse a bit matrix that is optimised for reading contiguous bits, as compared to repeatedly using Get() in a loop.
When reading from left to right, or downwards, the read is sequenced as follows: sample current bit then advance cursor position. When reading from right to left, or upwards, the read is sequenced as follows: advance cursor position then sample bit at new position. The different sequencing allows the expected behaviour that reading left then right repeatedly keeps returning the same bit.
func NewCursor ¶
NewCursor returns a new instance of a Cursor.
Receives the matrix to address as an argument, as well as the starting location. For rightward or downward reads, the initial cursor position should be on the first bit to be read. For leftward or upward reads, the initial cursor position should be one before the bit to be read (to its right or beneath it). Because of this, positioning the cursor at row = height, or at col = width is permitted.
func (*Cursor) ReadDown ¶
ReadDown samples the bit at the current position and then positions the cursor one bit further down. if ok is returned as false, the cursor cannot move further down, it's already past the bottom row.
func (*Cursor) ReadDownByte ¶
ReadDownByte constructs a byte from 8 consecutive reads downward. Returns the resulting byte and the number of bits successfully read before reading past the height of the matrix. The last bit read is always in the least significant position, regardless of the number of bits returned.
func (*Cursor) ReadLeft ¶
ReadLeft positions the cursor one bit to the left and returns the value at the new position. if ok is returned as false, the cursor cannot move further left, it's already on column zero.
func (*Cursor) ReadLeftByte ¶
ReadLeftByte constructs a byte from 8 consecutive reads leftward. Because of the leftward direction, bits in the result are sequenced in the reverse order of the natural order in the matrix. That is to say that the most significant bit of the returned byte is read from the rightmost position read by the cursor. Returns the resulting byte and the number of bits successfully read before reading past column zero. The last bit read is always in the least significant position, regardless of the number of bits returned.
func (*Cursor) ReadRight ¶
ReadRight samples the bit at the current position and then positions the cursor one bit to the right. if ok is returned as false, the cursor cannot move further right, it's already past the rightmost column.
func (*Cursor) ReadRightByte ¶
ReadRightByte constructs a byte from 8 consecutive reads rightward. Returns the resulting byte and the number of bits successfully read before reading past the width of the matrix. The last bit read is always in the least significant position, regardless of the number of bits returned.
func (*Cursor) ReadUp ¶
ReadUp positions the cursor one bit further up and returns the value at the new position. if ok is returned as false, the cursor cannot move further up, it's already on row zero.
func (*Cursor) ReadUpByte ¶
ReadUpByte constructs a byte from 8 consecutive reads upward. Returns the resulting byte and the number of bits successfully read before reading past row zero. The last bit read is always in the least significant position, regardless of the number of bits returned.
type HumanReadable ¶ added in v1.2.0
type HumanReadable struct {
TrueRune rune
FalseRune rune
NewRowRune rune
Terminator rune
Padding int
}
type Matrix ¶
type Matrix struct {
// contains filtered or unexported fields
}
A Matrix is a two-dimensional array of bits with fixed height and width.
Matrix is not thread-safe. Read-only operations such as Get and Clone may safely be called concurrently. Write operations such as Set and Clear should not be called concurrently with each other, or with read operations.
func Decode ¶
Decode creates a new Matrix from an array of UInt32.
Provided as a complement to the Encode method, builds a Matrix from the state encoded by that method.
func FromBools ¶ added in v1.2.0
FromBools builds a new Matrix from a slice of bool slices. Input must not be jagged, or the function will panic.
func (*Matrix) And ¶
And performs a bitwise and operation. The result of the operation is applied to this matrix.
func (*Matrix) Clear ¶
func (m *Matrix) Clear()
Clear resets all the bits in the matrix back to zero.
func (*Matrix) Encode ¶
Encode returns the complete state of the matrix as an array of UInt32.
Provided as a means to serialise a matrix for persistance or transport.
func (*Matrix) Equals ¶ added in v1.2.0
Equals performs a bitwise comparison of two matrices. The result is true if the two matriices are equivalent, or false otherwise.
func (*Matrix) Get ¶
Get returns the state of a specific bit in the Matrix. Arguments specify the coordinates of the bit. Get will panic if the arguments are out of bounds.
func (*Matrix) Not ¶
func (m *Matrix) Not()
Not performs a bitwise complement operation. The result of the operation is applied to this matrix.
func (*Matrix) Or ¶
Or performs a bitwise or operation. The result of the operation is applied to this matrix.
func (*Matrix) Put ¶
Put allocates state to a specific bit in the Matrix. Arguments specify the coordinates of the bit and the required state. Put will panic if the arguments are out of bounds.
func (*Matrix) Reset ¶
Reset allocates a value of false to a specific bit in the Matrix. Arguments specify the coordinates of the bit. Reset will panic if the arguments are out of bounds.
func (*Matrix) Set ¶
Set allocates a value of true to a specific bit in the Matrix. Arguments specify the coordinates of the bit. Set will panic if the arguments are out of bounds.
Source Files