bitflag

Documentation

Overview

Package bitflag provides a generic, type-safe bitset for flag fields in binary protocol headers.

Flags are parameterised over any unsigned integer type, including user-defined named types. This lets the compiler reject accidental mixing of flag constants from different fields.

type MsgFlags uint8

const (
    FlagAck      MsgFlags = 1 << 0
    FlagRetry    MsgFlags = 1 << 1
    FlagCompress MsgFlags = 1 << 2
)

f := bitflag.Of(FlagAck, FlagCompress)
f.Has(FlagAck)      // true
f.Has(FlagRetry)    // false
raw := f.Value()    // MsgFlags(0b00000101)

Example

package main

import (
	"fmt"

	"lowbit.dev/wireframe/bitflag"
)

// NetFlags represents TCP-like control flags packed in a single byte.
type NetFlags uint8

const (
	FlagSYN NetFlags = 1 << 0
	FlagACK NetFlags = 1 << 1
	FlagFIN NetFlags = 1 << 2
)

func main() {
	f := bitflag.Of(FlagSYN)
	f.Set(FlagACK)

	fmt.Println(f.Has(FlagSYN))
	fmt.Println(f.Has(FlagFIN))
	f.Clear(FlagSYN)
	fmt.Println(f.Value()) // only FlagACK remains
}

Output:
true
false
2

Index

• type Flags
  • func Of[T Integer](flags ...T) Flags[T]
  • func (f *Flags[T]) Clear(flags ...T)
  • func (f Flags[T]) Has(flag T) bool
  • func (f Flags[T]) HasAll(flags ...T) bool
  • func (f Flags[T]) HasAny(flags ...T) bool
  • func (f *Flags[T]) Set(flags ...T)
  • func (f Flags[T]) Value() T
• type Integer

Examples

• Package
• Flags.Clear
• Flags.Has
• Flags.HasAll
• Flags.HasAny
• Flags.Set
• Flags.Value
• Of

Types

type Flags

type Flags[T Integer] struct {
	// contains filtered or unexported fields
}

Flags is a type-safe bitset backed by an unsigned integer of type T.

func Of

func Of[T Integer](flags ...T) Flags[T]

Of constructs a Flags value with the given flags set.

Example

package main

import (
	"fmt"

	"lowbit.dev/wireframe/bitflag"
)

// NetFlags represents TCP-like control flags packed in a single byte.
type NetFlags uint8

const (
	FlagSYN NetFlags = 1 << 0
	FlagACK NetFlags = 1 << 1
	FlagFIN NetFlags = 1 << 2
)

func main() {
	f := bitflag.Of(FlagSYN, FlagACK)
	fmt.Println(f.Has(FlagSYN))
	fmt.Println(f.Has(FlagFIN))
	fmt.Println(f.Value()) // FlagSYN | FlagACK = 3
}

Output:
true
false
3

func (*Flags[T]) Clear

func (f *Flags[T]) Clear(flags ...T)

Clear clears the given flags, leaving others unchanged.

Example

package main

import (
	"fmt"

	"lowbit.dev/wireframe/bitflag"
)

// NetFlags represents TCP-like control flags packed in a single byte.
type NetFlags uint8

const (
	FlagSYN NetFlags = 1 << 0
	FlagACK NetFlags = 1 << 1
	FlagFIN NetFlags = 1 << 2
)

func main() {
	f := bitflag.Of(FlagSYN, FlagACK, FlagFIN)
	f.Clear(FlagACK)
	fmt.Println(f.Has(FlagACK))
	fmt.Println(f.Value()) // FlagSYN | FlagFIN = 5
}

Output:
false
5

func (Flags[T]) Has

func (f Flags[T]) Has(flag T) bool

Has reports whether flag is set. Exactly one bit should be set in flag.

Example

package main

import (
	"fmt"

	"lowbit.dev/wireframe/bitflag"
)

// NetFlags represents TCP-like control flags packed in a single byte.
type NetFlags uint8

const (
	FlagSYN NetFlags = 1 << 0
	FlagACK NetFlags = 1 << 1
)

func main() {
	f := bitflag.Of(FlagSYN)
	fmt.Println(f.Has(FlagSYN))
	fmt.Println(f.Has(FlagACK))
}

Output:
true
false

func (Flags[T]) HasAll

func (f Flags[T]) HasAll(flags ...T) bool

HasAll reports whether all of the given flags are set.

Example

package main

import (
	"fmt"

	"lowbit.dev/wireframe/bitflag"
)

// NetFlags represents TCP-like control flags packed in a single byte.
type NetFlags uint8

const (
	FlagSYN NetFlags = 1 << 0
	FlagACK NetFlags = 1 << 1
	FlagFIN NetFlags = 1 << 2
)

func main() {
	f := bitflag.Of(FlagSYN, FlagACK)
	fmt.Println(f.HasAll(FlagSYN, FlagACK))
	fmt.Println(f.HasAll(FlagSYN, FlagFIN))
}

Output:
true
false

func (Flags[T]) HasAny

func (f Flags[T]) HasAny(flags ...T) bool

HasAny reports whether at least one of the given flags is set.

Example

package main

import (
	"fmt"

	"lowbit.dev/wireframe/bitflag"
)

// NetFlags represents TCP-like control flags packed in a single byte.
type NetFlags uint8

const (
	FlagSYN NetFlags = 1 << 0
	FlagACK NetFlags = 1 << 1
	FlagFIN NetFlags = 1 << 2
)

func main() {
	f := bitflag.Of(FlagSYN)
	fmt.Println(f.HasAny(FlagSYN, FlagFIN))
	fmt.Println(f.HasAny(FlagACK, FlagFIN))
}

Output:
true
false

func (*Flags[T]) Set

func (f *Flags[T]) Set(flags ...T)

Set sets the given flags, leaving others unchanged.

Example

package main

import (
	"fmt"

	"lowbit.dev/wireframe/bitflag"
)

// NetFlags represents TCP-like control flags packed in a single byte.
type NetFlags uint8

const (
	FlagSYN NetFlags = 1 << 0

	FlagFIN NetFlags = 1 << 2
)

func main() {
	var f bitflag.Flags[NetFlags]
	f.Set(FlagSYN)
	f.Set(FlagFIN)
	fmt.Println(f.Value()) // FlagSYN | FlagFIN = 5
}

Output:
5

func (Flags[T]) Value

func (f Flags[T]) Value() T

Value returns the underlying integer representation.

Example

package main

import (
	"fmt"

	"lowbit.dev/wireframe/bitflag"
)

// NetFlags represents TCP-like control flags packed in a single byte.
type NetFlags uint8

const (
	FlagSYN NetFlags = 1 << 0
	FlagACK NetFlags = 1 << 1
)

func main() {
	f := bitflag.Of(FlagSYN, FlagACK)
	fmt.Println(f.Value()) // 1 | 2 = 3
}

Output:
3

type Integer

type Integer interface {
	~uint8 | ~uint16 | ~uint32 | ~uint64
}

Integer is the constraint satisfied by unsigned integer types and user-defined types with an unsigned integer base.