bits

package standard library
go1.27.0 Latest Latest
Warning

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

 Go to latest Published: Aug 19, 2026 License: BSD-3-Clause Imports: 1 Imported by: 53,829

Documentation

Overview

Package bits implements bit counting and manipulation functions for the predeclared unsigned integer types.

Functions in this package may be implemented directly by the compiler, for better performance. For those functions the code in this package will not be used. Which functions are implemented by the compiler depends on the architecture and the Go release.

Index

Examples

Constants

View Source 
const UintSize = uintSize

UintSize is the size of a uint in bits.

Variables

This section is empty.

Functions

func Add added in go1.12 

func Add(x, y, carry uint) (sum, carryOut uint)

Add returns the sum with carry of x, y and carry: sum = x + y + carry. The carry input must be 0 or 1; otherwise the behavior is undefined. The carryOut output is guaranteed to be 0 or 1.

This function's execution time does not depend on the inputs.

func Add32 added in go1.12 

func Add32(x, y, carry uint32) (sum, carryOut uint32)

Add32 returns the sum with carry of x, y and carry: sum = x + y + carry. The carry input must be 0 or 1; otherwise the behavior is undefined. The carryOut output is guaranteed to be 0 or 1.

This function's execution time does not depend on the inputs.

Example 
package main

import (
	"fmt"
	"math/bits"
)

func main() {
	// First number is 33<<32 + 12
	n1 := []uint32{33, 12}
	// Second number is 21<<32 + 23
	n2 := []uint32{21, 23}
	// Add them together without producing carry.
	d1, carry := bits.Add32(n1[1], n2[1], 0)
	d0, _ := bits.Add32(n1[0], n2[0], carry)
	nsum := []uint32{d0, d1}
	fmt.Printf("%v + %v = %v (carry bit was %v)\n", n1, n2, nsum, carry)

	// First number is 1<<32 + 2147483648
	n1 = []uint32{1, 0x80000000}
	// Second number is 1<<32 + 2147483648
	n2 = []uint32{1, 0x80000000}
	// Add them together producing carry.
	d1, carry = bits.Add32(n1[1], n2[1], 0)
	d0, _ = bits.Add32(n1[0], n2[0], carry)
	nsum = []uint32{d0, d1}
	fmt.Printf("%v + %v = %v (carry bit was %v)\n", n1, n2, nsum, carry)
}

Output:
[33 12] + [21 23] = [54 35] (carry bit was 0)
[1 2147483648] + [1 2147483648] = [3 0] (carry bit was 1)

func Add64 added in go1.12 

func Add64(x, y, carry uint64) (sum, carryOut uint64)

Add64 returns the sum with carry of x, y and carry: sum = x + y + carry. The carry input must be 0 or 1; otherwise the behavior is undefined. The carryOut output is guaranteed to be 0 or 1.

This function's execution time does not depend on the inputs.

Example 
package main

import (
	"fmt"
	"math/bits"
)

func main() {
	// First number is 33<<64 + 12
	n1 := []uint64{33, 12}
	// Second number is 21<<64 + 23
	n2 := []uint64{21, 23}
	// Add them together without producing carry.
	d1, carry := bits.Add64(n1[1], n2[1], 0)
	d0, _ := bits.Add64(n1[0], n2[0], carry)
	nsum := []uint64{d0, d1}
	fmt.Printf("%v + %v = %v (carry bit was %v)\n", n1, n2, nsum, carry)

	// First number is 1<<64 + 9223372036854775808
	n1 = []uint64{1, 0x8000000000000000}
	// Second number is 1<<64 + 9223372036854775808
	n2 = []uint64{1, 0x8000000000000000}
	// Add them together producing carry.
	d1, carry = bits.Add64(n1[1], n2[1], 0)
	d0, _ = bits.Add64(n1[0], n2[0], carry)
	nsum = []uint64{d0, d1}
	fmt.Printf("%v + %v = %v (carry bit was %v)\n", n1, n2, nsum, carry)
}

Output:
[33 12] + [21 23] = [54 35] (carry bit was 0)
[1 9223372036854775808] + [1 9223372036854775808] = [3 0] (carry bit was 1)

func Div added in go1.12 

func Div(hi, lo, y uint) (quo, rem uint)

Div returns the quotient and remainder of (hi, lo) divided by y: quo = (hi, lo)/y, rem = (hi, lo)%y with the dividend bits' upper half in parameter hi and the lower half in parameter lo. Div panics for y == 0 (division by zero) or y <= hi (quotient overflow).

func Div32 added in go1.12 

func Div32(hi, lo, y uint32) (quo, rem uint32)

Div32 returns the quotient and remainder of (hi, lo) divided by y: quo = (hi, lo)/y, rem = (hi, lo)%y with the dividend bits' upper half in parameter hi and the lower half in parameter lo. Div32 panics for y == 0 (division by zero) or y <= hi (quotient overflow).

Example 
package main

import (
	"fmt"
	"math/bits"
)

func main() {
	// First number is 0<<32 + 6
	n1 := []uint32{0, 6}
	// Second number is 0<<32 + 3
	n2 := []uint32{0, 3}
	// Divide them together.
	quo, rem := bits.Div32(n1[0], n1[1], n2[1])
	nsum := []uint32{quo, rem}
	fmt.Printf("[%v %v] / %v = %v\n", n1[0], n1[1], n2[1], nsum)

	// First number is 2<<32 + 2147483648
	n1 = []uint32{2, 0x80000000}
	// Second number is 0<<32 + 2147483648
	n2 = []uint32{0, 0x80000000}
	// Divide them together.
	quo, rem = bits.Div32(n1[0], n1[1], n2[1])
	nsum = []uint32{quo, rem}
	fmt.Printf("[%v %v] / %v = %v\n", n1[0], n1[1], n2[1], nsum)
}

Output:
[0 6] / 3 = [2 0]
[2 2147483648] / 2147483648 = [5 0]

func Div64 added in go1.12 

func Div64(hi, lo, y uint64) (quo, rem uint64)

Div64 returns the quotient and remainder of (hi, lo) divided by y: quo = (hi, lo)/y, rem = (hi, lo)%y with the dividend bits' upper half in parameter hi and the lower half in parameter lo. Div64 panics for y == 0 (division by zero) or y <= hi (quotient overflow).

Example 
package main

import (
	"fmt"
	"math/bits"
)

func main() {
	// First number is 0<<64 + 6
	n1 := []uint64{0, 6}
	// Second number is 0<<64 + 3
	n2 := []uint64{0, 3}
	// Divide them together.
	quo, rem := bits.Div64(n1[0], n1[1], n2[1])
	nsum := []uint64{quo, rem}
	fmt.Printf("[%v %v] / %v = %v\n", n1[0], n1[1], n2[1], nsum)

	// First number is 2<<64 + 9223372036854775808
	n1 = []uint64{2, 0x8000000000000000}
	// Second number is 0<<64 + 9223372036854775808
	n2 = []uint64{0, 0x8000000000000000}
	// Divide them together.
	quo, rem = bits.Div64(n1[0], n1[1], n2[1])
	nsum = []uint64{quo, rem}
	fmt.Printf("[%v %v] / %v = %v\n", n1[0], n1[1], n2[1], nsum)
}

Output:
[0 6] / 3 = [2 0]
[2 9223372036854775808] / 9223372036854775808 = [5 0]

func LeadingZeros 

func LeadingZeros(x uint) int

LeadingZeros returns the number of leading zero bits in x; the result is UintSize for x == 0.

func LeadingZeros8 

func LeadingZeros8(x uint8) int

LeadingZeros8 returns the number of leading zero bits in x; the result is 8 for x == 0.

Example 
package main

import (
	"fmt"
	"math/bits"
)

func main() {
	fmt.Printf("LeadingZeros8(%08b) = %d\n", 1, bits.LeadingZeros8(1))
}

Output:
LeadingZeros8(00000001) = 7

func LeadingZeros16 

func LeadingZeros16(x uint16) int

LeadingZeros16 returns the number of leading zero bits in x; the result is 16 for x == 0.