type_array 0.1

data/.gitignore

@@ -0,0 +1,19 @@
+.libs/*
+.rbx/*
+*.rbc
+*.lo
+*.la
+*.lai
+*.dylib.dSYM
+*.dylib
+*.o
+*.a
+*.log
+tmp/*
+true/*
+*.bundle
+*.gem
+doc/*
+.DS_Store
+pkg
+ext/type_array/Makefile

data/.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+rvm:
+  - rbx-18mode
+  - rbx-19mode
+  - ree
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ruby-head
+script: "bundle exec rake"
+gemfile:
+  - Gemfile
+notifications:
+  recipients:
+    - lourens@methodmissing.com
+branches:
+  only:
+    - master

data/CHANGELOG.rdoc

@@ -0,0 +1,4 @@
+= Changelog
+
+== 0.1.0 (July 11th, 2012)
+* initial release

data/Gemfile

@@ -0,0 +1,5 @@
+source :rubygems
+
+gemspec
+
+gem 'rake'

data/Gemfile.lock

@@ -0,0 +1,18 @@
+PATH
+  remote: .
+  specs:
+    binary_data (0.1)
+
+GEM
+  specs:
+    rake (0.9.2.2)
+    rake-compiler (0.8.0)
+      rake
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  rake-compiler (~> 0.8.0)
+  binary_data!

data/README.rdoc

@@ -0,0 +1,140 @@
+= TypeArray - Ruby implementation of the ECMAScript spec ( http://wiki.ecmascript.org/doku.php?id=strawman:typed_arrays ) {<img src="https://secure.travis-ci.org/methodmissing/type_array.png" alt="Build Status" />}[http://travis-ci.org/methodmissing/type_array]
+
+(c) 2012 Lourens Naudé (methodmissing)
+
+  http://github.com/methodmissing/type_array
+
+This library provides portable, high performance and memory-safe access to native-typed binary data. It defines a generic fixed length buffer type as well as accessor types (views) for accessing data stored within the buffer.
+
+Where binary data has needed to be manipulated, it is often stored as a String or Array. Both of these methods are slow and error-prone. Several protocol implementations would benefit from being able to read and write binary data directly to it's native form.
+
+Supported numeric types :
+
+* an unsigned-integer: one of uint8, uint16, uint32
+* a signed-integer: one of int8, int16, int32
+* a floating-point: one of float32 or float64
+
+There's a few different kinds of typed arrays defined :
+
+* Int8Array - 8-bit 2's complement signed integer
+* UInt8Array - 8-bit unsigned integer
+* Int16Array - 16-bit 2's complement signed integer
+* UInt16Array - 16-bit unsigned integer
+* Int32Array - 32-bit 2's complement signed integer
+* Uint32Array - 32-bit unsigned integer
+* Float32Array - 32-bit IEEE floating point
+* Float64Array - 64-bit IEEE floating point
+
+== Type Conversion
+
+    Type         Size    Description                             Equivalent C Type    Ruby Type
+    --------------------------------------------------------------------------------------------------
+    Int8Array     1       8-bit 2's complement signed integer     signed char          Fixnum
+    Uint8Array    1       8-bit unsigned integer                  unsigned char        Fixnum
+    Int16Array    2       16-bit 2's complement signed integer    short                Fixnum
+    Uint16Array   2       16-bit unsigned integer                 unsigned short       Fixnum
+    Int32Array    4       32-bit 2's complement signed integer    int                  Fixnum / Bignum
+    Uint32Array   4       32-bit unsigned integer                 unsigned int         Fixnum / Bignum
+    Float32Array  4       32-bit IEEE floating point              float                Float
+    Float64Array  8       64-bit IEEE floating point              double               Float
+
+== Array Buffers
+
+An opaque buffer with an explicit and fixed length. ArrayBuffer contents cannot be accessed directly - there's no Ruby API exposed to manipulate it.
+
+    buf = ArrayBuffer.new(8)         =>  ArrayBuffer
+    buf.byte_length                  =>  8
+
+    buf = ArrayBuffer.new("buffer")  =>  ArrayBuffer
+    buf.byte_length                  =>  6
+    buf.to_s                         =>  "buffer"
+
+== Type Arrays
+
+A group of types are used to create views of the ArrayBuffer. For example, to access the buffer as an array of 32-bit signed integers, an Int32Array would be created that refers to the ArrayBuffer.
+
+A number of types are introduced that describe how to interpret the bytes in an ArrayBuffer. For example, an Int32Array views the bytes in an ArrayBuffer (or a subregion of an ArrayBuffer) as 32-bit signed integers. Elements of the array are accessible by getting or setting their index.
+
+    buf = ArrayBuffer.new("buffer")    =>  ArrayBuffer
+    ary = Int32Array.new(buf)          =>  Int32Array
+    ary.to_s                           =>  "buffer"
+
+    ary = Int32Array.new("01234567")   =>  Int32Array
+    ary[1] = 23                        =>  nil
+    ary[1]                             =>  23
+
+    buf = ArrayBuffer.new(100)         =>  ArrayBuffer
+
+    ary = Int32Array.new(buf, 20)      =>  Int32Array
+    ary.length                         =>  20
+    ary.byte_length                    =>  80
+    ary.byte_offset                    =>  20
+
+    ary = Int32Array.new(buf, 0, 20)   =>  Int32Array
+    ary.length                         =>  20
+    ary.byte_length                    =>  80
+    ary.byte_offset                    =>  0
+
+    ary = Int32Array.new(buf, 20, 20)  =>  Int32Array
+    ary.length                         =>  20
+    ary.byte_length                    =>  80
+    ary.byte_offset                    =>  20
+
+    ary = Int32Array.new("01234567")   =>  Int32Array
+    ary.byte_length                    =>  8
+    ary.to_s                           =>  "01234567"
+
+    ary = Int32Array.new(100)          =>  Int32Array
+    ary.length                         =>  100
+    ary.byte_length                    =>  400
+
+== Data Views
+
+Multiple views can exist for the same ArrayBuffer, allowing for complex data structures to be built up, albeit with some difficulty. A DataView type is introduced which allows arbitrary indexed reads and writes of basic types from the bytes in the underlying ArrayBuffer. The goal is to allow as close to the native byte access as possible with very few performance penalties, while still retaining safety.
+
+    buf = ArrayBuffer.new(100)   =>  ArrayBuffer
+    view = DataView.new(buf)     =>  DataView
+    view.set_float64(2, 77.643)  =>  nil
+    view.get_float64(2)          =>  758
+
+    buf = ArrayBuffer.new(100)  => ArrayBuffer
+    view = DataView.new(buf)    =>  DataView
+    view.set_uint32(2, 758)     =>  nil
+    view.get_uint32(2)          =>  758
+
+    buf = ArrayBuffer.new(100)  => ArrayBuffer
+    view = DataView.new(buf)    =>  DataView
+    view.set_int16(2, 20)       =>  nil
+    view.get_int16(2)           =>  20
+
+== Requirements
+
+* Known to work well on Linux, BSD variants and Mac OS X (not tested on Windows)
+* A C compiler
+* Ruby MRI 1.8 or 1.9, Rubinius or JRuby (versions 1.6 and up, C API is deprecated though)
+
+== Installation
+
+Rubygems installation
+
+    gem install type_array
+
+Building from source
+
+    git clone git@github.com:methodmissing/type_array.git
+    rake
+
+Running tests
+
+    rake test
+
+== Todo
+
+* Support Marshal dump / load
+* Low level API for math operations on array elements without creating any Ruby objects
+* Support structs / records
+* Handle edges where coercion to and from Bignum is more appropriate
+
+== Contact, feedback and bugs
+
+This project is still work in progress. Please log bugs and suggestions at https://github.com/methodmissing/type_array/issues

data/Rakefile

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+require 'rubygems' unless defined?(Gem)
+require 'rake' unless defined?(Rake)
+
+# Prefer compiled Rubinius bytecode in .rbx/
+ENV["RBXOPT"] = "-Xrbc.db"
+
+require 'rake/extensiontask'
+require 'rake/testtask'
+
+begin
+require 'rdoc/task'
+rescue LoadError # fallback to older 1.8.7 rubies
+require 'rake/rdoctask'
+end
+
+gemspec = eval(IO.read('type_array.gemspec'))
+
+Gem::PackageTask.new(gemspec) do |pkg|
+end
+
+Rake::ExtensionTask.new('type_array', gemspec) do |ext|
+  ext.name = 'type_array_ext'
+  ext.ext_dir = 'ext/type_array'
+
+  CLEAN.include 'lib/**/type_array_ext.*'
+end
+
+desc 'Run TypeArray tests'
+Rake::TestTask.new(:test) do |t|
+  t.test_files = Dir.glob("test/**/test_*.rb")
+  t.verbose = true
+  t.warning = true
+end
+
+Rake::RDocTask.new do |rd|
+  files = FileList["README.rdoc", "ext/type_array/*.c"]
+  rd.title = "TypeArray - Ruby implementation of the ECMAScript spec"
+  rd.main = "README.rdoc"
+  rd.rdoc_dir = "doc"
+  rd.options << "--promiscuous"
+  rd.rdoc_files.include(files)
+end
+
+task :test => :compile
+task :default => :test

data/ext/type_array/array_buffer.c

@@ -0,0 +1,183 @@
+#include "type_array_ext.h"
+
+/*
+ * :nodoc:
+ *  An Array Buffer implementation with a simple query API for it's chunk of managed memory. The buffer is fixed and
+ *  cannot be resized. Data View and Type Array instances manipulate the buffer directly (this may change), but none
+ *  of that's exposed through a Ruby API.
+ *
+*/
+
+VALUE rb_cArrayBuffer;
+
+/*
+ * :nodoc:
+ *  GC free callback
+ *
+*/
+static void rb_free_array_buffer(void *ptr)
+{
+    rb_array_buffer_t *buf = (rb_array_buffer_t *)ptr;
+#ifdef TYPE_ARRAY_DEBUG
+    printf(">> rb_free_array_buffer %p\n", ptr);
+#endif
+    if (buf) {
+        if (buf->buf) xfree(buf->buf);
+        xfree(buf);
+        buf = NULL;
+    }
+#ifdef TYPE_ARRAY_DEBUG
+    printf("<< rb_free_array_buffer %p\n", ptr);
+#endif
+}
+
+/*
+ * :nodoc:
+ *  Utility function to allocate a new ArrayBuffer instance of given length. An optional pointer to an existing chunk
+ *  of memory may be passed, which becomes the buffer contents. This is useful for reading raw binary data from
+ *  standard I/O or sockets as binary strings.
+ *
+*/
+VALUE rb_alloc_array_buffer(unsigned long length, void *data)
+{
+    VALUE buffer;
+    rb_array_buffer_t *buf = NULL;
+    if (length == 0) rb_raise(rb_eRangeError, "ArrayBuffer is not a small enough positive integer");
+    buffer = Data_Make_Struct(rb_cArrayBuffer, rb_array_buffer_t, 0, rb_free_array_buffer, buf);
+    buf->length = length;
+    buf->buf = xcalloc(buf->length, 1);
+    if (!buf->buf) rb_raise(rb_eRangeError, "Unable to allocate ArrayBuffer");
+    if (data) memmove(buf->buf, data, length);
+    rb_obj_call_init(buffer, 0, NULL);
+    rb_obj_freeze(buffer);
+    return buffer;
+}
+
+/*
+ * :nodoc:
+ *  Utility function to create a new ArrayBuffer instance from a begin..end byte range
+ *
+*/
+static VALUE rb_copy_array_buffer(rb_array_buffer_t *source, long begin, long end)
+{
+    long length;
+    void *data;
+    length = (end - begin);
+    if (length < 0) length = 0;
+    data = source + begin;
+    return rb_alloc_array_buffer(length, data);
+}
+
+/*
+ *  call-seq:
+ *     ArrayBuffer.new(8)          =>  ArrayBuffer
+ *     ArrayBuffer.new("buffer")   =>  ArrayBuffer
+ *
+ *  Creates a new ArrayBuffer instance. Both length and data (String) constructors are supported.
+ *
+ * === Examples
+ *     buf = ArrayBuffer.new(8)         =>  ArrayBuffer
+ *     buf.byte_length                  =>  8
+ *
+ *     buf = ArrayBuffer.new("buffer")  =>  ArrayBuffer
+ *     buf.byte_length                  =>  6
+ *     buf.to_s                         =>  "buffer"
+ *
+*/
+static VALUE rb_array_buffer_s_new(VALUE klass, VALUE obj)
+{
+    VALUE buffer;
+    if (FIXNUM_P(obj)) {
+        buffer = rb_alloc_array_buffer(FIX2ULONG(obj), NULL);
+    } else if (rb_type(obj) == T_STRING) {
+        ArrayBufferEncode(obj);
+        buffer = rb_alloc_array_buffer((unsigned long)RSTRING_LEN(obj), (void *)RSTRING_PTR(obj));
+    } else {
+        rb_raise(rb_eTypeError, "ArrayBuffer constructor %s not supported.", RSTRING_PTR(rb_obj_as_string(obj)));
+    }
+    return buffer;
+}
+
+/*
+ *  call-seq:
+ *     buf.byte_length          =>  Fixnum
+ *
+ *  Returns the size of the buffer.
+ *
+ * === Examples
+ *     buf = ArrayBuffer.new(8)         =>  ArrayBuffer
+ *     buf.byte_length                  =>  8
+ *
+*/
+static VALUE rb_array_buffer_byte_length(VALUE obj)
+{
+    GetArrayBuffer(obj);
+    return ULONG2NUM(buf->length);   
+}
+
+/*
+ *  call-seq:
+ *     buf.slice(1)         =>  ArrayBuffer
+ *
+ *  Returns a new ArrayBuffer instance with a slice (copy) of a range of memory managed by the source buffer. 
+ *
+ * === Examples
+ *     buf = ArrayBuffer.new(8)         =>  ArrayBuffer
+ *     buf.slice(2)                     =>  ArrayBuffer
+ *     buf.slice(4,6)                   =>  ArrayBuffer
+ *
+*/
+static VALUE rb_array_buffer_slice(int argc, VALUE *argv, VALUE obj)
+{
+    VALUE buffer, begin, end;
+    long b = 0;
+    long e = 0;
+    GetArrayBuffer(obj);
+    rb_scan_args(argc, argv, "11", &begin, &end);
+    Check_Type(begin, T_FIXNUM);
+    b = FIX2LONG(begin);
+    if (NIL_P(end)) {
+        e = buf->length;
+    } else {
+        Check_Type(end, T_FIXNUM);
+        e = FIX2LONG(end);
+    }
+    if (b < 0) b = buf->length - abs(b);
+    if (e < 0) e = buf->length - abs(e);
+
+    if (e > buf->length) rb_raise(rb_eRangeError, "Offset out of range.");
+    buffer = rb_copy_array_buffer(buf, b, e);
+    return buffer;
+}
+
+/*
+ *  call-seq:
+ *     buf.to_s          =>  String
+ *
+ *  Returns a String (binary) representation of the buffer.
+ *
+ * === Examples
+ *     buf = ArrayBuffer.new("buffer")  =>  ArrayBuffer
+ *     buf.byte_length                  =>  6
+ *     buf.to_s                         =>  "buffer"
+ *
+*/
+VALUE rb_array_buffer_to_s(VALUE obj)
+{
+    VALUE str;
+    GetArrayBuffer(obj);
+    str = rb_str_new((const char*)buf->buf, buf->length);
+    ArrayBufferEncode(str);
+    return rb_obj_freeze(str);
+}
+
+void _init_array_buffer()
+{
+    rb_cArrayBuffer = rb_define_class("ArrayBuffer", rb_cObject);
+
+    rb_define_singleton_method(rb_cArrayBuffer, "new", rb_array_buffer_s_new, 1);
+
+    rb_define_method(rb_cArrayBuffer, "byte_length", rb_array_buffer_byte_length, 0);
+    rb_define_method(rb_cArrayBuffer, "slice", rb_array_buffer_slice, -1);
+    rb_define_method(rb_cArrayBuffer, "to_s", rb_array_buffer_to_s, 0);
+}

data/ext/type_array/array_buffer.h

@@ -0,0 +1,19 @@
+#ifndef ARRAY_BUFFER_H
+#define ARRAY_BUFFER_H
+
+typedef struct {
+    unsigned long length;
+    void *buf;
+} rb_array_buffer_t;
+
+#define GetArrayBuffer(obj) \
+    rb_array_buffer_t *buf = NULL; \
+    Data_Get_Struct(obj, rb_array_buffer_t, buf); \
+    if (!buf) rb_raise(rb_eTypeError, "uninitialized ArrayBuffer!");
+
+VALUE rb_alloc_array_buffer(unsigned long length, void *data);
+VALUE rb_array_buffer_to_s(VALUE obj);
+
+void _init_array_buffer();
+
+#endif