flex_array 0.3.5 → 0.3.6

data/lib/flex_array/flex_array_forever.rb

@@ -1,13 +1,15 @@
-#* flex_array_forever.rb - Forever looping support for the flexible array class.
+# Forever looping support for the flexible array class.
+
 class FlexArray
-  #A helper class that encapsulates the idea of looping without end!
+  # A helper class that encapsulates the idea of looping without end!
+
   class ForEver
-    #Do something until false == true ;-)
+    # Do something until false == true ;-)
     def times(&block)
       loop {block.call}
     end
 
-    #Convert an eternity into an integer. ;-)
+    # Convert an eternity into an integer. ;-)
     def to_i
       nil
     end

data/lib/flex_array/flex_array_index.rb

@@ -1,19 +1,7 @@
-#* flex_array_index.rb - The flexible array indexing and related methods.
+# The flexible array indexing and related methods.
+
 class FlexArray
-  #Retrieve the selected data from the \FlexArray.
-  #<br>Parameters
-  #* 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
-  #  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
-  #* If the indexes parameter equals a single :all this maps to all
-  #  elements of the array, regardless of its dimensionality.
+  # Retrieve the selected data from the flex array.
   def [](*indexes)
     validate_index_count(indexes)
     result = []
@@ -21,20 +9,7 @@ class FlexArray
     result.length == 1 ? result[0] : result
   end
 
-  #Store the value data into the \FlexArray.
-  #<br>Parameters
-  #* 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
-  #  dimension, or it can be the symbol :all for all of the possible values
-  #  of that dimension.
-  #* value - A value to be stored in the selected array entries.
-  #<br>Returns
-  #* The value stored in the array.
-  #<br>Note
-  #* If the indexes parameter equals a single :all this maps to all
-  #  elements of the array, regardless of its dimensionality.
+  # Store the value data into the flex array.
   def []=(*indexes, value)
     validate_index_count(indexes)
     source = value.in_array.cycle

data/lib/flex_array/flex_array_new.rb

@@ -1,28 +1,14 @@
-#* flex_array_new.rb - The flexible array class constructor and related methods.
+# The flexible array class constructor and related methods.
 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
-  #  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 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.
+  # Construct a flexible array object.
   def initialize(array_specs, default=nil, &init_block)
     @array_specs = SpecArray.new(array_specs.in_array)
     @transposed = false
 
-    #Allocate the data for the array.
+    # Allocate the data for the array.
     @array_data = Array.new(@array_specs.spec_count, default)
 
-    #Set up the array with the optional init_block.
+    # Set up the array with the optional init_block.
     if init_block
       process_all {|index, posn| @array_data[posn] = init_block.call(index)}
     end
@@ -30,11 +16,7 @@ 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.
+  # Create a duplicate of this array.
   def dup
     other = self.shallow_dup
     other.array_specs = @array_specs.dup
@@ -42,49 +24,20 @@ class FlexArray
     other
   end
 
-  #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
-  #  integers to represent arrays of more than one dimension.
-  #* 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.
+  # Construct a flex array using other as a template or data source.
   def self.new_from(array_specs, other)
     iterator = other.array_data.cycle
     FlexArray.new(array_specs) {iterator.next}
   end
 
-  #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
-  #  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 array are used instead.
-  #* 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.
-  #* To make a copy of a flex array, use dup instead.
+  # Construct a flex array using a all or a portion of portion of another flex
+  # array as a data source.
   def self.new_from_selection(array_specs, other, 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.
-  #<br>Returns
-  #* A flex array.
-  #<br>Note
-  #* The data array of the new flex array is a reference to the source array.
+  # Construct a flex array as a duplicate of a source array or flex array.
   def self.new_from_array(other)
     result = FlexArray.new(0)
     result.array_specs = other.array_specs.dup

data/lib/flex_array/flex_array_process.rb

@@ -1,18 +1,9 @@
-#* flex_array_process.rb - The flexible array class index processing routines.
+# The flexible array class index processing routines.
 class FlexArray
   private
-  #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
-  #  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.
-  #* posn - The position of the element being accessed in the data array.
+
+  # Process a flex array index array. This is the heart of the flex array
+  # indexing process.
   def process_indexes(indexes, &block)
     current = Array.new(dimensions, 0)
 
@@ -29,33 +20,19 @@ class FlexArray
     end
   end
 
-  #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
-  #  in the data array.
-  #* 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.
-  #* 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
+  # The worker bee for process_indexes.
   # :reek:LongParameterList
   def process_indexes_worker(depth, posn, indexes, current, &block)
-    if depth == dimensions                 #Is there more work to do?
-      block.call(current, posn)            #Index ready, call the block.
+    if depth == dimensions                 # Is there more work to do?
+      block.call(current, posn)            # Index ready, call the block.
     else
-      spec = @array_specs[depth]           #Get the current specification.
-      min, stride = spec.min, spec.stride  #Extract the relevant info.
+      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.
 
-      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 the next component in the array index.
         process_indexes_worker(depth+1,
                                posn + (index-min) * stride,
                                indexes,
@@ -65,43 +42,26 @@ class FlexArray
     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.
-  #* posn - The position of the element being accessed in the data array.
+  # Special case where all of the array is being processed.
   def process_all(&block)
     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
-  #  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.
-  #* 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
+  # The worker bee for process_all.
   def process_all_worker(depth, posn, current, &block)
-    if depth == dimensions                 #Is there more work to do?
-      block.call(current, posn)            #Index ready, call the block.
+    if depth == dimensions                 # Is there more work to do?
+      block.call(current, posn)            # Index ready, call the block.
     else
-      spec = @array_specs[depth]           #Get the current specification.
+      spec = @array_specs[depth]           # Get the current specification.
       stride = spec.stride
 
-      spec.each do |index|                 #Iterate over the range.
-        current[depth] = index             #Update the current index.
-        #Process the next component in the array specification.
+      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                     #Step to the next position.
+        posn += stride                     # Step to the next position.
       end
     end
   end

data/lib/flex_array/flex_array_reshape.rb

@@ -1,38 +1,28 @@
-#* flex_array_reshape.rb - The flexible array class reshape and related methods.
+# The flexible array class reshape and related methods.
+
 class FlexArray
-  #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
-  #  integers to represent arrays of more than one dimension.
-  #<br>Returns
-  #* The reshaped flexible array.
+  # Return a copy of this flex array, recast in a new shape, dropping or
+  # repeating data elements as required.
   def reshape(array_specs)
     iterator = @array_data.cycle
     FlexArray.new(array_specs) {iterator.next}
   end
 
-  #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
-  #  integers to represent arrays of more than one dimension.
-  #<br>Returns
-  #* The reshaped, flexible array.
+  # Recast this flex array in a new shape, dropping or repeating data elements
+  # as required.
   def reshape!(array_specs)
     temp = self.reshape(array_specs)
     @array_specs, @array_data = temp.array_specs, temp.array_data
     self
   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
+    if @transposed
+      fetch = self.cycle
+      Array.new(@array_data.length) { fetch.next }
+    else
+      @array_data.dup
+    end
   end
 end

data/lib/flex_array/flex_array_transpose.rb

@@ -1,12 +1,8 @@
-#* flex_array_transpose.rb - The flexible array class transpose and related methods.
+# The flexible array class transpose and related methods.
+
 class FlexArray
-  #Transpose the specified dimensions. 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].
+  # Transpose the specified dimensions. This may change the "shape" of the array
+  # if the transposed dimensions were of different limits.
   def transpose!(dim_a, dim_b)
     validate_dimension(dim_a)
     validate_dimension(dim_b)
@@ -15,14 +11,9 @@ class FlexArray
     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].
+  # 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.
   def transpose(dim_a, dim_b)
     FlexArray.new_from_array(self).transpose!(dim_a, dim_b)
   end

data/lib/flex_array/flex_array_validate.rb

@@ -1,10 +1,7 @@
-#* flex_array_validate.rb - The flexible array class index validation routines.
+# Some flexible array class index validation routines.
+
 class FlexArray
-  #Is this array compatible with other?
-  #<br>Parameters
-  #* other - The object being tested for compatibility.
-  #<br>Returns
-  #* true if the arrays are compatible.
+  # Is this array compatible with other?
   def compatible?(other)
     @array_specs == other.array_specs
   rescue
@@ -13,11 +10,7 @@ class FlexArray
 
   private
 
-  #Validate the dimensionality of the indexes passed in.
-  #<br>Parameters
-  #* indexes - An array of indexes to be validated.
-  #<br>Exceptions
-  #* ArgumentError - raised on invalid dimensionality.
+  # Validate the dimensionality of the indexes passed in.
   def validate_index_count(indexes)
     unless indexes == [:all]
       if dimensions != indexes.length
@@ -26,9 +19,7 @@ class FlexArray
     end
   end
 
-  #Is this a valid dimension selector?
-  #<br>Exceptions
-  #* ArgumentError - raised on invalid dimension.
+  # Is this a valid dimension selector?
   def validate_dimension(dim)
     unless (0...dimensions) === dim
       fail ArgumentError, "Invalid dimension selector: #{dim}"

data/lib/flex_array/integer.rb

@@ -1,10 +1,7 @@
-#Extensions to Integer needed to support flex array.
+# Extensions to Integer needed to support flex array.
+
 class Integer
-  #Convert this integer to a limits component.
-  #<br>Parameters
-  #* stride - the number of cells separating data with adjacent indexes.
-  #<br>Returns
-  #* A SpecComponent object of 0...self
+  # Convert this integer to a limits component.
   def to_spec_component(stride)
     if self >= 0
       SpecComponent.new(0...self, stride)
@@ -13,13 +10,7 @@ class Integer
     end
   end
 
-  #Convert this integer to an range index against the spec.
-  #<br>Parameters
-  #* spec - The spec component used to validate this index.
-  #<br>Returns
-  #* A range.
-  #<br>Exceptions
-  #* IndexError if the range is not valid.
+  # Convert this integer to a range index against the spec.
   def to_index_range(spec)
     alter_ego = (self >= 0) ? self : (spec.max + self + 1)
 

data/lib/flex_array/object.rb

@@ -1,21 +1,12 @@
-#Extensions to Object needed to support flex array.
+# Extensions to Object needed to support flex array.
+
 class Object
-  #Fail with message since the array dimension is invalid.
-  #<br>Parameters
-  #* _stride - unused, required to maintain signature.
-  #<br>Returns
-  #* Nothing, always fails.
+  # Fail with message since the array dimension is invalid.
   def to_spec_component(_stride)
     fail ArgumentError, "Invalid flex array dimension: #{self.inspect}"
   end
 
-  #Convert this object to an range index against the spec.
-  #<br>Parameters
-  #* spec - The spec component used to validate this index.
-  #<br>Returns
-  #* A range.
-  #<br>Exceptions
-  #* IndexError if the range is not valid.
+  # Convert this object to an range index against the spec.
   def to_index_range(spec)
     if self == :all
       spec.range