# NAME

Bit::Manip - Functions to simplify bit string manipulation

# SYNOPSIS

``````    use Bit::Manip qw(:all);

my \$b;    # bit string
\$b = 128; # 10000000

# toggle a bit off and on

\$b = bit_tog(\$b, 4); # 10010000
\$b = bit_tog(\$b, 4); # 10000000

# turn a bit off, then back on

\$b = bit_off(\$b, 7);    # 0
\$b = bit_on(\$b, 7);     # 10000000

# get the value of a range of bits...
# in this case, we'll print the value of bits 4-3

\$b = 0b00111000; (56)

print bit_get(\$b, 4, 3); # 3

# set a range of bits...
# let's set bits 4-2 to binary 101

\$b = 0b10000000;
my \$num_bits = 3; # 0b101 in the call is 3 bits

\$b = bit_set(\$b, 2, \$num_bits, 0b101); # 10010100

# clear some bits

\$b = 0b11111111;

\$num_bits = 3;
\$lsb = 3;

\$b = bit_clr(\$b, \$lsb, \$num_bits); # 11000111

# helpers

my (\$num_bits, \$lsb) = (3, 2);
print bit_mask(\$num_bits, \$lsb); # 28, or 11100

print bit_bin(255); # 11111111 (same as printf("%b", 255);)
``````

# DESCRIPTION

Provides functions to aid in bit manipulation (get, set, clear, toggle) etc. Particularly useful for embedded programming and writing device communication software.

Currently, up to 32-bit integers are supported.

Note that if your machine isn't capable of compiling C code, there's a pure Perl version as well, aptly named Bit::Manip::PP.

# EXPORT_OK

Use the `:all` tag (eg: `use Bit::Manip qw(:all);`) to import the following functions into your namespace, or pick and choose individually:

``````    bit_get
bit_set
bit_clr
bit_tog
bit_on
bit_off
bit_bin
bit_count

# FUNCTIONS

## bit_get(\$data, \$msb, \$lsb)

Retrieves the value of specified bits within a bit string.

Parameters:

``    \$data``

Mandatory: Integer, the bit string you want to send in. Eg: `255` for `11111111` (or `0xFF`).

``    \$msb``

Mandatory: Integer, the Most Significant Bit (leftmost) of the group of bits to collect the value for (starting from 0 from the right, so with `1000`, so you'd send in `3` as the start parameter for the bit set to `1`). Must be `1`

``    \$lsb``

Optional: Integer, the Least Significant Bit (rightmost) of the group of bits to collect the value for (starting at 0 from the right). A value of `0` means return the value from `\$msb` through to the very end of the bit string. A value of `1` will capture from `\$msb` through to bit `1` (second from right). If `\$msb` is equal to `\$lsb`, we'll return just that bit.

Return: Integer, the modified `\$data` param.

## bit_set(\$data, \$lsb, \$nbits, \$value)

Allows you to set a value for specific bits in your bit string.

Parameters:

``    \$data``

Mandatory: Integer, the bit string you want to manipulate bits in.

``    \$lsb``

Mandatory: Integer, the least significant bit (rightmost) in the bit range you want to manipulate. For example, if you wanted to set a new value for bits `7-5`, you'd send in `5`.

``    \$nbits``

Mandatory: Integer, the number of bits you're sending in. We need this param in the event your leading bit is a zero. For example, if you're sending in `0b111` or `0b001`, this param would be `3`.

``    \$value``

Mandatory: Integer, the value that you want to change the specified bits to. Easiest if you send in a binary string (eg: `0b1011` in Perl).

Return: Integer, the modified `\$data` param.

Example:

You have an 8-bit register where the MSB is a start bit, and the rest of the bits are zeroed out:

``    my \$data = 0b10000000; # (0x80, or 128)``

The datasheet for the hardware you're writing to requires you to set bits `6-4` to `111` in binary (always start from bit 0, not 1):

``````    10000000
^^^   ^
6-4   0``````

Code:

``````    my \$x = bit_set(\$data, 4, 3, 0b111); # (0x07, or 7)
printf("%b\n", \$x); # prints 11110000``````

## bit_clr(\$data, \$lsb, \$nbits)

Clear (unset to 0) specific bits in the bit string.

Parameters:

``    \$data``

Mandatory: Integer, the bit string you want to manipulate bits in.

``    \$lsb``

Mandatory: Integer, the least significant bit (rightmost) in the bit range you want to manipulate. For example, if you wanted to clear bits `7-5`, you'd send in `5`.

``    \$nbits``

Mandatory: Integer, the number of bits you're wanting to clear, starting from the `\$lsb` bit, and clearing the number of bits to the left.

Returns the modified bit string.

See "bit_tog".

## bit_tog(\$data, \$bit)

AKA: `bit_toggle()`.

Toggles a single bit. If it's `0` it'll toggle to `1` and vice-versa.

Parameters:

``    \$data``

Mandatory: Integer, the number/bit string to toggle a bit in.

``    \$bit``

Mandatory: Integer, the bit number counting from the right-most (LSB) bit starting from `0`.

Return: Integer, the modified `\$data` param.

## bit_on(\$data, \$bit)

Sets a single bit (sets to `1`), regardless of its current state. This is just a short form of setting a single bit with bit_set.

Parameters:

``    \$data``

Mandatory: Integer, the number/bit string to toggle a bit in.

``    \$bit``

Mandatory: Integer, the bit number counting from the right-most (LSB) bit starting from `0`.

Return: Integer, the modified `\$data` param.

## bit_off(\$data, \$bit)

Unsets a single bit (sets to `0`), regardless of its current state. This is just a short form of clearing a single bit with bit_set.

Parameters:

``    \$data``

Mandatory: Integer, the number/bit string to toggle a bit in.

``    \$bit``

Mandatory: Integer, the bit number counting from the right-most (LSB) bit starting from `0`.

Return: Integer, the modified `\$data` param.

## bit_bin(\$data)

Returns the binary representation of a number as a string of ones and zeroes.

Parameters:

``    \$data``

Mandatory: Integer, the number you want to convert.

## bit_count(\$num, \$set)

Returns either the total count of bits in a number, or just the number of set bits (if the `\$set`, parameter is sent in and is true).

Parameters:

``    \$num``

Mandatory: Unsigned integer, the number to retrieve the total number of bits for. For example, if you send in `15`, the total number of bits would be `4`, likewise, for `255`, the number of bits would be `16`.

``    \$set``

Optional: Integer. If this is sent and is a true value, we'll return the number of *set* bits only. For example, for `255`, the set bits will be `8` (ie. all of them), and for `8`, the return will be `1` (as only the MSB is set out of all four of the total).

Return: Integer, the number of bits that make up the number if `\$set` is `0`, and the number of set bits (1's) if `\$set` is true.

Generates a bit mask for the specific bits you specify.

Parameters:

``    \$nbits``

Mandatory: Integer, the number of bits to get the mask for.

``    \$lsb``

Mandatory: Integer, the LSB at which you plan on implementing your change.

Steve Bertrand, `<steveb at cpan.org>`