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