shifty

README

go-shifty

Package shifty offers quick and extensible additive bit shifting for simple configuration values, such as those describing a combination of log levels.

Documentation

Index

• type BitValue
  • func New(k Kind) (bv BitValue)
  • func (r BitValue) All() BitValue
  • func (r BitValue) Int() (i int)
  • func (r BitValue) Kind() Kind
  • func (r BitValue) Max() (max int)
  • func (r BitValue) Min() (min int)
  • func (r BitValue) NamesMap() map[int]string
  • func (r BitValue) None() BitValue
  • func (r BitValue) Positive(x any) (posi bool)
  • func (r *BitValue) SetNamesMap(m map[int]string)
  • func (r BitValue) Shift(x ...any) BitValue
  • func (r BitValue) Size() (size int)
  • func (r BitValue) Unshift(x ...any) BitValue
  • func (r BitValue) Value() any
• type Kind
  • func (r Kind) Size() (size int)
  • func (r Kind) String() (k string)

Examples

• BitValue.All
• BitValue.Int
• BitValue.Int (Mixed)
• BitValue.Kind
• BitValue.Max (For16Bit)
• BitValue.Max (For32bit)
• BitValue.Max (For8Bit)
• BitValue.Min
• BitValue.NamesMap
• BitValue.None
• BitValue.Positive
• BitValue.SetNamesMap
• BitValue.Shift
• BitValue.Size
• BitValue.Unshift
• BitValue.Value
• Kind.Size
• Kind.String
• New

Types

type BitValue

type BitValue struct {
	// contains filtered or unexported fields
}

BitValue contains the allocated value type, a Kind and a bit size reflecting the allocated instance magnitude.

Shift, Unshift and Positive operations may be conducted against instances of this type.

New instances of this type are created using the New package-level function.

func New

func New(k Kind) (bv BitValue)

New initializes a new instance of BitValue, using Kind k as the indicator for the desired bit allocation size. See the Kind constants for available values.

Example

bits := New(Uint16)
fmt.Printf("%T size %d, max %d", bits, bits.Size(), bits.Max())

Output:

shifty.BitValue size 16, max 65535

func (BitValue) All

func (r BitValue) All() BitValue

All is a convenience method that calls r.Shift(r.Max()), which will set the underlying integer value to ^uintN(0) (allocated maximum).

Example

bits := New(Uint16)
bits.All() // shift EVERYTHING

fmt.Printf("%d", bits.Int())

Output:

65535

func (BitValue) Int

func (r BitValue) Int() (i int)

Int returns the integer form of the underlying allocated value. As only unsigned integer types are supported in this package, the value shall never be less than zero (0).

Example

bits := New(Uint8)
bits.Shift(2, 4, 32)
fmt.Printf("%d", bits.Int())

Output:

38

Example (Mixed)

var ints []int
for i := 0; i < 3; i++ {
	bits := New(Kind(i + 1))
	bits.Shift(bits.Size() << i)
	ints = append(ints, bits.Int())
}
fmt.Printf("%v", ints)

Output:

[8 32 128]

func (BitValue) Kind

func (r BitValue) Kind() Kind

Kind returns the instance of Kind assigned to the receiver instance, which can be one (1) of three (3) possible values.

See the Kind constants for the complete list.

Example

bits := New(Uint32)
fmt.Printf("%s", bits.Kind())

Output:

uint32

func (BitValue) Max

func (r BitValue) Max() (max int)

Max returns ^uintN(0), where N is a bit size of eight (8), sixteen (16), or thirty-two (32).

The returned integer represents the largest possible value permitted by the underlying allocated instance.

Example (For16Bit)

bits := New(Uint16)
fmt.Printf("%d", bits.Max())

Output:

65535

Example (For32bit)

bits := New(Uint32)
fmt.Printf("%d", bits.Max())

Output:

4294967295

Example (For8Bit)

bits := New(Uint8)
fmt.Printf("%d", bits.Max())

Output:

255

func (BitValue) Min

func (r BitValue) Min() (min int)

Min returns zero (0), which indicates the lowest permitted value within the receiver for any supported allocation.

Example

var bits BitValue
fmt.Printf("%d", bits.Min())

Output:

0

func (BitValue) NamesMap

func (r BitValue) NamesMap() map[int]string

NamesMap returns the instance of map[int]string found within the receiver instance, else nil is returned.

The map is used to resolve string names to shift values (e.g.: consts).

Example

bits := New(Uint8)
fmt.Printf("%T", bits.NamesMap()) // note this is a nil map

Output:

map[int]string

func (BitValue) None

func (r BitValue) None() BitValue

None is a convenience method that calls r.Unshift(r.Max()), which will set the underlying integer value to zero (0) (allocated minimum).

Example

bits := New(Uint8)
bits.Shift(8 << 1)
bits.None() // annihilate any value

fmt.Printf("%d", bits.Int())

Output:

0

func (BitValue) Positive

func (r BitValue) Positive(x any) (posi bool)

Positive returns a Boolean value indicative of whether input value x's bits are set within the receiver. Negation (!) implies negative, or 'bit not set'.

Example

// user-defined shift values
type B uint8
const (
	Bopt1 B = 1 << iota //   1
	Bopt2               //   2
	Bopt3               //   4
	Bopt4               //   8
	Bopt5               //  16
	Bopt6               //  32
	Bopt7               //  64
	Bopt8               // 128	// go no higher (else, overflow uint8)
)

bits := New(Uint8)
bits.Shift(Bopt1, Bopt3, Bopt6)
fmt.Printf("Value contains B-options #6 (32): %t", bits.Positive(Bopt6))

Output:

Value contains B-options #6 (32): true

func (*BitValue) SetNamesMap

func (r *BitValue) SetNamesMap(m map[int]string)

SetNamesMap assigns an instance of map[int]string to the receiver. The instance, if non-nil, shall be used to resolve string names to shift values (e.g.: consts).

Case is not significant in the string matching process.

Example

// user-defined shift values
bits := New(Uint8)

type B uint8
const (
	Bopt1 B = 1 << iota //   1
	Bopt2               //   2
	Bopt3               //   4
	Bopt4               //   8
	Bopt5               //  16
	Bopt6               //  32
	Bopt7               //  64
	Bopt8               // 128      // go no higher (else, overflow uint8)
)

// create a const->name map using
// the above const vals by way of
// incremental shifts. Note that
// we could have just as easily
// built the map manually, though
// but looping is neater and more
// succinct.
var m map[int]string = make(map[int]string, 0)
for i := 0; i < bits.Size(); i++ {
	str := fmt.Sprintf("bit_option%d", i+1) // inc. label number since we start at zero
	bv := 1 << i
	m[bv] = str
}

// assign map to receiver
bits.SetNamesMap(m)

// now shift by string name instead
// of a constant directly :)
name := `bit_option6`
bits.Shift(name)

fmt.Printf("Value contains %s: %t (val:%d)", name, bits.Positive(name), bits.Int())

Output:

Value contains bit_option6: true (val:32)

func (BitValue) Shift

func (r BitValue) Shift(x ...any) BitValue

Shift shall left-shift the bits within the receiver to include input value(s) x.

If any of values x are considered extremes in their magnitudes (either zero or the maximum allowed per allocation size), one (1) of the following shall occur:

• If value is the maximum, receiver will be clobbered with it (overwritten), i.e.: shift all
• If value is zero (0), no shift shall occur as it is illogical and not actionable

Additionally, if a maximum value is present within a variadic call containing >1 slice, unexpected results may ensue. Generally, use of the maximum value should be used in unary context when calling this method.

Example

bits := New(Uint8)
bits.Shift(2, 4, 32)
fmt.Printf("Value: %d", bits.Int())

Output:

Value: 38

func (BitValue) Size

func (r BitValue) Size() (size int)

Size returns the underlying bit size of the receiver.

Example

bits := New(Uint32)
fmt.Printf("%d", bits.Size())

Output:

32

func (BitValue) Unshift

func (r BitValue) Unshift(x ...any) BitValue

Unshift shall right-shift the bits within the receiver to remove input value(s) x.

If any of values x are considered extremes in their magnitudes (either zero or the maximum allowed per allocation size), one (1) of the following shall occur:

• If value is the maximum, receiver will be annihilated to zero (0), i.e.: unshift all
• If value is zero (0), no unshift shall occur as it is illogical and not actionable

Additionally, if a maximum value is present within a variadic call containing >1 slice, unexpected results may ensue. Generally, use of the maximum value should be used in unary context when calling this method.

Example

bits := New(Uint8)
bits.Shift(2, 4, 32)
bits.Unshift(32)
fmt.Printf("Value: %d", bits.Int())

Output:

Value: 6

func (BitValue) Value

func (r BitValue) Value() any

Value returns the unasserted (POINTER) instance of an interface (any) within the receiver instance. If the value is nil, this indicates the receiver instance has not yet been initialized (hint: see New function).

Example

bits := New(Uint32)
bits.Shift(bits.Max())
fmt.Printf("%T", bits.Value())

Output:

*uint32

type Kind

type Kind uint8

Kind represents the specific unsigned integer type selected for use within instances of BitValue.

const (
	Uint8  Kind // 0x1; allows eight (8) bits, max val: 255
	Uint16      // 0x2; allows sixteen (16) bits, max val: 65535
	Uint32      // 0x3; allows thirty-two (32) bits, max val: 4294967295
)

Kind constants define the desired bit allocation size for an instance of BitValue.

func (Kind) Size

func (r Kind) Size() (size int)

Size returns the bit size of the receiver. Possible (valid) values are eight (8), sixteen (16) or thirty-two (32).

A value of zero (0) indicates the instance has not yet been initialized (hint: see the New function).

Example

k := Uint32
fmt.Printf("%d", k.Size())

Output:

32

func (Kind) String

func (r Kind) String() (k string)

String returns the string name of the receiver instance, each of which are literals of the underlying type which was selected during initialization:

• uint8
• uint16
• uint32

Example

fmt.Printf("%s", Uint32)

Output:

uint32