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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.