Steve Bertrand

# NAME

Bit::Manip::PP - Pure Perl 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

This is the Pure Perl version of the XS-based Bit::Manip distribution.

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

In functions that modify your data, you can pass your data by value and get the modified value returned, or pass it in as a scalar reference and we'll modify the data inline.

Currently, up to 32-bit integers are supported.

# 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>`