flex_array 0.2.0 → 0.3.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YzZiYThmNDY2YTU2NGE5YmQzNjUxNjRhODdkMzJiMGEwMWNiM2MwZg==
+    OWZiZTdkNTc4MmMyOTBiY2YwMjQ2ZTE5YmU1NWU0YWNmNzQ3MTRiNg==
   data.tar.gz: !binary |-
-    M2NjZmZmMjM2ZmEzMGNkNzc1NjFiNWEwNDE4ZTc3Y2M3ZmVkZjYzOQ==
+    NjhmZmMxZjFlM2Q1YWM2MDc4YjRhMTVjM2FhOTRmYWE2NTE4MzU1NA==
 SHA512:
   metadata.gz: !binary |-
-    MmJlZDVkZTRiMzJhMmU3ZTEyNmU3MmQyM2Q0NWQ3MDAxNTRjZDkzMGRlZjE4
-    ZjMyY2EzYzA4N2RjY2U5YzVlNjg3NGM4ZTQwNTAxOGFlNWYzYzAyN2MyNjE1
-    M2FlMWI1N2YwYTk0MGQ4ZTBjMmQ3N2M1MDZjMzYzNjM1YmRmZWY=
+    Y2FjMDgyYTRjZGY5NzQ2MzY5MzdjNTJhNGVjZDkyZjRiYTc3ZjBmZWMyMWVj
+    MGE1ZmU5NTBjMzQ0Y2ViOGEyYTc5ZGFmMGQyZGE4YzljYzMzNGU4NWQ4MTRm
+    NjQzOWEzNGMwZGM3OTE0YjFkZWE1ODljMTY1YzE2MzEwZTkyOWU=
   data.tar.gz: !binary |-
-    MjYwNDJkODI2YzA2YTE0NTY5MmZiZmQxNGYyNzA0NzExYzI0YWI1N2U3MGVm
-    NDliYWIxZTQyYjJhYzQzM2I4NDljOTI0NGZlZDQwNjlhMThmYjU2NDA5OGJk
-    NjQxZGM3YWEzZWIyYmU0MzA4NzNjYjgyYjNlNjkwMTdmZDgwMjg=
+    ZTNmMDUwOGEyNGRmYzljZjhjMjhlOWQ1NjVjMjlmNDA4MjZhODAyM2I2OWIy
+    NmU4ZWU4M2Y2OWEyOTlkZjgxZmIxZTczM2YxZWNkZDI2YzY4ZTVjMzNlMGMy
+    ODU1NGU2NWY5YTZhOTQzNjAyNWJjZGJjNGRiMjU3ZjQ2YmI4MzM=

data/lib/flex_array.rb

@@ -1,5 +1,7 @@
 require 'in_array'
+require_relative 'flex_array/flex_array_forever'
 require_relative 'flex_array/spec_component'
+require_relative 'flex_array/spec_array'
 require_relative 'flex_array/object'
 require_relative 'flex_array/integer'
 require_relative 'flex_array/range'
@@ -17,14 +19,13 @@ require_relative 'flex_array/flex_array_process'
 #\FlexArray - A flexible array class.
 #* flex_array.rb - The root file that gathers up all the flex array parts.
 class FlexArray
-  include Enumerable
   include InArrayAlready
 
   #The version of this class.
   #<br>Returns
   #* A version string; <major>.<minor>.<step>
   def self.version
-    '0.2.0'
+    '0.3.0'
   end
 
   #The version of the class of this instance.
@@ -41,16 +42,23 @@ class FlexArray
   attr_accessor :array_data
 
   #The total number of elements in this array.
-  attr_reader :count
+  def length
+    @array_specs.spec_count
+  end
+
+  alias size length
 
   #The number of dimensions in this array.
-  attr_reader :dimensions
+  def dimensions
+    @array_specs.spec_dimensions
+  end
+
+  #Is this flex array transposed?
+  attr_reader :transposed
 
   #Get the limits of the subscripts of the flex array.
-  #<br>Returns
-  #* An array of dimension limits ranges.
   def limits
-    Array.new(@dimensions) {|dimension| @array_specs[dimension].range}
+    @array_specs.collect {|spec| spec.range }
   end
 
   #Return this flex array as a flex array!
@@ -79,11 +87,9 @@ class FlexArray
   def <=>(other)
     @array_data <=> other.array_data
   end
-  
-  #Update the count and dimensions variables
-  def update_count_and_dimensions
-    @dimensions = @array_specs.length
-    @count      = @array_data.length
-    self
+
+  #Is this flex array empty?
+  def empty?
+    length == 0
   end
 end

data/lib/flex_array/array.rb

@@ -1,5 +1,3 @@
-require_relative '../flex_array'
-
 #Extensions to Array needed to support flex array.
 class Array
   #Get the specifications of the array index values.
@@ -8,23 +6,21 @@ class Array
   def limits
     [0...self.length]
   end
-  
+
   #Quick access to the limits for internal use.
   #<br>Returns
   #* An array with one spec component in it.
   def array_specs
-    [SpecComponent.new(0...self.length, 1)]
+    SpecArray.new([0...self.length])
   end
-  
+
   #Quick access to the array data for internal use.
   #<br>Returns
   #* An array -- self
   def array_data
     self
   end
-  
-  alias :length :count
-  
+
   #Convert this array to an range index against the spec.
   #<br>Parameters
   #* spec - The spec component used to validate this index.
@@ -33,22 +29,26 @@ class Array
   #<br>Exceptions
   #* IndexError if the range is not valid.
   def to_index_range(spec)
-    self_min, self_max, spec_max = Integer(self[0]), Integer(self[1]), spec.max
-    self_min = spec_max + self_min + 1 if self_min < 0
-    self_max = spec_max + self_max + 1 if self_max < 0
-    
-    if self.length == 2 && self_min <= self_max && spec === self_min && spec === self_max
-      self_min..self_max
-    else
-      fail IndexError, "Subscript invalid or out of range: #{self.inspect}"
+    spec_max = spec.max
+
+    self.collect do |value|
+      value = Integer(value)
+      value = spec_max + value + 1 if value < 0
+
+      unless spec === value
+        fail IndexError, "Subscript invalid or out of range: #{self.inspect}"
+      end
+
+      value
     end
-  end  
-  
+  end
+
   #Return this flex array as a flex array!
   #<br>Returns
   #* A flex array that references this array.
   #<br>Note
-  #* To avoid a shared reference, use my_array.dup.to_flex_array instead.
+  #* To avoid a shared reference, use my_array.dup.to_flex_array or
+  #  FlexArray.new_from_array(my_array.dup)  instead.
   def to_flex_array
     FlexArray.new_from_array(self)
   end

data/lib/flex_array/flex_array_append.rb

@@ -8,10 +8,10 @@ class FlexArray
   #<br>Exceptions
   #* ArgumentError if the data may not be appended.
   def << (data)
+    fail "Cannot append to a transposed array." if @transposed
     specs = get_append_specs(data = data.in_array)
-    data.array_data.each {|element| @array_data << element }
-    @array_specs[0].enlarge(specs[0].span)
-    @count += data.count
+    @array_data += data.array_data
+    @array_specs.enlarge(specs[0].span)
     self
   end
 
@@ -33,19 +33,19 @@ class FlexArray
   #* ArgumentError if the data may not be appended.
   def get_append_specs(data)
     spec_len = (specs = data.array_specs).length
-    
-    if @dimensions == spec_len+1
-      specs.insert(0, SpecComponent.new(0...1, nil))
-    elsif @dimensions != spec_len
+
+    if dimensions == spec_len+1
+      specs = specs.dup.insert(0, SpecComponent.new(0...1, nil))
+    elsif dimensions != spec_len
       fail ArgumentError, "Incompatible dimensionality error on <<."
     end
-    
-    (1...@dimensions).each do |index|
-      unless @array_specs[index] == specs[index]
+
+    (1...dimensions).each do |index|
+      unless @array_specs[index].span == specs[index].span
         fail ArgumentError, "Dimension mismatch error on <<."
       end
     end
-    
+
     specs
   end
 end

data/lib/flex_array/flex_array_each.rb

@@ -1,98 +1,435 @@
 #* flex_array_each.rb - The flexible array class each and related methods.
+# :reek:RepeatedConditional - @transposed determines if short cuts are allowed.
 class FlexArray
-  #Process the standard :each operator.
+  include Enumerable
+
+  #Retrieve data from the array endlessly repeating as needed.
   #<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 omitted
-  #  or passed in as [:all] all elements of the array are processed.
+  #* count - The number of times to cycle through the flex array. Defaults to
+  #  cycling forever.
   #* block - The optional block to be executed for each selected array element.
-  #  The return value is the last value returned by the block. If the block 
-  #  is not present, an enumerator object is returned.
+  #  The return value is the last value returned by the block. If the block
+  #  is not present, then an enumerator object is returned.
+  #<br>Returns
+  #* nil or an enumerator if no block is provided.
   #<br>Block Arguments
   #* value - Each value selected by the iteration.
-  def each(indexes=[:all], &block)
-    if validate_all_or_index_count(indexes)
-      @array_data.each(&block)
-    elsif block_given?
-      process_indexes(indexes) {|_index, posn| block.call(@array_data[posn])}
-    else
-      Enumerator.new do |yielder|
-        process_indexes(indexes) {|_index, posn| yielder.yield(@array_data[posn])}
+  #<br>Endemic Code Smells
+  #* :reek:NestedIterators
+  def cycle(count = FOREVER, &block)
+    if block_given?
+      if @transposed && length > 0
+        count.times do
+          process_all do |_index, posn|
+            block.call(@array_data[posn])
+          end
+        end
+
+        nil
+      else
+        @array_data.cycle(count.to_i, &block)
       end
+    else
+      self.to_enum(:cycle, count)
     end
   end
 
-  #Retrieve data from the array endlessly repeating as needed.
+  #Retrieve data from a subset of the flex array endlessly repeating as needed.
   #<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 omitted
-  #  or passed in as [:all] all elements of the array are processed.
+  #  a splat parameter, it must be passed as an array explicitly.
+  #* count - The number of times to cycle through the flex array. Defaults to
+  #  cycling forever.
   #* block - The optional block to be executed for each selected array element.
-  #  The return value is the last value returned by the block. If the block 
+  #  The return value is the last value returned by the block. If the block
   #  is not present, then an enumerator object is returned.
+  #<br>Returns
+  #* nil or an enumerator if no block is provided.
   #<br>Block Arguments
-  #* value - Each value selected by the iteration.  
-  def cycle(indexes=[:all], &block)
-    if validate_all_or_index_count(indexes)
-      @array_data.cycle(&block)
-    elsif block_given?
-      loop {process_indexes(indexes) {|_index, posn| block.call(@array_data[posn])}}
+  #* value - Each value selected by the iteration.
+  #<br>Endemic Code Smells
+  #* :reek:NestedIterators
+  def select_cycle(indexes, count = FOREVER, &block)
+    validate_index_count(indexes)
+
+    if block_given?
+      unless empty?
+        count.times do
+          process_indexes(indexes) do |_index, posn|
+            block.call(@array_data[posn])
+          end
+        end
+      end
+
+      nil
     else
-      Enumerator.new do |yielder|
-        loop {process_indexes(indexes) {|_index, posn| yielder.yield(@array_data[posn])}}
+      self.to_enum(:select_cycle, indexes, count)
+    end
+  end
+
+  #Process the standard each operator.
+  #<br>Parameters
+  #* block - The optional block to be executed for each selected array element.
+  #<br>Returns
+  #* If the block is not present, then an enumerator object is returned.
+  #  Otherwise the flex array is returned.
+  #<br>Block Arguments
+  #* value - Each value selected by the iteration.
+  def each(&block)
+    if block_given?
+      if @transposed
+        process_all {|_index, posn| block.call(@array_data[posn])}
+      else
+        @array_data.each(&block)
       end
+
+      self
+    else
+      self.to_enum(:each)
     end
   end
-  
-  #Process the standard :each_with_index operator.
+
+  #Process the enhanced select_each operator.
   #<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 omitted
-  #  or passed in as [:all] all elements of the array are processed.
+  #  a splat parameter, it must be passed as an array explicitly
   #* block - The optional block to be executed for each selected array element.
-  #  The return value is the last value returned by the block. If the block 
-  #  is not present, then an enumerator object is returned.
+  #<br>Returns
+  #* If the block is not present, then an enumerator object is returned.
+  #  Otherwise the flex array is returned.
+  #<br>Block Arguments
+  #* value - Each value selected by the iteration.
+  def select_each(indexes, &block)
+    validate_index_count(indexes)
+
+    if block_given?
+      process_indexes(indexes) {|_index, posn| block.call(@array_data[posn])}
+      self
+    else
+      self.to_enum(:select_each, indexes)
+    end
+  end
+
+  #Process the standard each_with_index operator.
+  #<br>Parameters
+  #* block - The optional block to be executed for each selected array element.
+  #<br>Returns
+  #* If the block is not present, then an enumerator object is returned.
+  #  Otherwise the flex array is returned.
   #<br>Block Arguments
   #* value - Each value selected by the iteration.
   #* index - An array with the full index of the selected value.
-  def each_with_index(indexes=[:all], &block)
-    validate_all_or_index_count(indexes)
+  def each_with_index(&block)
+    if block_given?
+      process_all {|index, posn| block.call(@array_data[posn], index)}
+      self
+    else
+      self.to_enum(:each_with_index)
+    end
+  end
+
+  #Process the enhanced select_each_with_index operator.
+  #<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.
+  #* block - The optional block to be executed for each selected array element.
+  #<br>Returns
+  #* If the block is not present, then an enumerator object is returned.
+  #  Otherwise the flex array is returned.
+  #<br>Block Arguments
+  #* value - Each value selected by the iteration.
+  #* index - An array with the full index of the selected value.
+  def select_each_with_index(indexes, &block)
+    validate_index_count(indexes)
 
     if block_given?
       process_indexes(indexes) {|index, posn| block.call(@array_data[posn], index)}
+      self
     else
-      Enumerator.new do |yielder|
-        process_indexes(indexes) {|index, posn| yielder.yield(@array_data[posn], index)}
-      end
+      self.to_enum(:select_each_with_index, indexes)
     end
   end
-  
-  #A specialized each variant that passes the low level data, the index 
+
+  #A specialized each variant that passes the low level data, the index
   #and the position to the block.
   #<br>Parameters
-  #* indexes - An array with as many entries as the flexible array has 
+  #* block - The optional block to be executed for each selected array element.
+  #  The return value is the last value returned by the block. If the block
+  #  is not present, then an enumerator object is returned.
+  #<br>Returns
+  #* If the block is not present, then an enumerator object is returned.
+  #  Otherwise the flex array is returned.
+  #<br>Block Arguments
+  #* index - An array with the full index of the selected value.
+  #* posn - The position of the data in the low level data store.
+  def _each_raw(&block)
+    if block_given?
+      process_all {|index, posn| block.call(index, posn)}
+      self
+    else
+      self.to_enum(:_each_raw)
+    end
+  end
+
+  #An enhanced specialized each variant that passes the low level data,
+  #the index and the position to the block.
+  #<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 omitted
-  #  or passed in as [:all] all elements of the array are processed.
+  #  a splat parameter, it must be passed as an array explicitly.
   #* block - The optional block to be executed for each selected array element.
-  #  The return value is the last value returned by the block. If the block 
+  #  The return value is the last value returned by the block. If the block
   #  is not present, then an enumerator object is returned.
+  #<br>Returns
+  #* If the block is not present, then an enumerator object is returned.
+  #  Otherwise the flex array is returned.
   #<br>Block Arguments
-  #* data - A reference to the low level data store.
   #* index - An array with the full index of the selected value.
   #* posn - The position of the data in the low level data store.
-  def _each_raw(indexes=[:all], &block)
-    validate_all_or_index_count(indexes)
+  def _select_each_raw(indexes, &block)
+    validate_index_count(indexes)
+
+    if block_given?
+      process_indexes(indexes) {|index, posn| block.call(index, posn)}
+      self
+    else
+      self.to_enum(:_select_each_raw, indexes)
+    end
+  end
+
+  alias_method :flatten_collect, :collect
+
+  #The flex array version of collect that returns a flex array.
+  #<br>Parameters
+  #* block - The optional block to be executed for each selected array element.
+  #<br>Returns
+  #* An array of the computed objects retuned by the block.
+  #<br>Block Arguments
+  #* value - Each value selected by the iteration.
+  def collect(&block)
+    result = self.dup
+    result.collect!(&block)
+  end
+
+  #The flex array version of collect that accepts an optional set of indexes
+  #to select the data being collected into a flex array.
+  #<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.
+  #* block - The optional block to be executed for each selected array element.
+  #<br>Returns
+  #* An array of the computed objects retuned by the block.
+  #  If the block is not present, an enumerator object is returned.
+  #<br>Block Arguments
+  #* value - Each value selected by the iteration.
+  def select_collect(indexes, &block)
+    result = self.dup
+    result.select_collect!(indexes, &block)
+  end
+
+  #The flex array version of collect that accepts an optional set of indexes
+  #to select the data being collected into a standard array.
+  #<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.
+  #* block - The optional block to be executed for each selected array element.
+  #<br>Returns
+  #* An array of the computed objects retuned by the block.
+  #  If the block is not present, an enumerator object is returned.
+  #<br>Block Arguments
+  #* value - Each value selected by the iteration.
+  def select_flatten_collect(indexes, &block)
+    validate_index_count(indexes)
 
     if block_given?
-      process_indexes(indexes) {|index, posn| block.call(@array_data, index, posn)}
+      result = []
+      process_indexes(indexes) {|_index, posn| result << block.call(@array_data[posn])}
+      result
+    else
+      self.to_enum(:select_collect, indexes)
+    end
+  end
+
+  #The flex array version of collect!
+  #<br>Parameters
+  #* block - The *required* block to be executed for each selected array element.
+  #  The return value is the last value returned by the block. If the block
+  #  is not present, an enumerator object is returned.
+  #<br>Returns
+  #* self
+  #<br>Block Arguments
+  #* value - Each value selected by the iteration.
+  def collect!(&block)
+    fail ArgumentError, "A block is required." unless block_given?
+
+    if @transposed
+      process_all {|_index, posn| @array_data[posn] =
+        block.call(@array_data[posn])}
     else
-      Enumerator.new do |yielder|
-        process_indexes(indexes) {|index, posn| yielder.yield(@array_data, index, posn)}
+      @array_data = @array_data.collect(&block)
+    end
+
+    self
+  end
+
+  #The enhanced flex array version of collect! that accepts a set of indexes
+  #to select the data being collected.
+  #<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.
+  #* block - The *required* block to be executed for each selected array element.
+  #  The return value is the last value returned by the block. If the block
+  #  is not present, an enumerator object is returned.
+  #<br>Returns
+  #* self
+  #<br>Block Arguments
+  #* value - Each value selected by the iteration.
+  def select_collect!(indexes, &block)
+    fail ArgumentError, "A block is required." unless block_given?
+    validate_index_count(indexes)
+
+    process_indexes(indexes) {|_index, posn| @array_data[posn] =
+      block.call(@array_data[posn])}
+
+    self
+  end
+
+  #The flex array version of find_index. This returns the
+  #coordinates of the first object that matches the search object or is
+  #flagged true by the search block.
+  #<br>Parameters
+  #* object - The optional value to search for.
+  #* block - The optional block to be executed for each selected array element.
+  #  If the block or object are not present, an enumerator object is returned.
+  #<br>Returns
+  #* The index of the first place that matched or nil if none matched.
+  #<br>Block Arguments
+  #* value - Each value selected by the iteration.
+  def find_index(value = nil, &block)
+    blk = get_find_block(value, &block)
+
+    if blk
+      process_all do |index, posn|
+        if blk.call(@array_data[posn])
+          return index
+        end
       end
+
+      nil
+    else
+      self.to_enum(:find_index)
+    end
+  end
+
+  #The enhanced flex array version of find_index. This returns the
+  #coordinates of the first object that matches the search object or is
+  #flagged true by the search block.
+  #<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.
+  #* object - The optional value to search for.
+  #* block - The optional block to be executed for each selected array element.
+  #  If the block or object are not present, an enumerator object is returned.
+  #<br>Returns
+  #* The index of the first place that matched or nil if none matched.
+  #<br>Block Arguments
+  #* value - Each value selected by the iteration.
+  def select_find_index(indexes, value = nil, &block)
+    validate_index_count(indexes)
+    blk = get_find_block(value, &block)
+
+    if blk
+      process_indexes(indexes) do |index, posn|
+        if blk.call(@array_data[posn])
+          return index
+        end
+      end
+
+      nil
+    else
+      self.to_enum(:select_find_index, indexes)
+    end
+  end
+
+  #The improved flex array version of find_index. This returns the
+  #coordinates of objects that match the search object or are
+  #flagged true by the search block.
+  #<br>Parameters
+  #* object - The optional value to search for.
+  #* block - The optional block to be executed for each selected array element.
+  #  If the block or object are not present, an enumerator object is returned.
+  #<br>Returns
+  #* An array of the indexes of the places that matched.
+  #<br>Block Arguments
+  #* value - Each value selected by the iteration.
+  def find_indexes(value = nil, &block)
+    blk, result = get_find_block(value, &block), []
+
+    if blk
+      process_all do |index, posn|
+        if blk.call(@array_data[posn])
+          result << index.dup
+        end
+      end
+
+      result
+    else
+      self.to_enum(:find_indexes)
+    end
+  end
+
+  #The enhanced and improved flex array version of find_index. This returns the
+  #coordinates of objects that match the search object or are
+  #flagged true by the search block.
+  #<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.
+  #* object - The optional value to search for.
+  #* block - The optional block to be executed for each selected array element.
+  #  If the block or object are not present, an enumerator object is returned.
+  #<br>Returns
+  #* An array of the indexes of the places that matched.
+  #<br>Block Arguments
+  #* value - Each value selected by the iteration.
+  def select_find_indexes(indexes, value = nil, &block)
+    validate_index_count(indexes)
+    blk, result = get_find_block(value, &block), []
+
+    if blk
+      process_indexes(indexes) do |index, posn|
+        if blk.call(@array_data[posn])
+          result << index.dup
+        end
+      end
+
+      result
+    else
+      self.to_enum(:select_find_index, indexes)
+    end
+  end
+
+  private
+
+  #A helper method to determine which block to use in the find_index family.
+  #<br>Returns
+  #* The block to use or nil.
+  #<br>Endemic Code Smells
+  #* :reek:NilCheck
+  def get_find_block(value, &block)
+    if block_given?
+      block
+    elsif value.nil?
+      nil
+    else
+      lambda {|obj| obj == value }
     end
   end
-end
+end