ntable 0.1.1 → 0.1.2

data/History.rdoc

@@ -1,3 +1,13 @@
+=== 0.1.2 / 2012-09-09
+
+I took a long look at ntable's interface, and the usage patterns of my own personal projects that depended on it, and decided some simplification was needed.
+
+* INCOMPATIBLE CHANGE: Renamed the "index_to_label" and "label_to_index" methods on axis objects to "label" and "index", respectively.
+* INCOMPATIBLE CHANGE: Renamed the "axis", "index", and "name" methods on AxisInfo to "axis_object", "axis_index", and "axis_name", respectively.
+* Added "index", "label", and "size" methods to AxisInfo, delegating to the underlying axis object. This means AxisInfo is now effectively a proxy for the axis implementation, which should normally no longer need to be accessed.
+* INCOMPATIBLE CHANGE: Renamed the "axis_info" and "all_axis_info" methods of Structure to "axis" and "all_axes", respectively.
+* The "axis" and "all_axes" methods of Structure are now exposed on Table, so you should not need to access the structure too often.
+
 === 0.1.1 / 2012-09-07
 
 * The "preferred" construction methods are now module methods on ::NTable.

data/Version

@@ -1 +1 @@
-0.1.1
+0.1.2

data/lib/ntable.rb

@@ -58,7 +58,7 @@
 # such a table with 100 rows and two columns could be created like this:
 #
 #  table = NTable.structure(NTable::IndexedAxis.new(100)).
-#                 add(NTable::LabeledAxis(:name, :address)).
+#                 add(NTable::LabeledAxis.new(:name, :address)).
 #                 create
 #
 # You can then look up individual cells like this:
@@ -68,7 +68,7 @@
 # Axes can be given names as well:
 #
 #  table = NTable.structure(NTable::IndexedAxis.new(100), :row).
-#                 add(NTable::LabeledAxis(:name, :address), :col).
+#                 add(NTable::LabeledAxis.new(:name, :address), :col).
 #                 create
 #
 # Then you can specify the axes by name when you look up:

data/lib/ntable/axis.rb

@@ -49,15 +49,23 @@ module NTable
   class EmptyAxis
 
 
+    # Axis objects must implement an equality check.
+
     def eql?(obj_)
       obj_.is_a?(EmptyAxis)
     end
     alias_method :==, :eql?
 
+
+    # Axis objects must implement a hash
+
     def hash
       self.class.hash
     end
 
+
+    # Axis methods should implement display methods for debugging.
+
     def inspect
       "#<#{self.class}:0x#{object_id.to_s(16)}>"
     end
@@ -75,7 +83,7 @@ module NTable
     # Given a label object, return the corresponding 0-based integer index.
     # Returns nil if the label is not recognized.
 
-    def label_to_index(label_)
+    def index(label_)
       nil
     end
 
@@ -84,7 +92,7 @@ module NTable
     # Returns nil if the index is out of bounds (i.e. is less than 0 or
     # greater than or equal to size.)
 
-    def index_to_label(index_)
+    def label(index_)
       nil
     end
 
@@ -144,11 +152,11 @@ module NTable
     attr_reader :size
 
 
-    def label_to_index(label_)
+    def index(label_)
       @h[label_.to_s]
     end
 
-    def index_to_label(index_)
+    def label(index_)
       @a[index_]
     end
 
@@ -186,7 +194,7 @@ module NTable
     alias_method :==, :eql?
 
     def hash
-      @size.hash + @start.hash
+      @size.hash ^ @start.hash
     end
 
     def inspect
@@ -199,11 +207,11 @@ module NTable
     attr_reader :start
 
 
-    def label_to_index(label_)
+    def index(label_)
       label_ >= @start && label_ < @size + @start ? label_ - @start : nil
     end
 
-    def index_to_label(index_)
+    def label(index_)
       index_ >= 0 && index_ < @size ? index_ + @start : nil
     end
 
@@ -258,11 +266,11 @@ module NTable
     attr_reader :size
 
 
-    def label_to_index(label_)
+    def index(label_)
       @h[label_]
     end
 
-    def index_to_label(index_)
+    def label(index_)
       @a[index_]
     end
 

data/lib/ntable/structure.rb

@@ -61,39 +61,67 @@ module NTable
 
     # A data structure that provides information about a particular
     # axis/dimension in a Structure. It provides access to the axis
-    # itself, as well as the axis's name (if any) and 0-based index
+    # object, as well as the axis's name (if any) and 0-based index
     # into the list of axes. You should never need to create an
-    # AxisInfo yourself, but you can obtain one from Structure#axis_info.
+    # AxisInfo yourself, but you can obtain one from Structure#axis.
 
-    class AxisInfo  # :nodoc:
+    class AxisInfo
 
       def initialize(axis_, index_, name_, step_=nil)  # :nodoc:
-        @axis = axis_
-        @index = index_
-        @name = name_
+        @axis_object = axis_
+        @axis_index = index_
+        @axis_name = name_
         @step = step_
       end
 
-      # The axis object
-      attr_reader :axis
+
+      # The underlying axis implementation
+      attr_reader :axis_object
+
       # The 0-based index of this axis in the structure. i.e. the first,
-      # most major axis has index 0.
-      attr_reader :index
+      # most major axis has number 0.
+      attr_reader :axis_index
+
       # The name of this axis in the structure as a string, or nil for
       # no name.
-      attr_reader :name
+      attr_reader :axis_name
 
       attr_reader :step  # :nodoc:
 
 
+      # Given a label object, return the corresponding 0-based integer index.
+      # Returns nil if the label is not recognized.
+
+      def index(label_)
+        @axis_object.index(label_)
+      end
+
+
+      # Given a 0-based integer index, return the corresponding label object.
+      # Returns nil if the index is out of bounds (i.e. is less than 0 or
+      # greater than or equal to size.)
+
+      def label(index_)
+        @axis_object.label(index_)
+      end
+
+
+      # Return the number of rows along this axis.
+      # An empty axis will return 0.
+
+      def size
+        @axis_object.size
+      end
+
+
       def eql?(obj_)  # :nodoc:
-        obj_.is_a?(AxisInfo) && obj_.axis.eql?(@axis) && obj_.name.eql?(@name)
+        obj_.is_a?(AxisInfo) && @axis_object.eql?(obj_.axis_object) && @axis_name.eql?(obj_.axis_name)
       end
       alias_method :==, :eql?  # :nodoc:
 
 
       def _set_axis(axis_)  # :nodoc:
-        @axis = axis_
+        @axis_object = axis_
       end
 
       def _set_step(step_)  # :nodoc:
@@ -101,7 +129,7 @@ module NTable
       end
 
       def _dec_index  # :nodoc:
-        @index -= 1
+        @axis_index -= 1
       end
 
     end
@@ -132,8 +160,8 @@ module NTable
       # axis may be provided by name or index.
 
       def coord(axis_)
-        ainfo_ = @structure.axis_info(axis_)
-        ainfo_ ? _coords[ainfo_.index] : nil
+        ainfo_ = @structure.axis(axis_)
+        ainfo_ ? _coords[ainfo_.axis_index] : nil
       end
       alias_method :[], :coord
 
@@ -194,7 +222,7 @@ module NTable
       other_.instance_variable_get(:@indexes).each do |ai_|
         ai_ = ai_.dup
         @indexes << ai_
-        if (name_ = ai_.name)
+        if (name_ = ai_.axis_name)
           @names[name_] = ai_
         end
       end
@@ -207,7 +235,7 @@ module NTable
 
     def unlocked_copy
       copy_ = Structure.new
-      @indexes.each{ |ai_| copy_.add(ai_.axis, ai_.name) }
+      @indexes.each{ |ai_| copy_.add(ai_.axis_object, ai_.axis_name) }
       copy_
     end
 
@@ -239,7 +267,7 @@ module NTable
         if rhs_indexes_.size == @indexes.size
           rhs_indexes_.each_with_index do |rhs_ai_, i_|
             lhs_ai_ = @indexes[i_]
-            return false unless lhs_ai_.axis == rhs_ai_.axis && lhs_ai_.name == rhs_ai_.name
+            return false unless lhs_ai_.axis_object == rhs_ai_.axis_object && lhs_ai_.axis_name == rhs_ai_.axis_name
           end
           return true
         end
@@ -271,17 +299,17 @@ module NTable
 
     def remove(axis_)
       raise StructureStateError, "Structure locked" if @locked
-      ainfo_ = axis_info(axis_)
+      ainfo_ = axis(axis_)
       unless ainfo_
         raise UnknownAxisError, "Unknown axis: #{axis_.inspect}"
       end
-      index_ = ainfo_.index
-      @names.delete(ainfo_.name)
+      index_ = ainfo_.axis_index
+      @names.delete(ainfo_.axis_name)
       @indexes.delete_at(index_)
       @indexes[index_..-1].each{ |ai_| ai_._dec_index }
-      size_ = ainfo_.axis.size
+      size_ = ainfo_.size
       if size_ == 0
-        @size = @indexes.inject(1){ |s_, ai_| s_ * ai_.axis.size }
+        @size = @indexes.inject(1){ |s_, ai_| s_ * ai_.size }
       else
         @size /= size_
       end
@@ -299,15 +327,15 @@ module NTable
 
     def replace(axis_, naxis_=nil)
       raise StructureStateError, "Structure locked" if @locked
-      ainfo_ = axis_info(axis_)
+      ainfo_ = axis(axis_)
       unless ainfo_
         raise UnknownAxisError, "Unknown axis: #{axis_.inspect}"
       end
-      osize_ = ainfo_.axis.size
+      osize_ = ainfo_.size
       naxis_ ||= yield(ainfo_)
       ainfo_._set_axis(naxis_)
       if osize_ == 0
-        @size = @indexes.inject(1){ |size_, ai_| size_ * ai_.axis.size }
+        @size = @indexes.inject(1){ |size_, ai_| size_ * ai_.size }
       else
         @size = @size / osize_ * naxis_.size
       end
@@ -341,7 +369,7 @@ module NTable
     # Returns an array of AxisInfo objects representing all the axes
     # of this structure.
 
-    def all_axis_info
+    def all_axes
       @indexes.dup
     end
 
@@ -350,7 +378,7 @@ module NTable
     # must be specified by 0-based index or by name string. Returns nil
     # if there is no such axis.
 
-    def axis_info(axis_)
+    def axis(axis_)
       case axis_
       when ::Integer
         @indexes[axis_]
@@ -370,7 +398,7 @@ module NTable
         if @size > 0
           s_ = @size
           @indexes.each do |ainfo_|
-            s_ /= ainfo_.axis.size
+            s_ /= ainfo_.size
             ainfo_._set_step(s_)
           end
         end
@@ -436,8 +464,8 @@ module NTable
 
     def to_json_array
       @indexes.map do |ai_|
-        name_ = ai_.name
-        axis_ = ai_.axis
+        name_ = ai_.axis_name
+        axis_ = ai_.axis_object
         type_ = axis_.class.name
         if type_ =~ /^NTable::(\w+)Axis$/
           type_ = $1
@@ -499,11 +527,11 @@ module NTable
       names_ = {}
       size_ = 1
       @indexes.each do |ainfo_|
-        if axes_.include?(ainfo_.index) == bool_
-          nainfo_ = AxisInfo.new(ainfo_.axis, indexes_.size, ainfo_.name, ainfo_.step)
+        if axes_.include?(ainfo_.axis_index) == bool_
+          nainfo_ = AxisInfo.new(ainfo_.axis_object, indexes_.size, ainfo_.axis_name, ainfo_.step)
           indexes_ << nainfo_
-          names_[ainfo_.name] = nainfo_
-          size_ *= ainfo_.axis.size
+          names_[ainfo_.axis_name] = nainfo_
+          size_ *= ainfo_.size
         end
       end
       sub_.instance_variable_set(:@indexes, indexes_)
@@ -522,8 +550,8 @@ module NTable
       when ::Hash
         offset_ = 0
         arg_.each do |k_, v_|
-          if (ainfo_ = axis_info(k_))
-            index_ = ainfo_.axis.label_to_index(v_)
+          if (ainfo_ = axis(k_))
+            index_ = ainfo_.index(v_)
             return nil unless index_
             offset_ += ainfo_.step * index_
           else
@@ -535,7 +563,7 @@ module NTable
         offset_ = 0
         arg_.each_with_index do |v_, i_|
           if (ainfo_ = @indexes[i_])
-            index_ = ainfo_.axis.label_to_index(v_)
+            index_ = ainfo_.index(v_)
             return nil unless index_
             offset_ += ainfo_.step * index_
           else
@@ -556,16 +584,16 @@ module NTable
       case arg_
       when ::Hash
         arg_.each do |k_, v_|
-          if (ainfo_ = axis_info(k_))
-            val_ = ainfo_.axis.label_to_index(v_)
-            vec_[ainfo_.index] = val_ if val_
+          if (ainfo_ = axis(k_))
+            val_ = ainfo_.index(v_)
+            vec_[ainfo_.axis_index] = val_ if val_
           end
         end
         vec_
       when ::Array
         arg_.each_with_index do |v_, i_|
           if (ainfo_ = @indexes[i_])
-            val_ = ainfo_.axis.label_to_index(v_)
+            val_ = ainfo_.index(v_)
             vec_[i_] = val_ if val_
           end
         end
@@ -587,7 +615,7 @@ module NTable
 
     def _compute_coords_for_vector(vector_)  # :nodoc:
       vector_.map.with_index do |v_, i_|
-        @indexes[i_].axis.index_to_label(v_)
+        @indexes[i_].label(v_)
       end
     end
 
@@ -596,7 +624,7 @@ module NTable
       (vector_.size - 1).downto(-1) do |i_|
         return true if i_ < 0
         v_ = vector_[i_] + 1
-        if v_ >= @indexes[i_].axis.size
+        if v_ >= @indexes[i_].size
           vector_[i_] = 0
         else
           vector_[i_] = v_
@@ -612,7 +640,7 @@ module NTable
         return true if i_ < 0
         v_ = vector_[i_] - 1
         if v_ < 0
-          vector_[i_] = @indexes[i_].axis.size - 1
+          vector_[i_] = @indexes[i_].size - 1
         else
           vector_[i_] = v_
           break
@@ -627,7 +655,7 @@ module NTable
       @indexes.map do |ainfo_|
         i_ = offset_ / ainfo_.step
         offset_ -= ainfo_.step * i_
-        ainfo_.axis.index_to_label(i_)
+        ainfo_.label(i_)
       end
     end
 

data/lib/ntable/table.rb

@@ -161,6 +161,23 @@ module NTable
     end
 
 
+    # Returns the AxisInfo object representing the given axis. The axis
+    # must be specified by 0-based index or by name string. Returns nil
+    # if there is no such axis.
+
+    def axis(axis_)
+      @structure.axis(axis_)
+    end
+
+
+    # Returns an array of AxisInfo objects representing all the axes
+    # of the structure of this table.
+
+    def all_axes
+      @structure.all_axes
+    end
+
+
     # Return the parent of this table. A table with a parent shares the
     # parent's data, and cannot have its data modified directly. Instead,
     # if the parent table is modified, the changes are reflected in the
@@ -473,8 +490,8 @@ module NTable
       axes_ = axes_.flatten
       axis_indexes_ = []
       axes_.each do |a_|
-        if (ainfo_ = @structure.axis_info(a_))
-          axis_indexes_ << ainfo_.index
+        if (ainfo_ = @structure.axis(a_))
+          axis_indexes_ << ainfo_.axis_index
         else
           raise UnknownAxisError, "Unknown axis: #{a_.inspect}"
         end
@@ -523,10 +540,10 @@ module NTable
       offset_ = @offset
       select_set_ = {}
       hash_.each do |k_, v_|
-        if (ainfo_ = @structure.axis_info(k_))
-          aindex_ = ainfo_.index
+        if (ainfo_ = @structure.axis(k_))
+          aindex_ = ainfo_.axis_index
           unless select_set_.include?(aindex_)
-            lindex_ = ainfo_.axis.label_to_index(v_)
+            lindex_ = ainfo_.index(v_)
             if lindex_
               offset_ += ainfo_.step * lindex_
               select_set_[aindex_] = true
@@ -582,7 +599,7 @@ module NTable
     def _to_nested_obj(aidx_, vec_, opts_)  # :nodoc:
       exclude_ = opts_.include?(:exclude_value)
       exclude_value_ = opts_[:exclude_value] if exclude_
-      axis_ = @structure.axis_info(aidx_).axis
+      axis_ = @structure.axis(aidx_).axis_object
       result_ = IndexedAxis === axis_ ? [] : {}
       (0...axis_.size).map do |i_|
         vec_[aidx_] = i_
@@ -592,7 +609,7 @@ module NTable
           _to_nested_obj(aidx_ + 1, vec_, opts_)
         end
         if !exclude_ || !val_.eql?(exclude_value_)
-          result_[axis_.index_to_label(i_)] = val_
+          result_[axis_.label(i_)] = val_
         end
       end
       result_

data/test/tc_axes.rb

@@ -52,18 +52,18 @@ module NTable
 
       def test_labeled_axis_label_to_index
         axis_ = LabeledAxis.new([:one, :two])
-        assert_equal(0, axis_.label_to_index(:one))
-        assert_equal(1, axis_.label_to_index(:two))
-        assert_equal(0, axis_.label_to_index('one'))
-        assert_nil(axis_.label_to_index(:three))
+        assert_equal(0, axis_.index(:one))
+        assert_equal(1, axis_.index(:two))
+        assert_equal(0, axis_.index('one'))
+        assert_nil(axis_.index(:three))
       end
 
 
       def test_labeled_axis_index_to_label
         axis_ = LabeledAxis.new([:one, :two])
-        assert_equal('one', axis_.index_to_label(0))
-        assert_equal('two', axis_.index_to_label(1))
-        assert_nil(axis_.index_to_label(2))
+        assert_equal('one', axis_.label(0))
+        assert_equal('two', axis_.label(1))
+        assert_nil(axis_.label(2))
       end
 
 
@@ -90,18 +90,18 @@ module NTable
 
       def test_object_axis_label_to_index
         axis_ = ObjectAxis.new([:one, :two])
-        assert_equal(0, axis_.label_to_index(:one))
-        assert_equal(1, axis_.label_to_index(:two))
-        assert_nil(axis_.label_to_index('one'))
-        assert_nil(axis_.label_to_index(:three))
+        assert_equal(0, axis_.index(:one))
+        assert_equal(1, axis_.index(:two))
+        assert_nil(axis_.index('one'))
+        assert_nil(axis_.index(:three))
       end
 
 
       def test_object_axis_index_to_label
         axis_ = ObjectAxis.new([:one, :two])
-        assert_equal(:one, axis_.index_to_label(0))
-        assert_equal(:two, axis_.index_to_label(1))
-        assert_nil(axis_.index_to_label(2))
+        assert_equal(:one, axis_.label(0))
+        assert_equal(:two, axis_.label(1))
+        assert_nil(axis_.label(2))
       end
 
 
@@ -128,17 +128,17 @@ module NTable
 
       def test_indexed_axis_label_to_index
         axis_ = IndexedAxis.new(2, 4)
-        assert_equal(0, axis_.label_to_index(4))
-        assert_equal(1, axis_.label_to_index(5))
-        assert_nil(axis_.label_to_index(3))
+        assert_equal(0, axis_.index(4))
+        assert_equal(1, axis_.index(5))
+        assert_nil(axis_.index(3))
       end
 
 
       def test_indexed_axis_index_to_label
         axis_ = IndexedAxis.new(2, 4)
-        assert_equal(4, axis_.index_to_label(0))
-        assert_equal(5, axis_.index_to_label(1))
-        assert_nil(axis_.index_to_label(2))
+        assert_equal(4, axis_.label(0))
+        assert_equal(5, axis_.label(1))
+        assert_nil(axis_.label(2))
       end
 
 

data/test/tc_structure.rb

@@ -67,10 +67,10 @@ module NTable
       def test_add_single_axis
         s_ = Structure.new
         s_.add(@labeled1, :first)
-        assert_equal(@labeled1, s_.axis_info(0).axis)
-        assert_equal(@labeled1, s_.axis_info(:first).axis)
-        assert_equal(0, s_.axis_info(:first).index)
-        assert_equal('first', s_.axis_info(0).name)
+        assert_equal(@labeled1, s_.axis(0).axis_object)
+        assert_equal(@labeled1, s_.axis(:first).axis_object)
+        assert_equal(0, s_.axis(:first).axis_index)
+        assert_equal('first', s_.axis(0).axis_name)
       end
 
 
@@ -79,16 +79,16 @@ module NTable
         s_.add(@labeled1, :first)
         s_.add(@indexed1, :second)
         s_.add(@indexed1)
-        assert_equal(@labeled1, s_.axis_info(0).axis)
-        assert_equal(@labeled1, s_.axis_info(:first).axis)
-        assert_equal(0, s_.axis_info(:first).index)
-        assert_equal('first', s_.axis_info(0).name)
-        assert_equal(@indexed1, s_.axis_info(1).axis)
-        assert_equal(@indexed1, s_.axis_info(:second).axis)
-        assert_equal(1, s_.axis_info(:second).index)
-        assert_equal('second', s_.axis_info(1).name)
-        assert_equal(@indexed1, s_.axis_info(2).axis)
-        assert_nil(s_.axis_info(2).name)
+        assert_equal(@labeled1, s_.axis(0).axis_object)
+        assert_equal(@labeled1, s_.axis(:first).axis_object)
+        assert_equal(0, s_.axis(:first).axis_index)
+        assert_equal('first', s_.axis(0).axis_name)
+        assert_equal(@indexed1, s_.axis(1).axis_object)
+        assert_equal(@indexed1, s_.axis(:second).axis_object)
+        assert_equal(1, s_.axis(:second).axis_index)
+        assert_equal('second', s_.axis(1).axis_name)
+        assert_equal(@indexed1, s_.axis(2).axis_object)
+        assert_nil(s_.axis(2).axis_name)
       end
 
 
@@ -98,12 +98,12 @@ module NTable
         s_.add(@indexed1, :second)
         s_.remove(:first)
         assert_equal(1, s_.dim)
-        assert_equal(@indexed1, s_.axis_info(0).axis)
-        assert_equal(@indexed1, s_.axis_info(:second).axis)
-        assert_equal(0, s_.axis_info(:second).index)
-        assert_equal('second', s_.axis_info(0).name)
-        assert_nil(s_.axis_info(1))
-        assert_nil(s_.axis_info(:first))
+        assert_equal(@indexed1, s_.axis(0).axis_object)
+        assert_equal(@indexed1, s_.axis(:second).axis_object)
+        assert_equal(0, s_.axis(:second).axis_index)
+        assert_equal('second', s_.axis(0).axis_name)
+        assert_nil(s_.axis(1))
+        assert_nil(s_.axis(:first))
       end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ntable
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-07 00:00:00.000000000 Z
+date: 2012-09-10 00:00:00.000000000 Z
 dependencies: []
 description: NTable provides a convenient data structure for storing n-dimensional
   tabular data. It works with zero-dimensional scalar values, arrays, tables, and