BitPack: Library for packing and unpacking binary strings
BitPack is a library that provides an easy to use API for packing and unpacking arbitrary binary strings. Unlike Array#pack and String#unpack, BitPack objects allow you to pack and unpack fields of arbitrary bit lengths.
Installing BitPack
Get BitPack from RubyForge.
$ gem install bitpack
Example
In this example, we will see how to pack and unpack a contrived message format.
The format is as follows:
-
field
foo
: unsigned integer, 3 bits in length -
field
bar
: unsigned integer, 13 bits in length -
field
baz
: octet string,bar
bytes in lengthrequire 'rubygems' require 'bitpack' class Message attr_accessor :foo, :bar, :baz def initialize(foo=nil, =nil, baz=nil) @foo = foo @bar = @baz = baz end def pack # create a new BitPack object to pack the message into bp = BitPack.new # pack field foo into 3 bits bp.append_bits(@foo, 3) # pack field bar into 13 bits bp.append_bits(@bar, 13) # finally, pack baz as a string bp.append_bytes(@baz) # convert the BitPack to a string bp.to_bytes end def self.unpack(bytes) m = self.new # create a new BitPack from the packed message string bp = BitPack.from_bytes(bytes) # unpack field foo from the first 3 bits m.foo = bp.read_bits(3) # unpack field bar from the next 13 bits m. = bp.read_bits(13) # finally, unpack the string baz from the next bar bytes m.baz = bp.read_bytes(m.) m end end m1 = Message.new m1.foo = 5 s = "BitPack makes packing and unpacking binary strings easy!" m1. = s.length m1.baz = s bytes = m1.pack p bytes #=> "\2408BitPack makes packing and unpacking binary strings easy!" m2 = Message.unpack(bytes) p m2.foo #=> 5 p m2. #=> 56 p m2.baz #=> "BitPack makes packing and unpacking binary strings easy!"
Notes
BitPack is almost entirely implemented as a C library. If you would like to use BitPack from a C program, just grab the bitpack.c and bitpack.h files from the ext/ directory of the gem and include them in your project. Documentation can be found in bitpack.h and example usage can be seen in test/bitpack_tests.c.