caruby-core 1.4.1

data/lib/caruby/util/stopwatch.rb

@@ -0,0 +1,66 @@
+require 'benchmark'
+
+# Stopwatch is a simple execution time accumulator.
+class Stopwatch
+  # Time accumulates elapsed real time and total CPU time.
+  class Time
+    # The Benchmark::Tms wrapped by this Time.
+    attr_reader :tms
+
+    def initialize(tms=nil)
+      @tms = tms || Benchmark::Tms.new
+    end
+
+    # Returns the cumulative elapsed real clock time.
+    def elapsed
+      @tms.real
+    end
+
+    # Returns the cumulative CPU total time.
+    def cpu
+      @tms.total
+    end
+
+    # Adds the time to execute the given block to this time. Returns the split execution Time.
+    def split(&block)
+      stms = Benchmark.measure(&block)
+      @tms += stms
+      Time.new(stms)
+    end
+
+    def reset
+      @tms = Benchmark::Tms.new
+    end
+  end
+  
+  # Executes the given block. Returns the execution Time.
+  def self.measure(&block)
+    new.run(&block)
+  end
+
+  # Creates a new idle Stopwatch.
+  def initialize
+    @time = Time.new
+  end
+
+  # Executes the given block. Accumulates the execution time in this Stopwatch. 
+  # Returns the execution Time.
+  def run(&block)
+    @time.split(&block)
+  end
+
+  # Returns the cumulative elapsed real clock time spent in {#run} executions.
+  def elapsed
+    @time.elapsed
+  end
+
+  # Returns the cumulative CPU total time spent in {#run} executions for the current process and its children.
+  def cpu
+    @time.cpu
+  end
+
+  # Resets this Stopwatch's cumulative time to zero.
+  def reset
+    @time.reset
+  end
+end

data/lib/caruby/util/topological_sync_enumerator.rb

@@ -0,0 +1,53 @@
+require 'caruby/util/collection'
+
+class TopologicalSyncEnumerator
+  include Enumerable
+
+  def initialize(targets, sources, symbol, &matcher)
+    @tgts = targets
+    @srcs = sources
+    @mthd = symbol
+    @matcher = matcher || lambda { |tgt, srcs| srcs.first }
+  end
+
+  # Calls the given block on each matching target and source.
+  # Returns the matching target => source hash.
+  def each # :yields: target, source
+    # the parent hashes for targets and sources
+    pt = @tgts.to_compact_hash { |tgt| tgt.send(@mthd) }
+    ps = @srcs.to_compact_hash { |src| src.send(@mthd) }
+
+    # the child hashes
+    ct = LazyHash.new { Array.new }
+    cs = LazyHash.new { Array.new }
+
+    # collect the chidren and roots
+    rt = @tgts.reject { |tgt| p = pt[tgt]; ct[p] << tgt if p }
+    rs = @srcs.reject { |src| p = ps[src]; cs[p] << src if p }
+
+    # the match hash
+    matches = {}
+    # match recursively
+    each_match_recursive(rt, rs, ct, cs) do |tgt, src|
+      yield(tgt, src)
+      matches[tgt] = src
+    end
+
+    matches
+  end
+
+  private
+
+  def each_match_recursive(targets, sources, ct, cs, &block)
+    # copy the sources
+    srcs = sources.dup
+    # match each target, removing the matched source for the
+    # next iteration
+    targets.each do |tgt|
+      src = @matcher.call(tgt, srcs) || next
+      yield(tgt, src)
+      srcs.delete(src)
+      each_match_recursive(ct[tgt], cs[src], ct, cs, &block)
+    end
+  end
+end

data/lib/caruby/util/transitive_closure.rb

@@ -0,0 +1,45 @@
+require 'caruby/util/visitor'
+
+class Object
+  # Returns the transitive closure over a method or block, e.g.:
+  #   class Node
+  #     attr_reader :parent, :children
+  #     def initialize(name, parent=nil)
+  #       super()
+  #       @name = name
+  #       @parent = parent
+  #       @children = []
+  #       parent.children << self if parent
+  #     end
+  #
+  #     def to_s;
+  #   end
+  #   a = Node.new('a'); b = Node.new('b', a), c = Node.new('c', a); d = Node.new('d', c)
+  #   a.transitive_closure { |node| node.children }.to_a.join(", ") #=> a, b, c, d
+  #   a.transitive_closure(:children).to_a.join(", ") #=> a, b, c, d
+  # This method returns an array partially ordered by the closure method, i.e.
+  # each node occurs before all other nodes referenced directly or indirectly by the closure method.
+  #
+  # If a method symbol or name is provided, then that method is called. Otherwise, the block is called.
+  # In either case, the call is expected to return an object or Enumerable of objects which also respond
+  # to the method or block.
+  def transitive_closure(method=nil)
+    raise ArgumentError.new("Missing both a method argument and a block") if method.nil? and not block_given?
+    return transitive_closure() { |node| node.send(method) } if method
+    Visitor.new(:depth_first) { |node| yield node }.to_enum(self).to_a.reverse
+  end
+end
+
+module Enumerable
+  # Returns the transitive closure over all items in this Enumerable.
+  #
+  # @see Object#transitive_closure
+  def transitive_closure(method=nil, &navigator)
+    # delegate to Object if there is a method argument
+    return super(method, &navigator) if method
+    # this Enumerable's children are this Enumerable's contents
+    closure = super() { |node| node.equal?(self) ? self : yield(node) }
+    # remove this collection from the closure
+    closure[1..-1]
+  end
+end

data/lib/caruby/util/tree.rb

@@ -0,0 +1,48 @@
+# A Tree consists of a root node and subtree children.
+# A Tree can be decorated with an optional value.
+class Tree
+  attr_reader :root, :children
+
+  attr_accessor :value
+
+  # Creates a Trie with the given root node.
+  def initialize(root=nil)
+   @root = root
+   @children = []
+ end
+
+  # Adds a subtree rooted at the given node as a child of this tree.
+  def <<(node)
+    @children << self.class.new(node)
+    self
+  end
+
+  # Returns the subtree at the given node path.
+  def subtree(*path)
+    return self if path.empty?
+    first = path.shift
+    tree = @children.detect { |child| child.root == first }
+    tree.subtree(*path) if tree
+  end
+
+  alias :[] :subtree
+
+  # Creates the given node path if it does not yet exist.
+  # Returns the subtree at the path.
+  def fill(*path)
+    return self if path.empty?
+    first = path.shift
+    tree = subtree(first)
+    if tree.nil? then
+      self << first
+      tree = @children.last
+    end
+    tree.fill(*path)
+  end
+
+  def to_s
+    root_s = @root.nil? || Symbol === root ? root.inspect : root.to_s
+    return "[#{root_s}]" if @children.empty?
+    "[#{root_s} -> #{@children.join(', ')}]"
+  end
+end

data/lib/caruby/util/trie.rb

@@ -0,0 +1,37 @@
+require File.join(File.dirname(__FILE__), 'tree')
+
+# A Trie[http://en.wikipedia.org/wiki/Trie] is an associative access tree structure.
+#
+# @example
+#   trie = Trie.new
+#   trie[:a, :b] = 1
+#   trie[:a, :b] #=> 1
+#   trie[:a, :c] #=> nil
+class Trie
+  # Creates a new empty Trie.
+  def initialize
+    @tree = Tree.new
+  end
+
+  # @return the value at the given trie path
+  def [](*path)
+    tree = @tree[nil, *path]
+    tree.value if tree
+  end
+
+  # @return the top_level Tree for this trie
+  def to_tree
+    @tree
+  end
+
+  # Sets the value for a node path.
+  #
+  # @example
+  #   trie = Trie.new
+  #   trie[:a, :b] = 1
+  #   trie[:a, :b] #=> 1
+  def []=(*path_and_value)
+    value = path_and_value.pop
+    @tree.fill(nil, *path_and_value).value = value
+  end
+end

data/lib/caruby/util/uniquifier.rb

@@ -0,0 +1,30 @@
+# A test utility class to generate id qualifiers.
+class Uniquifier
+  # Returns a relatively unique integral qualifier. Successive calls to this method
+  # within the same time zone spaced more than a millisecond apart return different
+  # integers. Each generated qualifier is greater than the previous by an unspecified
+  # amount.
+  def self.qualifier
+    # the first date that this method could be called
+    @first ||= Date.new(2000, 01, 01)
+    # days as integer + milliseconds as fraction since the first date
+    diff = DateTime.now - @first
+    # shift a tenth of a milli up into the integer portion
+    decimillis = diff * 24 * 60 * 60 * 10000
+    # truncate the fraction
+    decimillis.truncate
+  end
+end
+
+class String
+  # Returns a relatively unique value obtained from the specified base value.
+  # Spaces are removed, e.g.:
+  #   Uniquifier.uniquify('Test Name')
+  # might produce:
+  #   Test_Name_3309388006
+  #
+  # The suffix is generated by {Uniquifier.qualifier}.
+  def uniquify
+    gsub(' ', '_') + "_#{Uniquifier.qualifier}"
+  end
+end

data/lib/caruby/util/validation.rb

@@ -0,0 +1,48 @@
+# Raised when an object fails a validation test.
+class ValidationError < RuntimeError; end
+
+class Object
+  # Returns whether this object is nil, false, empty, or a whitespace string.
+  # For example, "", "   ", +nil+, [], and {} are blank.
+  #
+  # This method is borrowed from Rails ActiveSupport.
+  def blank?
+    respond_to?(:empty?) ? empty? : !self
+  end
+
+  # Returns whether this object is nil, empty, or a whitespace string.
+  # For example, "", "   ", +nil+, [], and {} return +true+.
+  #
+  # This method differs from blank? in that +false+ is an allowed value.
+  def nil_or_empty?
+    nil? or (respond_to?(:empty?) and empty?)
+  end
+end
+
+module Validation
+  # A Validator is a procedure which responds to the +validate(value)+ method.
+  class Validator < Proc
+    alias :validate :call
+  end
+
+  # Validates that each key value in the value_type_assns value => type hash is an instance of the associated class.
+  #
+  # Raises ValidationError if the value is missing.
+  # Raises TypeError if the value is not the specified type.
+  def validate_type(value_type_assns)
+    TYPE_VALIDATOR.validate(value_type_assns)
+  end
+
+  private
+
+  def self.create_type_validator
+    Validator.new do |value_type_assns|
+      value_type_assns.each do |value, type|
+        raise ArgumentError.new("Missing #{type.name} argument") if value.nil?
+        raise TypeError.new("Unsupported argument type; expected: #{type.name} found: #{value.class.name}") unless type === value
+      end
+    end
+  end
+
+  TYPE_VALIDATOR = create_type_validator
+end

data/lib/caruby/util/version.rb

@@ -0,0 +1,56 @@
+# A Version is an Array of version major and minor components that is comparable to
+# another version identifier based on a precedence relationship.
+class Version < Array
+  include Comparable
+
+  attr_reader :predecessor
+
+  # Creates a new Version from the given version components and optional predecessor.
+  #
+  # @example
+  #   alpha = Version.new(1, '1alpha')
+  #   Version.new(1, 1, alpha) > alpha #=> true
+  def initialize(*params)
+    @predecessor = params.pop if self.class === params.last
+    super(params)
+  end
+
+  # Returns the comparison of this version identifier to the other version identifier as follows:
+  # * if this version can be compared to other via the predecessor graph, then return that comparison result
+  # * otherwise, return a component-wise comparison
+  #
+  # @example
+  #   beta = Version.new(1, '1beta')
+  #   Version.new(1) < beta > #=> true
+  #   Version.new(1, 1) < beta #=> true
+  #   Version.new(1, 1, beta) > beta #=> true
+  def <=>(other)
+    return 0 if equal?(other)
+    raise ArgumentError.new("Comparand is not a #{self.class}: #{other}") unless self.class === other
+    return -1 if other.predecessor == self
+    return 1 unless predecessor.nil? or predecessor < other
+    each_with_index do |component, index|
+      return 1 unless index < other.length
+      other_component = other[index]
+      if String === other_component then
+        component = component.to_s
+      elsif String === component
+        other_component = other_component.to_s
+      end
+      cmp = (component <=> other_component)
+      return cmp unless cmp.zero?
+    end
+    length < other.length ? -1 : 0
+  end
+end
+
+class String
+  # Returns this String as a Version.
+  #
+  # @example
+  #   "1.2.1alpha".to_version #=> [1, 2, "1alpha"]
+  def to_version
+    components = split('.').map { |component| component =~ /[\D]/ ? component : component.to_i }
+    Version.new(*components)
+  end
+end

data/lib/caruby/util/visitor.rb

@@ -0,0 +1,351 @@
+require 'caruby/util/collection'
+require 'caruby/util/options'
+
+# Enumerator overwrites to_enum, so include it first
+require 'enumerator'
+require 'generator'
+
+# Error raised on a visit failure.
+class VisitError < RuntimeError; end
+
+# Visitor traverses items and applies an operation, e.g.:
+#   class Node
+#     attr_accessor :children, :value
+#     def initialize(value, parent=nil)
+#       @value = value
+#       @children = []
+#       @parent = parent
+#       @parent.children << self if @parent
+#     end
+#   end
+#   parent = Node.new(1)
+#   child = Node.new(2, parent)
+#   multiplier = 2
+#   Visitor.new { |node| node.children }.visit(parent) { |node| node.value *= multiplier } #=> 2
+#   parent.value #=> 2
+#   child.value #=> 4
+#
+# The visit result is the result of evaluating the operation block on the initial visited node.
+# Visiting a collection returns an array of the result of visiting each member of the collection,
+# e.g. augmenting the preceding example:
+#   parent2 = Node.new(3)
+#   child2 = Node.new(4, parent2)
+#   Visitor.new { |node| node.children }.visit([parent, parent2]) { |node| node.value *= multiplier } #=> [2, 6]
+# Each visit captures the visit result in the +visited+ hash, e.g.:
+#   parent = Node.new(1)
+#   child = Node.new(2, parent)
+#   visitor = Visitor.new { |node| node.children }
+#   visitor.visit([parent]) { |node| node.value += 1 }
+#   parent.value #=> 2
+#   visitor.visited[parent] #=> 2
+#   child.value #=> 3
+#   visitor.visited[child] #=> 3
+#
+# A +return+ from the operation block terminates the visit and exits from the defining scope with the block return value,
+# e.g. given the preceding example:
+#   def increment(parent, limit)
+#     Visitor.new { |node| node.children }.visit(parent) { |node| node.value < limit ? node.value += 1 : return }
+#   end
+#   increment(parent, 2) #=> nil
+#   parent.value #=> 2
+#   child.value #=> 2
+#
+# The to_enum method allows navigator iteration, e.g.:
+#   Visitor.new { |node| node.children }.to_enum(parent).detect { |node| node.value == 2 }
+class Visitor
+
+  attr_reader :options, :visited, :lineage, :cycles
+
+  # Creates a new Visitor which traverses the child objects returned by the navigator block.
+  # The navigator block takes a parent argument and returns the children to visit. If the block
+  # return value is not nil and not a collection, then the returned object is visited. A nil or
+  # empty child is not visited.
+  #
+  # options is a symbol => value hash. A Symbol argument _symbol_ is the same as +{+_symbol_+=>true}+.
+  # Supported options include the follwing:
+  #
+  # The value of :depth_first can be +true+, +false+ or a Proc. If the value is a Proc, then
+  # value determines whether a child is visited depth-first. See the {#visit} method for more information.
+  #
+  # If the the :visited option is set, then the visited nodes are recorded in the :visited option hash.
+  # In that case, the {#visit} call does not clear the visited hash.
+  #
+  # If the :operator option is set, then the visit operator block is called when a node is visited.
+  # The operator block argument is the visited node.
+  #
+  # @param [Symbol, {Symbol => Object}] options the visit options. A symbol argument is the same
+  #   as symbol => true
+  # @option options [String] :depth_first depth-first traversal
+  # @option options [Hash] :visited the hash to use when recording visited node => value associations
+  # @option options [Proc] :operator the visit operator block
+  # @option options [String] :prune_cycle flag indicating whether to exclude cycles to the root in a visit
+  # @yield [parent] the parent being visited
+  def initialize(options=nil, &navigator)
+    @navigator = navigator
+    @options = Options.to_hash(options)
+    @depth_first_flag = @options[:depth_first]
+    @visited = @options[:visited] || {}
+    @prune_cycle_flag = @options[:prune_cycle]
+    @lineage = []
+    @cycles = []
+    @exclude = Set.new
+  end
+
+  # Navigates to node and the children returned by this Visitor's navigator block.
+  # Applies the optional operator block to each child node if the block is given to this method.
+  # Returns the result of the operator block if given, or the node itself otherwise.
+  #
+  # The nodes to visit from a parent node are determined in the following sequence:
+  # * Return if the parent node has already been visited.
+  # * If depth_first, then call the navigator block defined in the initializer on
+  #   the parent node and visit each child node.
+  # * Visit the parent node.
+  # * If not depth-first, then call the navigator block defined in the initializer
+  #   on the parent node and visit each child node.
+  # The :depth option value constrains child traversal to that number of levels.
+  #
+  # This method first clears the _visited_ hash, unless the :visited option was set in the initializer.
+  #
+  # @param node the root object to visit
+  # @yield [visited] an operator applied to each visited object
+  # @yieldparam visited the object currently being visited
+  # @return the result of the yield block on node, or node itself if no block is given
+  def visit(node, &operator)
+    visit_root(node, &operator)
+  end
+
+  # @param node the node to check
+  # @return whether the node was visited
+  def visited?(node)
+    @visited.has_key?(node)
+  end
+
+  # @return the top node visited
+  def root
+    @lineage.first
+  end
+
+  # @return the current node being visited
+  def current
+    @lineage.last
+  end
+
+  # @return the node most recently passed as an argument to this visitor's navigator block, or nil if
+  #   visiting the first node
+  def parent
+    @lineage[-2]
+  end
+
+  # @return [Enumerable] iterator over each visited node
+  def to_enum(node)
+    # could use Generator, but that results in dire behavior on any error by crashing with an elided Java lineage trace
+    VisitorEnumerator.new(self, node)
+  end
+
+  # Returns a new visitor that traverses a collection of parent nodes in lock-step fashion using this visitor.
+  # The synced {#visit} method applies the visit operator block to an array of child nodes taken
+  # from each parent node, e.g. given the class documentation example:
+  #   parent1 = Node.new(1)
+  #   child11 = Node.new(2, parent1)
+  #   child12 = Node.new(3, parent1)
+  #   parent2 = Node.new(1)
+  #   child21 = Node.new(3, parent2)
+  #   Visitor.new { |node| node.children }.sync.enum.to_a #=> [
+  #    [parent1, parent2],
+  #    [child11, child21],
+  #    [child12, nil]
+  #   ]
+  #
+  # By default, the children are grouped in enumeration order. If a block is given to this
+  # method, then the block is called to match child nodes, e.g. using the above example:
+  #   visitor = Visitor.new { |node| node.children }
+  #   synced = visitor.sync { |node, others| others.detect { |other| node.value == other.value }
+  #   synced.enum.to_a #=> [
+  #     [parent1, parent2],
+  #     [child11, nil],
+  #     [child12, child21]
+  #   ]
+  #
+  # @yield [node, others] matches node in others (optional)
+  # @yieldparam [Resource] node the visited node to match
+  # @yieldparam [<Resource>] the candidates for matching the node
+  def sync(&matcher) # :yields: node, others
+    SyncVisitor.new(self, &matcher)
+  end
+
+  # Returns a new Visitor which determines which nodes to visit by applying the given block
+  # to this visitor, e.g.:
+  #   Visitor.new { |node| node.children }.filter { |parent, children| children.first if parent.age >= 18 }
+  # navigates to the first child of parents 18 or older.
+  #
+  # The filter block arguments consist of a parent node and an array of children nodes for the parent.
+  # The  block can return nil, a single node to visit or a collection of nodes to visit.
+  #
+  # @return [Visitor] the filter visitor
+  # @yield [parent, children] the filter to select which of the children to visit next
+  # @yieldparam parent the currently visited node
+  # @yieldparam children the nodes slated by this Visitor to visit next
+  # @raise [ArgumentError] if a block is not given to this method
+  def filter
+    raise ArgumentError.new("Filter block not given to visitor filter method") unless block_given?
+    Visitor.new(@options) { |node| yield(node, node_children(node)) }
+  end
+
+  protected
+
+  # Resets this visitor's state in preparation for a new visit.
+  def clear
+    # clear the lineage
+    @lineage.clear
+    # if the visited hash is not shared, then clear it
+    @visited.clear unless @options.has_key?(:visited)
+    # clear the cycles
+    @cycles.clear
+  end
+
+  # Sets the visited hash.
+  def visited=(hash)
+    @visited = hash ||= {}
+  end
+
+  # Visits the given node using the block given to this method.
+  # The default block returns node.
+  def visit_node(node)
+    @visited[node] = block_given? ? yield(node) : node
+  end
+
+  # Returns the children to visit for the given node.
+  def node_children(node)
+    children = @navigator.call(node)
+    return Array::EMPTY_ARRAY if children.nil?
+    Enumerable === children ? children.to_a.compact : [children]
+  end
+
+  private
+
+  # Visits the root node and all descendants.
+  def visit_root(node, &operator)
+    clear
+    prune_cycle_nodes(node) if @prune_cycle_flag
+    # visit the root node
+    visit_recursive(node, &operator)
+  end
+
+  # Excludes the internal nodes in cycles starting and ending at the given root.
+  def prune_cycle_nodes(root)
+    @exclude.clear
+    # visit the root, which will detect cycles, and remove the visited nodes afterwords
+    @prune_cycle_flag = false
+    to_enum(root).collect.each { |node| @visited.delete(node) }
+    @prune_cycle_flag = true
+    # add each cyclic internal node to the exclude list
+    @cycles.each { |cycle| cycle[1...-1].each { |node| @exclude << node } if cycle.first == root }
+  end
+
+  def visit_recursive(node, &operator)
+    return if node.nil? or @exclude.include?(node)
+    # return the visited value if the node has already been visited
+    if @visited.has_key?(node) then
+      #capture a cycle
+      index = @lineage.index(node)
+      if index then
+        cycle = @lineage[index..-1] << node
+        @cycles << cycle
+      end
+      return @visited[node]
+    end
+    # return nil if the node has not been visited but has been navigated in a depth-first visit
+    return if @lineage.include?(node)
+    visit_node_and_children(node, &operator)
+  end
+
+  def visit_node_and_children(node, &operator)
+    # set the current node
+    @lineage.push(node)
+    # if depth-first, then visit the children before the current node
+    visit_children(node, &operator) if @depth_first_flag
+    # visit the current node
+    result = visit_node(node, &operator)
+    # if not depth-first, then visit the children after the current node
+    visit_children(node, &operator) unless @depth_first_flag
+    @lineage.pop
+    # return the visit result
+    result
+  end
+
+  def visit_children(node, &operator)
+    children = node_children(node)
+    children.each { |child| visit_recursive(child, &operator) }
+  end
+
+  class VisitorEnumerator
+    include Enumerable
+
+    def initialize(visitor, node)
+      @visitor = visitor
+      @root = node
+    end
+
+    def each
+      @visitor.visit(@root) { |node| yield(node) }
+    end
+  end
+
+  class SyncVisitor < Visitor
+    # @param [Visitor] visitor the Visitor which will visit synchronized input
+    # @yield (see Visitor#sync)
+    def initialize(visitor, &matcher)
+      # the next node to visit is an array of child node pairs matched by the given matcher block
+      super() { |nodes| match_children(visitor, nodes, &matcher) }
+    end
+
+    # Visits the given pair of nodes.
+    #
+    # Raises ArgumentError if nodes does not consist of either two node arguments or one two-item Array
+    # argument.
+    def visit(*nodes)
+      if nodes.size == 1 then
+        nodes = nodes.first
+        raise ArgumentError.new("Sync visitor requires a pair of entry nodes.") unless nodes.size == 2
+      end
+      super(nodes)
+    end
+
+    # Returns an Enumerable which applies the given block to each matched node starting at the given nodes.
+    #
+    # Raises ArgumentError if nodes does not consist of either two node arguments or one two-item Array
+    # argument.
+    def to_enum(*nodes)
+      if nodes.size == 1 then
+        nodes = nodes.first
+        raise ArgumentError.new("Sync visitor requires a pair of entry nodes.") unless nodes.size == 2
+      end
+      super(nodes)
+    end
+
+    private
+
+    # Returns an array of arrays of matched children from the given parent nodes. The children are matched
+    # using the block given to this method, if supplied, or by index otherwise.
+    #
+    # @see #sync a usage example
+    def match_children(visitor, nodes) # :yields: child, others
+      # the parent nodes
+      p1, p2 = nodes
+      # this visitor's children
+      c1 = visitor.node_children(p1)
+      c2 = p2 ? visitor.node_children(p2) : []
+
+      # apply the matcher block on each of this visitor's children and the other children.
+      # if no block, then group the children by index, which is the transpose of the array of children arrays.
+      if block_given? then
+        c1.map { |c| [c, yield(c, c2)] }
+      else
+        # ensure that both children arrays are the same size
+        others = c2.size <= c1.size ? c2.fill(nil, c2.size...c1.size) : c2[0, c1.size]
+        # the children grouped by index is the transpose of the array of children arrays
+        [c1, others].transpose
+      end
+    end
+  end
+end