flex_array 0.2.0 → 0.3.0

data/lib/flex_array/flex_array_forever.rb

@@ -0,0 +1,18 @@
+#* flex_array_forever.rb - Forever looping support for the flexible array class.
+class FlexArray
+  #A helper class that encapsulates the idea of looping without end!
+  class ForEver
+    #Do something until false == true ;-)
+    def times(&block)
+      loop {block.call}
+    end
+
+    #Convert an eternity into an integer. ;-)
+    def to_i
+      nil
+    end
+  end
+
+  #Create a forever constant for use where infinite looping is needed.
+  FOREVER = ForEver.new
+end

data/lib/flex_array/flex_array_index.rb

@@ -2,20 +2,20 @@
 class FlexArray
   #Retrieve the selected data from the \FlexArray.
   #<br>Parameters
-  #* indexes - An array with as many entries as the flexible array has 
+  #* indexes - An array with as many entries as the flexible array has
   #  dimensions. These entries may be an integer that is in the bounds of
   #  the range limit of that dimension, or it can be a range where the start
-  #  and end of the range are in the bounds of the range limit of that 
+  #  and end of the range are in the bounds of the range limit of that
   #  dimension, or it can be the symbol :all for all of the possible values
   #  of that dimension.
   #<br>Returns
   #* The data selected by the index or an array of data if the index selects
-  #  more than one cell.  
-  #<br>Note 
+  #  more than one cell.
+  #<br>Note
   #* If the indexes parameter equals a single :all this maps to all
   #  elements of the array, regardless of its dimensionality.
   def [](*indexes)
-    validate_all_or_index_count(indexes)
+    validate_index_count(indexes)
     result = []
     process_indexes(indexes) {|_index, posn| result << @array_data[posn]}
     result.length == 1 ? result[0] : result
@@ -23,20 +23,22 @@ class FlexArray
 
   #Store the value data into the \FlexArray.
   #<br>Parameters
-  #* indexes - An array with as many entries as the flexible array has 
+  #* indexes - An array with as many entries as the flexible array has
   #  dimensions. These entries may be an integer that is in the bounds of
   #  the range limit of that dimension, or it can be a range where the start
-  #  and end of the range are in the bounds of the range limit of that 
+  #  and end of the range are in the bounds of the range limit of that
   #  dimension, or it can be the symbol :all for all of the possible values
-  #  of that dimension. 
+  #  of that dimension.
   #* value - A value to be stored in the selected array entries.
   #<br>Returns
   #* The value stored in the array.
-  #<br>Note 
+  #<br>Note
   #* If the indexes parameter equals a single :all this maps to all
   #  elements of the array, regardless of its dimensionality.
   def []=(*indexes, value)
-    validate_all_or_index_count(indexes)
-    process_indexes(indexes) {|_index, posn| @array_data[posn] = value}
+    validate_index_count(indexes)
+    source = value.in_array.cycle
+    process_indexes(indexes) {|_index, posn| @array_data[posn] = source.next}
+    value
   end
 end

data/lib/flex_array/flex_array_new.rb

@@ -2,34 +2,26 @@
 class FlexArray
   #Construct a flexible array object.
   #<br>Parameters
-  #* array_specs - The specification of the flex array subscript limits. 
-  #  These can either be integers, in which case the limits are 0...n or 
-  #  they can be ranges of integers, in which case the limits are those 
-  #  of the range, or they can be an array of integers and/or ranges of 
+  #* array_specs - The specification of the flex array subscript limits.
+  #  These can either be integers, in which case the limits are 0...n or
+  #  they can be ranges of integers, in which case the limits are those
+  #  of the range, or they can be an array of integers and/or ranges of
   #  integers to represent arrays of more than one dimension.
   #* default - The optional default value. Defaults to nil.
   #* init_block - An optional initialization block. The return values from this
   #  block are used to initialize the array. This overrides the default value.
   #<br>Block Arguments
-  #* index - An array with one element per dimension with the fully qualified 
+  #* index - An array with one element per dimension with the fully qualified
   #  index of the element being accessed. Note that the same array is passed
   #  in each time the block is called, so, if this parameter is to stored
   #  anywhere, it's best that it be cloned or duplicated first.
   def initialize(array_specs, default=nil, &init_block)
-    @array_specs, @count, @transposed = [], 1, false
-
-    #Parse the array limits.
-    array_specs.in_array.reverse_each do |spec|
-      @array_specs.insert(0, spec.to_spec_component(@count))
-      @count *= @array_specs[0].span
-    end
-    
-    #Cache the dimensionality of the flex array.
-    @dimensions = @array_specs.length
+    @array_specs = SpecArray.new(array_specs.in_array)
+    @transposed = false
 
     #Allocate the data for the array.
-    @array_data = Array.new(@count, default)
-    
+    @array_data = Array.new(@array_specs.spec_count, default)
+
     #Set up the array with the optional init_block.
     if init_block
       process_all {|index, posn| @array_data[posn] = init_block.call(index)}
@@ -39,6 +31,10 @@ class FlexArray
   alias_method :shallow_dup, :dup
 
   #Create a duplicate of this array.
+  #<br>Warning
+  #* The rdoc tool messes this up. shallow_dup is NOT an alias for this
+  #  dup, but rather the original system implementation of dup. This dup,
+  #  overrides the default dup and calls shallow_dup as part of its processing.
   def dup
     other = self.shallow_dup
     other.array_specs = @array_specs.dup
@@ -48,12 +44,12 @@ class FlexArray
 
   #Construct a \FlexArray using other as a template or data source.
   #<br>Parameters:
-  #* array_specs - The specification of the flex array subscript limits. 
-  #  These can either be integers, in which case the limits are 0...n or 
-  #  they can be ranges of integers, in which case the limits are those 
-  #  of the range, or they can be an array of integers and/or ranges of 
+  #* array_specs - The specification of the flex array subscript limits.
+  #  These can either be integers, in which case the limits are 0...n or
+  #  they can be ranges of integers, in which case the limits are those
+  #  of the range, or they can be an array of integers and/or ranges of
   #  integers to represent arrays of more than one dimension.
-  #* other - The array or flex array that is the source of the data. 
+  #* other - The array or flex array that is the source of the data.
   #<br>Note:
   #* To make a copy of a flex array, use dup instead.
   def self.new_from(array_specs, other)
@@ -61,27 +57,27 @@ class FlexArray
     FlexArray.new(array_specs) {iterator.next}
   end
 
-  #Construct a \FlexArray using a all or a portion of portion of another 
+  #Construct a \FlexArray using a all or a portion of portion of another
   #\FlexArray as a data source.
   #<br>Parameters
-  #* array_specs - The specification of the flex array subscript limits. 
-  #  These can either be integers, in which case the limits are 0...n or 
-  #  they can be ranges of integers, in which case the limits are those 
-  #  of the range, or they can be an array of integers and/or ranges of 
+  #* array_specs - The specification of the flex array subscript limits.
+  #  These can either be integers, in which case the limits are 0...n or
+  #  they can be ranges of integers, in which case the limits are those
+  #  of the range, or they can be an array of integers and/or ranges of
   #  integers to represent arrays of more than one dimension.
-  #* other - The flex array source of the data used to build this flex 
-  #  array. If no limits or other_indexes are specified, the limits of the 
+  #* other - The flex array source of the data used to build this flex
+  #  array. If no limits or other_indexes are specified, the limits of the
   #  other array are used instead.
-  #* selection - The indexes of the required sub-set of data to use 
+  #* selection - The indexes of the required sub-set of data to use
   #  in setting up the new array.
   #<br>Notes:
-  #* If the entire source array is to be used, use new_from instead.  
+  #* If the entire source array is to be used, use new_from instead.
   #* To make a copy of a flex array, use dup instead.
   def self.new_from_selection(array_specs, other, selection)
-    iterator = other.cycle(selection)
+    iterator = other.select_cycle(selection)
     FlexArray.new(array_specs) {iterator.next}
   end
-  
+
   #Construct a \FlexArray as a duplicate of a source array or flex array.
   #<br>Parameters
   #* other - the array or flex array that is the source.
@@ -93,6 +89,6 @@ class FlexArray
     result = FlexArray.new(0)
     result.array_specs = other.array_specs.dup
     result.array_data = other.array_data
-    result.update_count_and_dimensions
+    result
   end
 end

data/lib/flex_array/flex_array_process.rb

@@ -4,27 +4,27 @@ class FlexArray
   #Process a \FlexArray index array. This is the heart of the \FlexArray
   #indexing process.
   #<br>Parameters
-  #* indexes - An array with as many entries as the flexible array has 
+  #* indexes - An array with as many entries as the flexible array has
   #  dimensions. See [] for more details. Note that since indexes is NOT
   #  a splat parameter, it must be passed as an array explicitly. If passed
   #  in as [:all] all elements of the array are processed.
   #* block - a block to be called for each value selected by this process.
   #<br>Block Arguments
-  #* current - An array with one element per dimension with the fully qualified 
-  #  index of the element being accessed. 
+  #* current - An array with one element per dimension with the fully qualified
+  #  index of the element being accessed.
   #* posn - The position of the element being accessed in the data array.
   def process_indexes(indexes, &block)
-    current = Array.new(@dimensions, 0)
-    
+    current = Array.new(dimensions, 0)
+
     if indexes == [:all]
       process_all_worker(0, 0, current, &block)
     else
       specs = @array_specs.each
-      
+
       checked = indexes.collect do |index|
         index.to_index_range(specs.next)
       end
-    
+
       process_indexes_worker(0, 0, checked, current, &block)
     end
   end
@@ -32,71 +32,76 @@ class FlexArray
   #The worker bee for process_indexes.
   #<br>Parameters
   #* depth - The index of the dimension being processed.
-  #* posn - The partially computed position of the element being accessed 
+  #* posn - The partially computed position of the element being accessed
   #  in the data array.
-  #* indexes - An array of array indexes. See the method [] for details on 
+  #* indexes - An array of array indexes. See the method [] for details on
   #  what sorts of things these can be.
   #* current - The partial fully qualified index of the element being accessed.
   #* block - A block to be called for each value selected by this process.
   #<br>Block Arguments
-  #* current - An array with one element per dimension with the fully qualified 
-  #  index of the element being accessed. 
+  #* current - An array with one element per dimension with the fully qualified
+  #  index of the element being accessed.
   #* posn - The position of the element being accessed in the data array.
   #<br>Note
   #This is a recursive function. The recursion runs for index in 0..#dimensions
+  #<br>Endemic Code Smells
+  # :reek:LongParameterList
   def process_indexes_worker(depth, posn, indexes, current, &block)
-    if depth == @dimensions
-      block.call(current, posn)
+    if depth == dimensions                 #Is there more work to do?
+      block.call(current, posn)            #Index ready, call the block.
     else
-      spec   = @array_specs[depth]
-      range  = indexes[depth]
-      posn  += spec.index_step(range.min)
-      stride = spec.stride
-      
-      range.each do |index|
-        current[depth] = index
-        process_indexes_worker(depth+1, posn, indexes, current, &block)
-        posn += stride
+      spec = @array_specs[depth]           #Get the current specification.
+      min, stride = spec.min, spec.stride  #Extract the relevant info.
+
+      indexes[depth].each do |index|       #Iterate over the range.
+        current[depth] = index             #Update the current index.
+        #Process the next component in the array index.
+        process_indexes_worker(depth+1,
+                               posn + (index-min) * stride,
+                               indexes,
+                               current,
+                               &block)
       end
     end
   end
-  
+
   #Special case where all of the array is being processed.
   #<br>Parameters
   #* block - A block to be called for each value selected by this process.
   #<br>Block Arguments
-  #* current - An array with one element per dimension with the fully qualified 
-  #  index of the element being accessed. 
+  #* current - An array with one element per dimension with the fully qualified
+  #  index of the element being accessed.
   #* posn - The position of the element being accessed in the data array.
   def process_all(&block)
-    current = Array.new(@dimensions, 0)
+    current = Array.new(dimensions, 0)
     process_all_worker(0, 0, current, &block)
   end
-  
+
   #The worker bee for process_all.
   #<br>Parameters
   #* depth - The index of the dimension being processed.
-  #* posn - The partially computed position of the element being accessed 
+  #* posn - The partially computed position of the element being accessed
   #  in the data array.
   #* current - The partial fully qualified index of the element being accessed.
   #* block - A block to be called for each value selected by this process.
   #<br>Block Arguments
-  #* current - An array with one element per dimension with the fully qualified 
-  #  index of the element being accessed. 
+  #* current - An array with one element per dimension with the fully qualified
+  #  index of the element being accessed.
   #* posn - The position of the element being accessed in the data array.
   #<br>Note
   #This is a recursive function. The recursion runs for index in 0..#dimensions
   def process_all_worker(depth, posn, current, &block)
-    if depth == @dimensions
-      block.call(current, posn)
+    if depth == dimensions                 #Is there more work to do?
+      block.call(current, posn)            #Index ready, call the block.
     else
-      spec   = @array_specs[depth]
+      spec = @array_specs[depth]           #Get the current specification.
       stride = spec.stride
-    
-      spec.each do |index|
-        current[depth] = index
+
+      spec.each do |index|                 #Iterate over the range.
+        current[depth] = index             #Update the current index.
+        #Process the next component in the array specification.
         process_all_worker(depth+1, posn, current, &block)
-        posn += stride
+        posn += stride                     #Step to the next position.
       end
     end
   end

data/lib/flex_array/flex_array_reshape.rb

@@ -1,12 +1,12 @@
 #* flex_array_reshape.rb - The flexible array class reshape and related methods.
 class FlexArray
-  #Return a copy of this \FlexArray, recast in a new shape, dropping or 
+  #Return a copy of this \FlexArray, recast in a new shape, dropping or
   #repeating data elements as required.
   #<br>Parameters
-  #* array_specs - The specification of the flex array subscript limits. 
-  #  These can either be integers, in which case the limits are 0...n or 
-  #  they can be ranges of integers, in which case the limits are those 
-  #  of the range, or they can be an array of integers and/or ranges of 
+  #* array_specs - The specification of the flex array subscript limits.
+  #  These can either be integers, in which case the limits are 0...n or
+  #  they can be ranges of integers, in which case the limits are those
+  #  of the range, or they can be an array of integers and/or ranges of
   #  integers to represent arrays of more than one dimension.
   #<br>Returns
   #* The reshaped flexible array.
@@ -15,31 +15,23 @@ class FlexArray
     FlexArray.new(array_specs) {iterator.next}
   end
 
-  #Recast this \FlexArray in a new shape, dropping or 
+  #Recast this \FlexArray in a new shape, dropping or
   #repeating data elements as required.
   #<br>Parameters
-  #* array_specs - The specification of the flex array subscript limits. 
-  #  These can either be integers, in which case the limits are 0...n or 
-  #  they can be ranges of integers, in which case the limits are those 
-  #  of the range, or they can be an array of integers and/or ranges of 
+  #* array_specs - The specification of the flex array subscript limits.
+  #  These can either be integers, in which case the limits are 0...n or
+  #  they can be ranges of integers, in which case the limits are those
+  #  of the range, or they can be an array of integers and/or ranges of
   #  integers to represent arrays of more than one dimension.
   #<br>Returns
   #* The reshaped, flexible array.
   def reshape!(array_specs)
-    iterator = @array_data.cycle
-    temp = FlexArray.new(array_specs) {iterator.next}
-    @array_specs, @array_data, @dimensions = 
-      temp.array_specs, temp.array_data, temp.dimensions
+    temp = self.reshape(array_specs)
+    @array_specs, @array_data = temp.array_specs, temp.array_data
     self
   end
 
-  #Unravel the multi-dimensional structure, and any contained arrays into 
-  #a simple array.
-  def flatten
-    @array_data.flatten
-  end
-
-  #Convert the flex array to a simple array. Contained arrays are not affected.  
+  #Convert the flex array to a simple array. Contained arrays are not affected.
   def to_a
     @array_data.dup
   end

data/lib/flex_array/flex_array_transpose.rb

@@ -7,11 +7,24 @@ class FlexArray
   #<br>Note
   #* Transposing an array disables the speed-up for processing the array with
   #  an index of [:all].
-  def transpose(dim_a, dim_b)
+  def transpose!(dim_a, dim_b)
     validate_dimension(dim_a)
     validate_dimension(dim_b)
     @array_specs[dim_a], @array_specs[dim_b] = @array_specs[dim_b], @array_specs[dim_a]
-    @transposed = true
+    @transposed = @array_specs.transposed?
     self
   end
+
+  #Return a reference to this array's data with the specified dimensions
+  #transposed. This may change the "shape" of the array if the transposed
+  #dimensions were of different limits.
+  #<br>Returns
+  #* The flex array transposed.
+  #<br>Note
+  #* Transposing an array disables the speed-up for processing the array with
+  #  an index of [:all].
+  def transpose(dim_a, dim_b)
+    FlexArray.new_from_array(self).transpose!(dim_a, dim_b)
+  end
+
 end

data/lib/flex_array/flex_array_validate.rb

@@ -7,31 +7,31 @@ class FlexArray
   #* true if the arrays are compatible.
   def compatible?(other)
     @array_specs == other.array_specs
+  rescue Exception
+    false
   end
 
   private
-  
+
   #Validate the dimensionality of the indexes passed in.
   #<br>Parameters
   #* indexes - An array of indexes to be validated.
-  #<br>Returns
-  #* true if the indexes value is [:all] and the array is not transposed.
   #<br>Exceptions
   #* ArgumentError - raised on invalid dimensionality.
-  def validate_all_or_index_count(indexes)
-    if indexes == [:all]
-      !@transposed
-    elsif @dimensions != indexes.length
-      fail ArgumentError, "Incorrect number of indexes: #{@dimensions} expected."
+  def validate_index_count(indexes)
+    unless indexes == [:all]
+      if dimensions != indexes.length
+        fail ArgumentError, "Incorrect number of indexes: #{dimensions} expected."
+      end
     end
   end
-  
+
   #Is this a valid dimension selector?
   #<br>Exceptions
   #* ArgumentError - raised on invalid dimension.
   def validate_dimension(dim)
-    unless (0...@dimensions) === dim
-      fail ArgumentError, "Invalid dimesnsion selector: #{dim}"
+    unless (0...dimensions) === dim
+      fail ArgumentError, "Invalid dimension selector: #{dim}"
     end
   end
 end