# NAME

Bit::Manip - Functions to simplify bit string manipulation

# SYNOPSIS

```
use Bit::Manip qw(:all);
my $b; # bit string
$b = 128; # 10000000
$b = bit_toggle($b, 4); # 10010000
$b = bit_toggle($b, 4); # 10000000
$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.

# 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_toggle
bit_on
bit_off
bit_bin
bit_count
bit_mask
```

# FUNCTIONS

## bit_get

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). This value must be lower than `$msb`

.

Return: Integer, the modified `$data`

param.

## bit_set

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

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.

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

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

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

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

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.

## bit_mask

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.

Return: Integer, the bit mask ready to be applied.

# AUTHOR

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

# LICENSE AND COPYRIGHT

Copyright 2017 Steve Bertrand.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.