type_balancer 0.1.0

data/lib/type_balancer/alternating_filler.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  # Fills gaps by alternating between primary and secondary items
+  class AlternatingFiller
+    def initialize(collection, primary_items, secondary_items)
+      @collection = collection
+      @primary_items = primary_items
+      @secondary_items = secondary_items
+    end
+
+    def self.fill(collection, positions, primary_items, secondary_items)
+      new(collection, primary_items, secondary_items).fill_gaps(positions)
+    end
+
+    def fill_gaps(positions)
+      return positions if positions.compact.size == positions.size
+      return [] if positions.empty?
+
+      filled_positions = positions.dup
+      use_primary = true
+
+      positions.each_with_index do |pos, idx|
+        next unless pos.nil?
+
+        item = select_next_item(use_primary)
+        break unless item
+
+        filled_positions[idx] = item
+        use_primary = !use_primary
+      end
+
+      filled_positions
+    end
+
+    private
+
+    def select_next_item(use_primary)
+      if (use_primary || @secondary_items.empty?) && !@primary_items.empty?
+        @primary_items.shift
+      elsif !@secondary_items.empty?
+        @secondary_items.shift
+      end
+    end
+  end
+end

data/lib/type_balancer/balancer.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  # Main class responsible for balancing items in a collection based on their types.
+  # It uses a distribution calculator to determine optimal positions for each type
+  # and a gap filler strategy to place items in the final sequence.
+  class Balancer
+    BATCH_SIZE = 500 # Process items in batches of 500 for better performance
+
+    def initialize(collection, type_field: :type, types: nil, distribution_calculator: nil)
+      @collection = collection
+      @type_field = type_field
+      @types = types || extract_types
+      @distribution_calculator = distribution_calculator || Distributor
+    end
+
+    def call
+      return [] if @collection.empty?
+
+      if @collection.size <= BATCH_SIZE
+        process_single_batch(@collection)
+      else
+        process_multiple_batches
+      end
+    end
+
+    private
+
+    def process_single_batch(items)
+      # Group items by type
+      items_by_type = items.group_by { |item| get_type(item) }
+
+      # Calculate ratios based on type order and counts
+      ratios = calculate_ratios(items_by_type)
+
+      # Calculate positions for each type
+      positions_by_type = calculate_positions_by_type(items_by_type, ratios, items.size)
+
+      # Map items to their balanced positions
+      balanced_items = place_items_in_positions(items_by_type, positions_by_type, items.size)
+
+      # Fill any gaps with remaining items
+      fill_gaps(balanced_items, items)
+    end
+
+    def process_multiple_batches
+      result = []
+      @collection.each_slice(BATCH_SIZE) do |batch|
+        result.concat(process_single_batch(batch))
+      end
+      result
+    end
+
+    def calculate_positions_by_type(items_by_type, ratios, total_count)
+      positions_by_type = {}
+
+      @types.each_with_index do |type, index|
+        items = items_by_type[type] || []
+        ratio = ratios[index]
+        positions = @distribution_calculator.calculate_target_positions(total_count, items.size, ratio)
+        positions_by_type[type] = positions
+      end
+
+      positions_by_type
+    end
+
+    def place_items_in_positions(items_by_type, positions_by_type, total_count)
+      balanced_items = Array.new(total_count)
+
+      @types.each do |type|
+        items = items_by_type[type] || []
+        positions = positions_by_type[type] || []
+
+        items.each_with_index do |item, index|
+          pos = positions[index]
+          next unless pos && pos < total_count && balanced_items[pos].nil?
+
+          balanced_items[pos] = item
+        end
+      end
+
+      balanced_items
+    end
+
+    def fill_gaps(balanced_items, original_items)
+      # Fill any gaps with remaining items
+      remaining_items = original_items.reject { |item| balanced_items.include?(item) }
+      empty_positions = balanced_items.each_index.select { |i| balanced_items[i].nil? }
+
+      empty_positions.each_with_index do |pos, idx|
+        break unless idx < remaining_items.size
+
+        balanced_items[pos] = remaining_items[idx]
+      end
+
+      balanced_items.compact
+    end
+
+    def calculate_ratios(_items_by_type)
+      case @types.size
+      when 1
+        [1.0]
+      when 2
+        [0.6, 0.4]
+      else
+        # First type gets 0.4, rest split remaining 0.6 evenly
+        remaining = (0.6 / (@types.size - 1).to_f).round(6)
+        [0.4] + Array.new(@types.size - 1, remaining)
+      end
+    end
+
+    def get_type(item)
+      if item.respond_to?(@type_field)
+        item.send(@type_field)
+      elsif item.respond_to?(:[])
+        item[@type_field] || item[@type_field.to_s]
+      else
+        raise Error, "Cannot access type field '#{@type_field}' on item #{item}"
+      end
+    end
+
+    def extract_types
+      TypeBalancer.extract_types(@collection, @type_field)
+    end
+  end
+end

data/lib/type_balancer/calculator.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  # Handles calculation of positions for balanced item distribution
+  class PositionCalculator
+    # Represents a batch of position calculations
+    class PositionBatch
+      attr_reader :total_count, :ratio, :available_items
+
+      def initialize(total_count:, ratio:, available_items: nil)
+        @total_count = total_count
+        @ratio = ratio
+        @available_items = available_items
+      end
+
+      def valid?
+        valid_basic_inputs? && valid_available_items?
+      end
+
+      def target_count
+        @target_count ||= (total_count * ratio).round
+      end
+
+      private
+
+      def valid_basic_inputs?
+        total_count.positive? && ratio.positive? && ratio <= 1.0
+      end
+
+      def valid_available_items?
+        return true if available_items.nil?
+
+        valid_array? && valid_indices?
+      end
+
+      def valid_array?
+        available_items.is_a?(Array) && available_items.all? { |i| i.is_a?(Integer) }
+      end
+
+      def valid_indices?
+        available_items.none? { |i| i.negative? || i >= total_count }
+      end
+    end
+
+    class << self
+      # Calculate positions for a single input (legacy support)
+      def calculate_positions(total_count:, ratio:, available_items: nil)
+        return [] if total_count.zero? || ratio.zero?
+        return nil unless valid_inputs?(total_count, ratio)
+
+        target_count = (total_count * ratio).round
+        return [] if target_count.zero?
+
+        if available_items
+          calculate_positions_with_available_items(total_count, target_count, available_items)
+        else
+          calculate_evenly_spaced_positions(total_count, target_count, ratio)
+        end
+      end
+
+      private
+
+      def calculate_positions_with_available_items(total_count, target_count, available_items)
+        return nil if available_items.any? { |pos| pos >= total_count }
+        return available_items.take(target_count) if available_items.size <= target_count
+
+        if target_count == 1
+          [available_items.first]
+        else
+          distribute_available_positions(available_items, target_count)
+        end
+      end
+
+      def distribute_available_positions(available_items, target_count)
+        indices = (0...target_count).map do |i|
+          ((available_items.size - 1) * i.fdiv(target_count - 1)).round
+        end
+        indices.map { |i| available_items[i] }
+      end
+
+      def calculate_evenly_spaced_positions(total_count, target_count, ratio)
+        return [0] if target_count == 1
+        return handle_two_thirds_case(total_count) if two_thirds_ratio?(ratio, total_count)
+
+        (0...target_count).map do |i|
+          ((total_count - 1) * i.fdiv(target_count - 1)).round
+        end
+      end
+
+      def two_thirds_ratio?(ratio, total_count)
+        (ratio - (2.0 / 3.0)).abs < 1e-6 && total_count == 3
+      end
+
+      def handle_two_thirds_case(_total_count)
+        [0, 1]
+      end
+
+      def valid_inputs?(total_count, ratio)
+        total_count >= 0 && ratio >= 0 && ratio <= 1.0
+      end
+    end
+  end
+
+  # Main calculator that handles type-based balancing of items
+  class Calculator
+    DEFAULT_TYPE_ORDER = %w[video image strip article].freeze
+
+    def initialize(items, type_field: :type, types: nil)
+      raise ArgumentError, 'Items cannot be nil' if items.nil?
+      raise ArgumentError, 'Type field cannot be nil' if type_field.nil?
+
+      @items = items
+      @type_field = type_field
+      @types = types || extract_types
+    end
+
+    def call
+      return [] if @items.empty?
+
+      validate_items!
+
+      items_by_type = @types.map { |type| @items.select { |item| item[@type_field].to_s == type } }
+
+      # Calculate target positions for each type
+      target_positions = calculate_target_positions(items_by_type)
+
+      # Place items at their target positions
+      place_items_at_positions(items_by_type, target_positions)
+    end
+
+    private
+
+    def validate_items!
+      @items.each do |item|
+        raise ArgumentError, 'All items must have a type field' unless item.key?(@type_field)
+        raise ArgumentError, 'Type values cannot be empty' if item[@type_field].to_s.strip.empty?
+      end
+    end
+
+    def extract_types
+      types = @items.map { |item| item[@type_field].to_s }.uniq
+      DEFAULT_TYPE_ORDER.select { |type| types.include?(type) } + (types - DEFAULT_TYPE_ORDER)
+    end
+
+    def calculate_target_positions(items_by_type)
+      total_count = @items.size
+      available_positions = (0...total_count).to_a
+
+      items_by_type.map.with_index do |_items, index|
+        ratio = calculate_ratio(items_by_type.size, index)
+        target_count = (total_count * ratio).round
+
+        # Calculate positions based on ratio and total count
+        if target_count == 1
+          [index]
+        else
+          # For better distribution, calculate positions based on available slots
+          step = available_positions.size.fdiv(target_count)
+          positions = (0...target_count).map do |i|
+            pos_index = (i * step).round
+            available_positions[pos_index]
+          end
+
+          # Remove used positions from available ones
+          positions.each { |pos| available_positions.delete(pos) }
+          positions
+        end
+      end
+    end
+
+    def calculate_ratio(type_count, index)
+      case type_count
+      when 1 then 1.0
+      when 2 then index.zero? ? 0.6 : 0.4
+      else
+        # For 3+ types: first type gets 0.4, rest split remaining 0.6 evenly
+        remaining = (0.6 / (type_count - 1).to_f).round(6)
+        index.zero? ? 0.4 : remaining
+      end
+    end
+
+    def place_items_at_positions(items_by_type, target_positions)
+      result = Array.new(@items.size)
+      used_items = place_items_at_target_positions(items_by_type, target_positions, result)
+      fill_empty_slots(result, used_items)
+      result.compact
+    end
+
+    def place_items_at_target_positions(items_by_type, target_positions, result)
+      used_items = []
+      items_by_type.each_with_index do |items, type_index|
+        positions = target_positions[type_index] || []
+        place_type_items(items, positions, result, used_items)
+      end
+      used_items
+    end
+
+    def place_type_items(items, positions, result, used_items)
+      items.take(positions.size).each_with_index do |item, item_index|
+        pos = positions[item_index]
+        next unless pos && result[pos].nil?
+
+        result[pos] = item
+        used_items << item
+      end
+    end
+
+    def fill_empty_slots(result, used_items)
+      remaining_items = @items - used_items
+      empty_slots = result.each_index.select { |i| result[i].nil? }
+      empty_slots.zip(remaining_items).each do |slot, item|
+        break unless item
+
+        result[slot] = item
+      end
+    end
+  end
+end

data/lib/type_balancer/distribution_calculator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  # Calculates the optimal distribution of items by type in a sequence.
+  # For each type, it determines the ideal positions where items of that type
+  # should be placed to achieve a balanced distribution.
+  class DistributionCalculator
+    def initialize(target_ratio = 0.2)
+      @target_ratio = target_ratio
+    end
+
+    def calculate_target_positions(total_count, available_items_count, target_ratio = @target_ratio)
+      # Use the C extension for the calculation
+      TypeBalancer::Distributor.calculate_target_positions(
+        total_count,
+        available_items_count,
+        target_ratio
+      )
+    end
+  end
+end

data/lib/type_balancer/distributor.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  module Distributor
+    class << self
+      def calculate_target_positions(total_count, available_count, ratio, available_items = nil)
+        # Input validation
+        return [] if total_count <= 0 || available_count <= 0 || ratio <= 0 || ratio > 1
+        return [] if available_count > total_count
+
+        # Calculate target count
+        target_count = (total_count * ratio).ceil
+        target_count = [target_count, available_count].min
+
+        # Special cases
+        return [] if target_count.zero?
+        return [available_items&.first || 0] if target_count == 1
+
+        # If specific positions are available, use those
+        if available_items
+          # Ensure available_items are valid
+          available_items = available_items.select { |pos| pos >= 0 && pos < total_count }.sort
+          return [] if available_items.empty?
+
+          # If we have fewer available positions than target count, use what we have
+          target_count = [target_count, available_items.size].min
+
+          # Calculate spacing within available positions
+          return [available_items.first] unless target_count > 1
+
+          step = (available_items.size - 1).to_f / (target_count - 1)
+          return target_count.times.map { |i| available_items[(i * step).round] }
+
+        end
+
+        # Calculate spacing for the general case
+        spacing = total_count.to_f / target_count
+
+        # Generate positions
+        positions = Array.new(target_count)
+        target_count.times do |i|
+          # Calculate ideal position
+          ideal_pos = i * spacing
+
+          # Round to nearest integer, ensuring we don't exceed bounds
+          pos = ideal_pos.round
+          pos = [pos, total_count - 1].min
+          pos = [pos, 0].max
+
+          positions[i] = pos
+        end
+
+        # Ensure positions are unique and sorted
+        positions.uniq!
+        positions.sort!
+
+        positions
+      end
+    end
+  end
+end

data/lib/type_balancer/ordered_collection_manager.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  # Manages an ordered collection of items, providing methods to place items
+  # at specific positions and fill gaps using different strategies.
+  # This class acts as a facade for the gap filling functionality.
+  class OrderedCollectionManager
+    def initialize(size)
+      @collection = Array.new(size)
+      @item_order = [] # Track items in their original order
+      @size = size
+    end
+
+    def place_at_positions(items, positions)
+      # Store items in their original order
+      @item_order.concat(items)
+
+      # Place items at their positions
+      positions.each_with_index do |pos, i|
+        break if i >= items.size
+
+        @collection[pos] = items[i] if pos >= 0 && pos < @size
+      end
+    end
+
+    alias place_items_at_positions place_at_positions
+
+    def fill_gaps_alternating(primary_items, secondary_items)
+      # Add new items to the order list before filling gaps
+      @item_order.concat(primary_items)
+      @item_order.concat(secondary_items)
+
+      # Find empty positions
+      empty_positions = find_empty_positions
+      return if empty_positions.empty?
+
+      # Create a copy of the collection for filling
+      collection_copy = @collection.dup
+
+      # Use C extension for alternating filling
+      result = TypeBalancer::AlternatingFiller.fill(
+        collection_copy,
+        empty_positions,
+        primary_items,
+        secondary_items
+      )
+
+      # Update collection if we got a valid result
+      @collection = result if result.is_a?(Array)
+    end
+
+    def fill_remaining_gaps(items_arrays)
+      # Add all new items to the order list before filling gaps
+      items_arrays.each { |items| @item_order.concat(items) }
+
+      # Find empty positions
+      empty_positions = find_empty_positions
+      return if empty_positions.empty?
+
+      # Create a copy of the collection for filling
+      collection_copy = @collection.dup
+
+      # Use C extension for sequential filling
+      result = TypeBalancer::SequentialFiller.fill(
+        collection_copy,
+        empty_positions,
+        items_arrays
+      )
+
+      # Update collection if we got a valid result
+      @collection = result if result.is_a?(Array)
+    end
+
+    def result
+      # If no items have been placed, return an empty array
+      return [] if @item_order.empty?
+
+      # Get all non-nil items from the collection
+      non_nil_items = @collection.compact
+
+      # Return empty array if no items were successfully placed
+      return [] if non_nil_items.empty?
+
+      # Return all items that were successfully placed, in their original order
+      @item_order.select { |item| non_nil_items.include?(item) }
+    end
+
+    private
+
+    def find_empty_positions
+      # Find all positions that are nil and within bounds
+      (0...@size).select { |i| @collection[i].nil? }
+    end
+  end
+end

data/lib/type_balancer/sequential_filler.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  # Fills gaps in positions sequentially with remaining items
+  class SequentialFiller
+    def initialize(collection, items_arrays)
+      @collection = collection
+      @items_arrays = items_arrays
+    end
+
+    def self.fill(collection, positions, items_arrays)
+      new(collection, items_arrays).fill_gaps(positions)
+    end
+
+    def fill_gaps(positions)
+      return [] if positions.nil? || positions.empty?
+      return positions if positions.compact.size == positions.size
+
+      remaining_items = @items_arrays.flatten
+      filled_positions = positions.dup
+
+      positions.each_with_index do |pos, idx|
+        next unless pos.nil?
+        break if remaining_items.empty?
+
+        filled_positions[idx] = remaining_items.shift
+      end
+
+      filled_positions
+    end
+  end
+end

data/lib/type_balancer/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TypeBalancer
+  VERSION = '0.1.0'
+end

data/lib/type_balancer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'type_balancer/version'
+require 'type_balancer/calculator'
+
+module TypeBalancer
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  # Load Ruby implementations
+  require_relative 'type_balancer/distribution_calculator'
+  require_relative 'type_balancer/ordered_collection_manager'
+  require_relative 'type_balancer/alternating_filler'
+  require_relative 'type_balancer/sequential_filler'
+  require_relative 'type_balancer/balancer'
+  require_relative 'type_balancer/distributor'
+
+  def self.calculate_positions(total_count:, ratio:, available_items: nil)
+    PositionCalculator.calculate_positions(
+      total_count: total_count,
+      ratio: ratio,
+      available_items: available_items
+    )
+  end
+
+  def self.balance(collection, type_field: :type, type_order: nil)
+    Balancer.new(collection, type_field: type_field, types: type_order).call
+  end
+
+  def self.extract_types(collection, type_field)
+    collection.map do |item|
+      if item.respond_to?(type_field)
+        item.send(type_field)
+      elsif item.respond_to?(:[])
+        item[type_field] || item[type_field.to_s]
+      else
+        raise Error, "Cannot access type field '#{type_field}' on item #{item}"
+      end
+    end.uniq
+  end
+
+  # Error raised when input validation fails
+  class ValidationError < StandardError; end
+end