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.
= 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 length
require 'rubygems'
require 'bitpack'
class Message
attr_accessor :foo, :bar, :baz
def initialize(foo=nil, bar=nil, baz=nil)
@foo = foo
@bar = 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.bar = bp.read_bits(13)
# finally, unpack the string baz from the next bar bytes
m.baz = bp.read_bytes(m.bar)
m
end
end
m1 = Message.new
m1.foo = 5
s = "BitPack makes packing and unpacking binary strings easy!"
m1.bar = 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.bar
#=> 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 <tt>bitpack.c</tt> and <tt>bitpack.h</tt> files from
the <tt>ext/</tt> directory of the gem and include them in your project. Documentation
can be found in <tt>bitpack.h</tt> and example usage can be seen in <tt>test/bitpack_tests.c</tt>.
= Project Page
http://rubyforge.org/projects/bitpack