pbits

package module
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 26, 2025 License: MIT Imports: 0 Imported by: 0

README

pbits is designed for bit masking and data packing in Go, enabling efficient memory management and storage of numbers in a specified number of bits. It can be used for:

  • Memory Optimization: By using defined masks (e.g., Mask5, Mask10), you can limit the range of numbers you want to store, saving memory. For example, Mask10 allows storing numbers from 0 to 1023 using only 10 bits, instead of the standard 64 bits.

  • Packing Data in a Specific Number of Bits: The Pack and Unpack functions enable storing and retrieving data using defined masks. This is useful when you want to store multiple values in a single 64-bit word, occupying exactly the space needed.

  • Manipulating and Storing Large Bitwise Data: The package enables storing numerical values in a compact form, useful when serializing data for disk storage, especially when maximizing space efficiency is essential.

  • Low-level Applications: It is ideal for systems handling large datasets, network operations, binary protocols, or hardware-level tasks where bitwise efficiency is critical.

This package can be applied in systems requiring optimal storage or transmission of large numbers of values, such as databases, index files, or data transmission systems where data is sent in binary form.

pbits was created to make bit manipulation more transparent and to simplify error detection in the code. By providing a structured set of masks and utility functions, it helps developers work with bits more intuitively and reduces the chances of mistakes in bit-level operations, enhancing code readability and maintainability.

Example

Suppose we have two numbers:

  • a = 1939, which we want to store using 11 bits (i.e., using Mask11).

  • b = 512, which we want to store using 10 bits (i.e., using Mask10).

  • Using Pack and Unpack functions, we can store these numbers in a single 64-bit integer and retrieve them.

package main

import (
    "fmt"
    "github.com/malumar/pbits"
)

func main() {
    // Define the numbers to pack
    a := uint64(1939) // Number to pack with Mask11
    b := uint64(512)  // Number to pack with Mask10

    // Step 1: Pack the numbers into a single variable (bigendian format)
    packed := pbits.Pack(a, pbits.NoMask, pbits.Mask11) | 
		pbits.Pack(b, pbits.Mask11, pbits.Mask10)
    fmt.Printf("Packed value: %d\n", packed)

    // Step 2: Unpack the numbers
    unpackedA := pbits.Unpack(packed, pbits.NoMask, pbits.Mask11)
    unpackedB := pbits.Unpack(packed, pbits.Mask11, pbits.Mask10)
    
    fmt.Printf("Unpacked values: a = %d, b = %d\n", unpackedA, unpackedB)
}

More examples You find in pbits_test.go

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Pack 

func Pack[T uint | uint8 | uint16 | uint32 | uint64](value T, prevMask Mask, mask Mask) T

Pack @value of max value defined by @mask if it is first value in packed integer @prevMask should be equal NoMask

func Unpack 

func Unpack[T uint | uint8 | uint16 | uint32 | uint64](value T, prevMask Mask, mask Mask) T

Unpack uint from @value, which max value is defined by @mask if it is first unpacking value @prevMask should be equal NoMask

func Value 

func Value(m Mask) uint64

Types

type Mask 

type Mask uint

Mask defines the maximum number that can be stored in bit packing, This is quite problematic, so it is better to use constant arrays e.g. to encode the number 1939 using the smallest possible number of bits in a 64-bit number you need to use this: x := 1939 << 53 & Mask11.MaxValue() so encoding 1939 requires Mask11 because it stores numbers from 0-2047 the value 53 is taken from this, that we want to put the result in a 64-bit number, i.e. 64bits-Mask11 gives us that we start saving the first bit from position no. 53 In the BigEndian format and so the last bits are the first ones, so we should write the sorting value, i.e. e.g. timstamp from the 64th bit down, because after writing to disk they will be the first 

const (
	// NoMask max value: 0, bitsCount: 0, memory use: 0 byte(s) size: 0
	NoMask Mask = iota

	// Mask1 max value: 1, bitsCount: 1, memory use: 1 byte(s) size: 8
	Mask1

	// Mask2 max value: 3, bitsCount: 2, memory use: 1 byte(s) size: 8
	Mask2

	// Mask3 max value: 7, bitsCount: 3, memory use: 1 byte(s) size: 8
	Mask3

	// Mask4 max value: 15, bitsCount: 4, memory use: 1 byte(s) size: 8
	Mask4

	// Mask5 max value: 31, bitsCount: 5, memory use: 1 byte(s) size: 8
	Mask5

	// Mask6 max value: 63, bitsCount: 6, memory use: 1 byte(s) size: 8
	Mask6

	// Mask7 max value: 127, bitsCount: 7, memory use: 1 byte(s) size: 8
	Mask7

	// Mask8 max value: 255, bitsCount: 8, memory use: 1 byte(s) size: 8
	Mask8

	// Mask9 max value: 511, bitsCount: 9, memory use: 2 byte(s) size: 16
	Mask9

	// Mask10 max value: 1023, bitsCount: 10, memory use: 2 byte(s) size: 16
	Mask10

	// Mask11 max value: 2047, bitsCount: 11, memory use: 2 byte(s) size: 16
	Mask11

	// Mask12 max value: 4095, bitsCount: 12, memory use: 2 byte(s) size: 16
	Mask12

	// Mask13 max value: 8191, bitsCount: 13, memory use: 2 byte(s) size: 16
	Mask13

	// Mask14 max value: 16383, bitsCount: 14, memory use: 2 byte(s) size: 16
	Mask14

	// Mask15 max value: 32767, bitsCount: 15, memory use: 2 byte(s) size: 16
	Mask15

	// Mask16 max value: 65535, bitsCount: 16, memory use: 2 byte(s) size: 16
	Mask16

	// Mask17 max value: 131071, bitsCount: 17, memory use: 3 byte(s) size: 32
	Mask17

	// Mask18 max value: 262143, bitsCount: 18, memory use: 3 byte(s) size: 32
	Mask18

	// Mask19 max value: 524287, bitsCount: 19, memory use: 3 byte(s) size: 32
	Mask19

	// Mask20 max value: 1048575, bitsCount: 20, memory use: 3 byte(s) size: 32
	Mask20

	// Mask21 max value: 2097151, bitsCount: 21, memory use: 3 byte(s) size: 32
	Mask21

	// Mask22 max value: 4194303, bitsCount: 22, memory use: 3 byte(s) size: 32
	Mask22

	// Mask23 max value: 8388607, bitsCount: 23, memory use: 3 byte(s) size: 32
	Mask23

	// Mask24 max value: 16777215, bitsCount: 24, memory use: 3 byte(s) size: 32
	Mask24

	// Mask25 max value: 33554431, bitsCount: 25, memory use: 4 byte(s) size: 32
	Mask25

	// Mask26 max value: 67108863, bitsCount: 26, memory use: 4 byte(s) size: 32
	Mask26

	// Mask27 max value: 134217727, bitsCount: 27, memory use: 4 byte(s) size: 32
	Mask27

	// Mask28 max value: 268435455, bitsCount: 28, memory use: 4 byte(s) size: 32
	Mask28

	// Mask29 max value: 536870911, bitsCount: 29, memory use: 4 byte(s) size: 32
	Mask29

	// Mask30 max value: 1073741823, bitsCount: 30, memory use: 4 byte(s) size: 32
	Mask30

	// Mask31 max value: 2147483647, bitsCount: 31, memory use: 4 byte(s) size: 32
	Mask31

	// Mask32 max value: 4294967295, bitsCount: 32, memory use: 4 byte(s) size: 32
	Mask32

	// Mask33 max value: 8589934591, bitsCount: 33, memory use: 5 byte(s) size: 64
	Mask33

	// Mask34 max value: 17179869183, bitsCount: 34, memory use: 5 byte(s) size: 64
	Mask34

	// Mask35 max value: 34359738367, bitsCount: 35, memory use: 5 byte(s) size: 64
	Mask35

	// Mask36 max value: 68719476735, bitsCount: 36, memory use: 5 byte(s) size: 64
	Mask36

	// Mask37 max value: 137438953471, bitsCount: 37, memory use: 5 byte(s) size: 64
	Mask37

	// Mask38 max value: 274877906943, bitsCount: 38, memory use: 5 byte(s) size: 64
	Mask38

	// Mask39 max value: 549755813887, bitsCount: 39, memory use: 5 byte(s) size: 64
	Mask39

	// Mask40 max value: 1099511627775, bitsCount: 40, memory use: 5 byte(s) size: 64
	Mask40

	// Mask41 max value: 2199023255551, bitsCount: 41, memory use: 6 byte(s) size: 64
	Mask41

	// Mask42 max value: 4398046511103, bitsCount: 42, memory use: 6 byte(s) size: 64
	Mask42

	// Mask43 max value: 8796093022207, bitsCount: 43, memory use: 6 byte(s) size: 64
	Mask43

	// Mask44 max value: 17592186044415, bitsCount: 44, memory use: 6 byte(s) size: 64
	Mask44

	// Mask45 max value: 35184372088831, bitsCount: 45, memory use: 6 byte(s) size: 64
	Mask45

	// Mask46 max value: 70368744177663, bitsCount: 46, memory use: 6 byte(s) size: 64
	Mask46

	// Mask47 max value: 140737488355327, bitsCount: 47, memory use: 6 byte(s) size: 64
	Mask47

	// Mask48 max value: 281474976710655, bitsCount: 48, memory use: 6 byte(s) size: 64
	Mask48

	// Mask49 max value: 562949953421311, bitsCount: 49, memory use: 7 byte(s) size: 64
	Mask49

	// Mask50 max value: 1125899906842623, bitsCount: 50, memory use: 7 byte(s) size: 64
	Mask50

	// Mask51 max value: 2251799813685247, bitsCount: 51, memory use: 7 byte(s) size: 64
	Mask51

	// Mask52 max value: 4503599627370495, bitsCount: 52, memory use: 7 byte(s) size: 64
	Mask52

	// Mask53 max value: 9007199254740991, bitsCount: 53, memory use: 7 byte(s) size: 64
	Mask53

	// Mask54 max value: 18014398509481983, bitsCount: 54, memory use: 7 byte(s) size: 64
	Mask54

	// Mask55 max value: 36028797018963967, bitsCount: 55, memory use: 7 byte(s) size: 64
	Mask55

	// Mask56 max value: 72057594037927935, bitsCount: 56, memory use: 8 byte(s) size: 64
	Mask56

	// Mask57 max value: 144115188075855871, bitsCount: 57, memory use: 8 byte(s) size: 64
	Mask57

	// Mask58 max value: 288230376151711743, bitsCount: 58, memory use: 8 byte(s) size: 64
	Mask58

	// Mask59 max value: 576460752303423487, bitsCount: 59, memory use: 8 byte(s) size: 64
	Mask59

	// Mask60 max value: 1152921504606846975, bitsCount: 60, memory use: 8 byte(s) size: 64
	Mask60

	// Mask61 max value: 2305843009213693951, bitsCount: 61, memory use: 8 byte(s) size: 64
	Mask61

	// Mask62 max value: 4611686018427387903, bitsCount: 62, memory use: 8 byte(s) size: 64
	Mask62

	// Mask63 max value: 9223372036854775807, bitsCount: 63, memory use: 8 byte(s) size: 64
	Mask63

	// Mask64 max value: 18446744073709551615, bitsCount: 64, memory use: 8 byte(s) size: 64
	Mask64
)

func (Mask) BitsCount 

func (self Mask) BitsCount() int

BitsCount how many bitsCount you need sto store value BitsCount is equal to Mask value

func (Mask) BytesCount 

func (self Mask) BytesCount() int

BytesCount how many bytes you need to store value in memory/disk

func (Mask) MaxValue 

func (self Mask) MaxValue() uint64

MaxValue max value that can be stored in this mask

func (Mask) Protect 

func (self Mask) Protect(val uint64) uint64

Protect guarantees to return a number in the mask range if the higher supply returns zero

func (Mask) Size 

func (self Mask) Size() int

Size int size type (0, 32 lub 64)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.