byteutils

README

byteutils

Utilities for managing bytes, such as indexing into a byte to get an individual bit and converting types like uint to and from []byte.

Example

fmt.Println(byteutils.ToUint16([]byte{0x01, 0x00}, byteutils.LittleEndian)) // 256

b := 0b0001_0000
fmt.Println(byteutils.GetL(b, 3)) // 1 (index from left)
byteutils.SetL(&b, 4) // set index 4 from left to 1
fmt.Println(byteutils.GetR(b, 3)) // 1 (index from right)

fmt.Printf("%b\n", byteutils.SliceL(0b00110000, 2, 4)) // 11

Documentation

Overview

Package byteutils contains utilities for managing bytes.

Note that a byte's indices are [0, 8), and using an index beyond this range may cause a panic or undefined behavior.

Example

Bitwise methods to manage bytes and their bits are abstracted with this library.

Functions are provided to "index" into a byte from the left and from the right.

var b byte = 0b0000_0000
byteutils.SetL(&b, 1)
fmt.Printf("%08b\n", b)
byteutils.ChangeR(&b, 0, byteutils.One)
fmt.Printf("%08b\n", b)
byteutils.ToggleL(&b, 7)
fmt.Printf("%08b\n", b)
fmt.Println(byteutils.GetR(b, 6))

Output:

01000000
01000001
01000000
1

Example (Endianness)

Endianness determines the least and most significant bytes.

Little endian means that the last byte is the smallest. Big endian means that the last byte is the largest.

bytes := []byte{0x00, 0x01}

littleEndianConversion := byteutils.ToUint16(bytes, byteutils.LittleEndian)
bigEndianConversion := byteutils.ToUint16(bytes, byteutils.BigEndian)

fmt.Printf("%d (0x%04X)\n", littleEndianConversion, littleEndianConversion)
fmt.Printf("%d (0x%04X)\n", bigEndianConversion, bigEndianConversion)

Output:

1 (0x0001)
256 (0x0100)

Index

• func BitAsBool(b Bit) bool
• func ChangeL(b *byte, index byte, bit Bit)
• func ChangeR(b *byte, index byte, bit Bit)
• func ClearL(b *byte, index byte)
• func ClearR(b *byte, index byte)
• func SetL(b *byte, index byte)
• func SetR(b *byte, index byte)
• func SliceL(b byte, i, end byte) byte
• func SliceR(b byte, i, end byte) byte
• func ToUint16(bytes Bytes, e Endian) uint16
• func ToUint32(bytes Bytes, e Endian) uint32
• func ToggleL(b *byte, index byte)
• func ToggleR(b *byte, index byte)
• type Bit
  • func GetL(b byte, index byte) Bit
  • func GetR(b byte, index byte) Bit
  • func NewBit(bit interface{}) Bit
• type ByteIteratorFunc
• type Bytes
  • func BytesFromUint16(n uint16, e Endian) Bytes
  • func BytesFromUint32(n uint32, e Endian) Bytes
• type Endian
  • func (e Endian) IterateSmallestToLargest(b Bytes, f ByteIteratorFunc)
  • func (e Endian) IterateUint16(n uint16, f ByteIteratorFunc)
  • func (e Endian) IterateUint32(n uint32, f ByteIteratorFunc)

Examples

• Package
• Package (Endianness)

Functions

func BitAsBool

func BitAsBool(b Bit) bool

BitAsBool converts a bit into a bool.

func ChangeL

func ChangeL(b *byte, index byte, bit Bit)

ChangeL changes the nth bit from the right to the bit provided.

func ChangeR

func ChangeR(b *byte, index byte, bit Bit)

ChangeR changes the nth bit from the left to the bit provided.

func ClearL

func ClearL(b *byte, index byte)

ClearL clears the nth bit from the left.

func ClearR

func ClearR(b *byte, index byte)

ClearR clears the nth bit from the right.

func SetL

func SetL(b *byte, index byte)

SetL sets the nth bit from the left.

func SetR

func SetR(b *byte, index byte)

SetR sets the nth bit from the right.

func SliceL

func SliceL(b byte, i, end byte) byte

SliceL gets the [i, end) bits from the left.

func SliceR

func SliceR(b byte, i, end byte) byte

SliceR gets the [i, end) bits from the right.

i will be the "index" of the bit farthest to the right, and end is the index of the bit further left from the right.

func ToUint16

func ToUint16(bytes Bytes, e Endian) uint16

ToUint16 converts Bytes to uint16

func ToUint32

func ToUint32(bytes Bytes, e Endian) uint32

ToUint32 converts Bytes to uint16

func ToggleL

func ToggleL(b *byte, index byte)

ToggleL flips the nth bit from the left.

func ToggleR

func ToggleR(b *byte, index byte)

ToggleR flips the nth bit from the right.

Types

type Bit

type Bit = byte

Bit abstracts a single bit. The underlying type is byte instead of bool to make conversion usage with bytes simpler.

const (
	// Zero represents a 0 bit
	Zero Bit = 0
	// One represents a 1 bit
	One Bit = 1
)

func GetL

func GetL(b byte, index byte) Bit

GetL gets the nth bit from the left.

func GetR

func GetR(b byte, index byte) Bit

GetR gets the nth bit from the right.

func NewBit

func NewBit(bit interface{}) Bit

NewBit creates a bit. This is to simplify enforcing that a bit is either Zero or One. Boolean type and most numerical types can be used as the bit. Floats, complex types, etc. are undefined behavior.

type ByteIteratorFunc

type ByteIteratorFunc = func(b *byte, enumeration int)

ByteIteratorFunc takes a byte and the enumeration (count of calls to function). A pointer is passed so that the byte can be potentially modified.

type Bytes

type Bytes = []byte

Bytes can be converted to and from other built-in types.

func BytesFromUint16

func BytesFromUint16(n uint16, e Endian) Bytes

BytesFromUint16 creates bytes from a uint16.

func BytesFromUint32

func BytesFromUint32(n uint32, e Endian) Bytes

BytesFromUint32 creates bytes from a uint32.

type Endian

type Endian bool

Endian represents the endianness for conversion.

const (
	// LittleEndian places the least significant byte at the end (right side) of
	// a byte sequence.
	LittleEndian Endian = false
	// BigEndian places the most significant byte at the end (right side) of a
	// byte sequence
	BigEndian Endian = true
)

func (Endian) IterateSmallestToLargest

func (e Endian) IterateSmallestToLargest(b Bytes, f ByteIteratorFunc)

IterateSmallestToLargest iterates from the smallest byte to the largest byte given the endianness. It will call the provided function on each byte.

func (Endian) IterateUint16

func (e Endian) IterateUint16(n uint16, f ByteIteratorFunc)

IterateUint16 iterates over a uint16 as bytes, from smallest to largest. Endianness determines if iteration goes from the left-most byte to the right-most (big endian), or the right-most byte to the left-most (little endian).

func (Endian) IterateUint32

func (e Endian) IterateUint32(n uint32, f ByteIteratorFunc)

IterateUint32 iterates over a uint32 as bytes, from smallest to largest. Endianness determines if iteration goes from the left-most byte to the right-most (big endian), or the right-most byte to the left-most (little endian).