tuple 0.1.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Justin Balthrop
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,32 @@
+= Tuple
+
+Tuple provides fast, binary-sortable serialization for arrays of simple Ruby types. This
+means you do not have to deserialize your tuples to store them. This leads to significant
+performance benifits when using Tuples as keys for a BTree.
+
+A Tuple is just an Array of any number of simple Ruby types. The following types are
+supported (listed in ascending sort order):
+  
+1. NilClass
+2. FalseClass
+3. Integer (Fixnum or Bignum)
+4. String
+5. Symbol
+6. True
+
+== Usage:
+   
+  require 'tuple'
+
+  data = Tuple.dump([1, -43, :foo, "bar", true, false, nil])
+  => "\000\000\020\000\000\000\000\001..."
+  Tuple.load(data)
+  => [1, -43, :foo, "bar", true, false, nil]
+
+== Install:
+
+  sudo gem install ninjudd-tuple -s http://gems.github.com
+
+== License:
+
+Copyright (c) 2009 Justin Balthrop, Geni.com; Published under The MIT License, see LICENSE

data/ext/extconf.rb

@@ -0,0 +1,2 @@
+require 'mkmf'
+create_makefile('tuple')

data/ext/tuple.c

@@ -0,0 +1,235 @@
+#include "ruby.h"
+#include <netinet/in.h>
+
+VALUE mTuple;
+VALUE rb_cDate;
+
+#define TRUE_SORT  255 // TrueClass
+#define TUPLE_SORT 192 // Array
+#define TUPLE_END  191 // For nested tuples 
+#define TIME_SORT  128 // Time
+#define SYM_SORT    64 // Symbol
+#define STR_SORT    32 // String
+#define INTP_SORT   16 // Integer (Positive)
+#define INTN_SORT    8 // Integer (Negative)
+#define FALSE_SORT   1 // FalseClass
+#define NIL_SORT     0 // NilClass
+
+#define BDIGITS(x) ((BDIGIT*)RBIGNUM(x)->digits)
+
+static void null_pad(VALUE data, int len) {
+  static u_int8_t null = 0;
+
+  // Pad with null bytes so subsequent fields will be aligned.
+  while (len % 4 != 0) {
+    rb_str_cat(data, (char*)&null, 1);
+    len++;
+  }
+}
+
+
+u_int32_t split64(int64_t num, int word) {
+  u_int32_t *split = (u_int32_t*)(void*)&num;
+
+  static int i = 1;
+  if (*(char *)&i == 1) word = word ? 1: 0;
+  else                  word = word ? 0: 1;
+
+  return split[word];
+}
+
+
+
+/*
+ * call-seq:
+ * Tuple.dump(tuple) -> string
+ *
+ * Dumps an array of simple Ruby types into a string of binary data.
+ *
+ */
+static VALUE tuple_dump(VALUE self, VALUE tuple) {
+  VALUE data = rb_str_new2("");
+  VALUE item;
+  int i, j, len, sign;
+  u_int8_t header[4];
+  u_int32_t digit;
+  int64_t fixnum;
+  BDIGIT *digits;
+
+
+  if (TYPE(tuple) != T_ARRAY) tuple = rb_ary_new4(1, &tuple);
+
+  for (i = 0; i < RARRAY(tuple)->len; i++) {
+    item = RARRAY(tuple)->ptr[i];
+    header[0] = header[1] = header[2] = header[3] = 0;
+    if (FIXNUM_P(item)) {
+      fixnum = FIX2LONG(item);
+      sign = (fixnum >= 0);
+      if (!sign) fixnum = -fixnum;
+      len = fixnum > UINT_MAX ? 2 : 1;
+      header[2] = sign ? INTP_SORT : INTN_SORT;
+      header[3] = sign ? len : UCHAR_MAX - len;
+      rb_str_cat(data, (char*)&header, sizeof(header));      
+
+      if (len == 2) {
+        digit = split64(fixnum, 1);
+        digit = htonl(sign ? digit : UINT_MAX - digit);
+        rb_str_cat(data, (char*)&digit, sizeof(digit));
+      }
+      digit = split64(fixnum, 0);
+      digit = htonl(sign ? digit : UINT_MAX - digit);
+      rb_str_cat(data, (char*)&digit, sizeof(digit));
+    } else if (TYPE(item) == T_BIGNUM) {
+      sign = RBIGNUM(item)->sign;
+      len  = RBIGNUM(item)->len;
+      header[2] = sign ? INTP_SORT : INTN_SORT;
+      header[3] = sign ? len : UCHAR_MAX - len;
+      rb_str_cat(data, (char*)&header, sizeof(header));
+
+      digits = BDIGITS(item);
+      for (j = len-1; j >= 0; j--) {
+        digit = htonl(sign ? digits[j] : (UINT_MAX - digits[j]));
+        rb_str_cat(data, (char*)&digit, sizeof(digit));
+      }
+    } else if (SYMBOL_P(item) || TYPE(item) == T_STRING) {
+      if (SYMBOL_P(item)) {
+        header[2] = SYM_SORT;
+        item = rb_funcall(item, rb_intern("to_s"), 0);
+      } else {
+        header[2] = STR_SORT;
+      }
+      rb_str_cat(data, (char*)&header, sizeof(header));
+      len = RSTRING_LEN(item);
+      rb_str_cat(data, RSTRING_PTR(item), len);
+      
+      null_pad(data, len);
+    } else if (rb_obj_class(item) == rb_cTime || rb_obj_class(item) == rb_cDate) {
+      header[2] = TIME_SORT;
+      rb_str_cat(data, (char*)&header, sizeof(header));
+
+      if (rb_obj_class(item) == rb_cTime) {
+        item = rb_funcall(item, rb_intern("getgm"), 0);
+        item = rb_funcall(item, rb_intern("strftime"), 1, rb_str_new2("%Y/%m/%d %H:%M:%S +0000"));
+      } else {
+        item = rb_funcall(item, rb_intern("strftime"), 1, rb_str_new2("%Y/%m/%d"));
+      }
+      len = RSTRING_LEN(item);
+      rb_str_cat(data, RSTRING_PTR(item), len);
+
+      null_pad(data, len);
+    } else if (TYPE(item) == T_ARRAY) {
+      header[2] = TUPLE_SORT;
+      rb_str_cat(data, (char*)&header, sizeof(header));
+
+      rb_str_concat(data, tuple_dump(mTuple, item));
+
+      header[2] = TUPLE_END;
+      rb_str_cat(data, (char*)&header, sizeof(header));      
+    } else {        
+      if      (item == Qnil)   header[2] = NIL_SORT;
+      else if (item == Qtrue)  header[2] = TRUE_SORT;
+      else if (item == Qfalse) header[2] = FALSE_SORT;
+      else    rb_raise(rb_eTypeError, "invalid type %s in tuple", rb_obj_classname(item));
+      
+      rb_str_cat(data, (char*)&header, sizeof(header));      
+    }
+  }
+  return data;
+}
+
+static VALUE empty_bignum(int sign, int len) {
+  /* Create an empty bignum with the right number of digits. */
+  NEWOBJ(num, struct RBignum);
+  OBJSETUP(num, rb_cBignum, T_BIGNUM);
+  num->sign = sign ? 1 : 0;
+  num->len = len;
+  num->digits = ALLOC_N(BDIGIT, len);
+
+  return (VALUE)num;
+}
+
+static VALUE tuple_parse(void **data, int data_len) {
+  VALUE tuple = rb_ary_new();
+  VALUE item;
+  void* ptr = *data; *data = &ptr;
+  void* end = ptr + data_len;
+  int i, len, sign;
+  u_int8_t header[4];
+  u_int32_t digit;
+  BDIGIT *digits;
+
+  while (ptr < end) {
+    memcpy(header, ptr, 4);
+    ptr += 4;
+
+    switch(header[2]) {
+    case TRUE_SORT:  rb_ary_push(tuple, Qtrue);  break;
+    case FALSE_SORT: rb_ary_push(tuple, Qfalse); break;
+    case NIL_SORT:   rb_ary_push(tuple, Qnil);   break;
+    case INTP_SORT:
+    case INTN_SORT:
+      sign  = (header[2] == INTP_SORT);
+      len   = sign ? header[3] : (UCHAR_MAX - header[3]);
+
+      item = empty_bignum(sign, len);
+      digits = BDIGITS(item);
+      for (i = len-1; i >= 0; i--) {
+        digit = ntohl(*(u_int32_t*)ptr);
+        digits[i] = sign ? digit : UINT_MAX - digit;
+        ptr += 4;
+      }
+      rb_ary_push(tuple, item);
+      break;
+    case STR_SORT:
+    case SYM_SORT:
+      item = rb_str_new2(ptr);
+      len  = RSTRING_LEN(item);
+      if (header[2] == SYM_SORT) item = rb_funcall(item, rb_intern("to_sym"), 0);
+      rb_ary_push(tuple, item);
+      while (len % 4 != 0) len++; ptr += len;
+      break;
+    case TIME_SORT:
+      item = rb_str_new2(ptr);
+      len  = RSTRING_LEN(item);
+      if (len == 10) item = rb_funcall(rb_cDate, rb_intern("parse"), 1, item);
+      else           item = rb_funcall(rb_cTime, rb_intern("parse"), 1, item);
+      rb_ary_push(tuple, item);
+      while (len % 4 != 0) len++; ptr += len;
+      break;
+    case TUPLE_SORT:
+      item = tuple_parse(&ptr, end - ptr);
+      rb_ary_push(tuple, item);
+      break;
+    case TUPLE_END:
+      return tuple;
+    default:
+      rb_raise(rb_eTypeError, "invalid type code %d in tuple", header[2]);
+      break;
+    }
+  }
+  return tuple;
+}
+
+/*
+ * call-seq:
+ * Tuple.load(string) -> tuple
+ *
+ * Reads in a previously dumped tuple from a string of binary data.
+ *
+ */
+static VALUE tuple_load(VALUE self, VALUE data) {
+  data = StringValue(data);
+  void* ptr = RSTRING_PTR(data);
+  return tuple_parse(&ptr, RSTRING_LEN(data));
+}
+
+VALUE mTuple;
+void Init_tuple() {
+  rb_require("time");
+  rb_require("date");
+  rb_cDate = rb_const_get(rb_cObject, rb_intern("Date"));
+
+  mTuple = rb_define_module("Tuple");
+  rb_define_module_function(mTuple, "dump", tuple_dump, 1);
+  rb_define_module_function(mTuple, "load", tuple_load, 1);
+}

data/test/test_helper.rb

@@ -0,0 +1,22 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'mocha'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../ext')
+require 'tuple'
+
+if not [].respond_to?(:shuffle)
+  class Array
+    def shuffle
+      t_self = self.dup 
+      t_size = self.size 
+      result=[] 
+      t_size.times { result << t_self.slice!(rand(t_self.size)) } 
+      result 
+    end
+  end
+end
+
+class Test::Unit::TestCase
+end

data/test/tuple_test.rb

@@ -0,0 +1,96 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class Time
+  def ==(other)
+    # Ignore microseconds for testing.
+    to_i == other.to_i
+  end
+end
+
+class TupleTest < Test::Unit::TestCase
+  should "dump and load arrays of simple types" do
+    t = [1, true, :foo, "foo", -1001, false, nil, Time.now, Date.today - 7, [:foo, 1, 4, nil]]
+    assert_equal t, Tuple.load(Tuple.dump(t))
+  end
+  
+  should "dump, load, and sort fixnums and bignums" do
+    t = [2**64, 2**38, 2**32, 2**32 - 1, 2**31, 2**31 - 1, 1, 0]
+    t = t + t.reverse.collect {|n| -n}
+    assert_equal t, Tuple.load(Tuple.dump(t))
+    assert_equal t.reverse, t.sort_by {|i| Tuple.dump(i)}
+  end
+
+  should "convert single value into array" do
+    assert_equal [1], Tuple.load(Tuple.dump(1))
+  end
+
+  should "dump times consistently" do
+    t = '2009-10-15 1:23:45 PM'
+    tuple = Tuple.dump(Time.parse(t))
+    100000.times do
+      assert_equal tuple, Tuple.dump(Time.parse(t))
+    end
+  end
+
+  should "sort tuples using binary" do
+    now   = Time.now.getgm
+    today = Date.parse(now.to_s)
+
+    tuples = [
+      [1, "foo"],
+      [1, true],
+      [2],
+      [1],
+      [nil],
+      [true],
+      [:foo, -1],
+      [:foo, -2**64],
+      [:foo,  2**64],
+      [1, "foo", 7, nil, false, true],
+      [1, "foo", 7, nil, false, false],
+      ["charles", "atlas"],
+      ["charles", "atlas", "shrugged"],
+      ["charles", "atlantic"],
+      ["charles", "atlas jr."],
+      ["charles", "atlas", "world's", "strongest", "man"],
+      ["charles", "atlas", 5],
+      [now, "foo"],
+      [now, "bar"],
+      [now - 24 * 60 * 60],
+      [today + 1],
+      [today - 1],
+      [today],
+    ]
+
+    expected = [
+      [nil],
+      [1],
+      [1, "foo"],
+      [1, "foo", 7, nil, false, false],
+      [1, "foo", 7, nil, false, true],
+      [1, true],
+      [2],
+      ["charles", "atlantic"],
+      ["charles", "atlas"],
+      ["charles", "atlas", 5],
+      ["charles", "atlas", "shrugged"],
+      ["charles", "atlas", "world's", "strongest", "man"],
+      ["charles", "atlas jr."],
+      [:foo, -18446744073709551616],
+      [:foo, -1],
+      [:foo, 18446744073709551616],
+      [today - 1],
+      [now - 24 * 60 * 60],
+      [today],
+      [now, "bar"],
+      [now, "foo"],
+      [today + 1],
+      [true]
+    ]
+    assert_equal expected, tuples.sort_by {|t| Tuple.dump(t)}
+
+    100.times do
+      assert_equal expected, tuples.shuffle.sort_by {|t| Tuple.dump(t)}
+    end
+  end 
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification 
+name: tuple
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Justin Balthrop
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-20 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: Fast, binary-sortable serialization for arrays of simple Ruby types.
+email: code@justinbalthrop.com
+executables: []
+
+extensions: 
+- ext/extconf.rb
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- README.rdoc
+- ext/extconf.rb
+- ext/tuple.c
+- test/test_helper.rb
+- test/tuple_test.rb
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/ninjudd/tuple
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- ext
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Tuple serialization functions.
+test_files: 
+- test/test_helper.rb
+- test/tuple_test.rb