aoc_rb_helpers 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9049a2637e249afd1d2670f1b4ca3616aa21ef94ae10efb271178693ff16f63
-  data.tar.gz: 485a04d7594ef25fbec3fb2ca19060c8f5699a30fb0845ec9c985a899aae5be4
+  metadata.gz: 1990cde2622df33946ce6131918c215ac548d3b013ed36b57fd980fd0ba7c0ab
+  data.tar.gz: 7070a8add7b5f3bf0b4fa033959ce30624edeac87329a95964e2bade9dbb5741
 SHA512:
-  metadata.gz: 6343e8180d5ab30baecad403c7765b4a666562a713154541c70ee6a602ecaa3253c08a25f89db76d36e4e86371901564b34eb7ba779fbbaa2e011cb543edf10a
-  data.tar.gz: dade32999ee76bbda52f4615cad719ab2dc4ab2209dccf88b6756b0f63d125d7dfe40b76d61e85245c599b472b29e426c5dd110b91c5c3eb46bd8ffd1ab96f84
+  metadata.gz: 402844433642a9dcfd4bcded006ec9eca2d3cc8b18a0016b7d3cc45631b24e54e37315af3cff1d895c511233a167b9cc82ed21f7f942f721cafe016f8ea552d6
+  data.tar.gz: 34f664b1de9a6fd751241afc34445c46cc16ab6cce24f246476799d7915ce4f519f4ac67d22a42b72780c673d5c21fe693c19c42786a23f6b529c19beffa53f8

data/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 - No unreleased changes!
 
+## [0.0.5]
+### Added
+- AocInput#process_each_line - Processes each line of the input data using the provided block
+- Grid#includes_coords? - Returns `true` if the provided coordinates exist within the bounds of the grid
+- Grid#beyond_grid? - Returns `true` if the provided coordinates exceed the bounds of the grid
+- Grid#locate(value) - Returns the first coordinates within the grid containing the given value
+- Grid#locate_all(value) - Returns an array of coordinates for any location within the grid containing the given value
+- Grid#each_cell - Iterates over each cell in the grid
+
+### Changed
+- Grid#cell now returns `nil` if the provided coordinates to not exist within the grid
+- Grid#set_cell nwo returns `nil` if the provided coordinates to not exist within the grid
+
+### Fixed
+- Grid#dup previously returned a new `Grid` instance with the same instance of the `@grid` array within it. Now `@grid` is a unique copy.
+
+## [0.0.4]
+### Added
+- Grid class for working with two-dimensional arrays of data
+- AocInput updated with convenience method for creating a Grid from input
+- AocInput#sections added, for splitting input into multiple sections
+
 ## [0.0.3]
 ### Added
 - Characters `I` and `T` now supported by DotMatrix
@@ -23,6 +45,9 @@ Initial release.
 ### Added
 - Created `AocInput` class with initial helper methods
 
-[Unreleased]: https://github.com/pacso/aoc_rb_helpers/compare/v0.0.2...HEAD
+[Unreleased]: https://github.com/pacso/aoc_rb_helpers/compare/v0.0.5...HEAD
+[0.0.5]: https://github.com/pacso/aoc_rb_helpers/compare/v0.0.4...v0.0.5
+[0.0.4]: https://github.com/pacso/aoc_rb_helpers/compare/v0.0.3...v0.0.4
+[0.0.3]: https://github.com/pacso/aoc_rb_helpers/compare/v0.0.2...v0.0.3
 [0.0.2]: https://github.com/pacso/aoc_rb_helpers/compare/v0.0.1...v0.0.2
 [0.0.1]: https://github.com/pacso/aoc_rb_helpers

data/README.md

@@ -58,13 +58,21 @@ X  X X    X    X    X    X  X   X  X    X  X    X
 ```
 Into the string `CFLELOYFCS`.
 
+### [Grid](https://rubydoc.info/github/pacso/aoc_rb_helpers/Grid)
+Provides helper methods for manipulating end querying two-dimensional grids.
+
+```ruby
+grid = Grid.new([[0, 1], [2, 3]])
+grid.rotate! # => #<Grid:0x0000ffff8f42f8f8 @grid=[[2, 0], [3, 1]]>
+```
+
 ## Examples
 
 Below are some examples of how you can use the features of this gem.
 
 ### Input manipulation
 
-This example solution for 2024 Day 1 shows how the convenience methdos can be used to format the puzzle input:
+This example solution for 2024 Day 1 shows how the convenience methods can be used to format the puzzle input:
 
 ```ruby
 # frozen_string_literal: true
@@ -95,6 +103,14 @@ module Year2024
 end
 ```
 
+Where you have different sections of input which need to be handled differently, you can quickly split them into independent instances of `AocInput`, such as with the pussle from 2024, Day 5:
+
+```ruby
+  page_rules, page_updates = aoc_input.sections
+  page_rules_data = page_rules.multiple_lines.columns_of_numbers("|").data
+  page_updates_data = page_updates.multiple_lines.columns_of_numbers(",").data
+```
+
 ### Decoding printed text
 
 ```ruby

data/lib/aoc_rb_helpers/aoc_input.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Provides input manipulation helper methods.
-# Methods are chainable, and directly modify the parsed view of the input data within the @data instance variable.
+# Methods are chainable, and directly modify the parsed view of the input data within the +@data+ instance variable.
 #
-# Once manipulated as required, the input is accessable from #data
+# Once manipulated as required, the input is accessable using the {#data} method.
 class AocInput
   # Returns a new AocInput initialized with the given puzzle input.
   #
@@ -24,8 +24,8 @@ class AocInput
 
   # Splits the input string into an array of lines.
   #
-  # This method processes `@data` by splitting the input string into multiple lines,
-  # removing trailing newline characters. It modifies `@data` directly and returns `self`
+  # This method processes +@data+ by splitting the input string into multiple lines,
+  # removing trailing newline characters. It modifies +@data+ directly and returns +self+
   # to enable method chaining.
   #
   # @return [AocInput] self
@@ -36,13 +36,33 @@ class AocInput
     self
   end
 
+  # Processes each line of the data using the provided block.
+  #
+  # This method applies the given block to each line in the +@data+ array,
+  # replacing the original +@data+ with the results of the block. The method
+  # returns +self+ to allow method chaining.
+  #
+  # Returns an enumerator if no block is given.
+  #
+  # @yieldparam line [Object, Array<Object>] a single line of the data being processed
+  # @yieldreturn [Object, Array<Object>] the result of processing the line
+  # @return [self] the instance itself, for method chaining
+  # @return [Enumerator] if no block is given
+  def process_each_line
+    return to_enum(__callee__) unless block_given?
+    @data = @data.map do |line|
+      yield line
+    end
+    self
+  end
+
   # Splits each string in the data array into an array of numbers.
   #
-  # This method processes `@data` by splitting each string in the array using the specified delimiter,
-  # then converting each resulting element to an integer. It modifies `@data` directly and enables
-  # chaining by returning `self`.
+  # This method processes +@data+ by splitting each string in the array using the specified delimiter,
+  # then converting each resulting element to an integer. It modifies +@data+ directly and enables
+  # chaining by returning +self+.
   #
-  # @param delimiter [String, nil] the delimiter to be passed to `String#split`
+  # @param delimiter [String, nil] the delimiter to be passed to +String#split+
   # @raise [RuntimeError] if {#multiple_lines} has not been called
   # @return [AocInput] self
   def columns_of_numbers(delimiter = nil)
@@ -57,7 +77,7 @@ class AocInput
   # Transposes the data array.
   #
   # This method can only be called after {columns_of_numbers}.
-  # It directly modifies `@data` by transposing it and returns `self` to allow method chaining.
+  # It directly modifies +@data+ by transposing it and returns +self+ to allow method chaining.
   #
   # @raise [RuntimeError] if {columns_of_numbers} has not been called.
   # @return [AocInput] self
@@ -67,10 +87,10 @@ class AocInput
     self
   end
 
-  # Sorts each array within the `@data` array.
+  # Sorts each array within the +@data+ array.
   #
-  # This method processes `@data` by sorting each nested array in ascending order.
-  # It directly modifies `@data` and returns `self` to enable method chaining.
+  # This method processes +@data+ by sorting each nested array in ascending order.
+  # It directly modifies +@data+ and returns +self+ to enable method chaining.
   #
   # @raise [RuntimeError] if {#columns_of_numbers} has not been called
   # @return [AocInput] self
@@ -80,6 +100,19 @@ class AocInput
     self
   end
 
+  # Returns a new +Grid+ object from the parsed input
+  # @return [Grid] the new grid
+  def to_grid
+    Grid.from_input(@raw_input)
+  end
+
+  # Returns a new +AocInput+ for each section of the raw input, split by the given delimiter.
+  # @param delimiter [String] the string used to split sections
+  # @return [Array<AocInput>] an array of new AocInput instances initialised with each section of the raw input from +self+
+  def sections(delimiter = "\n\n")
+    @sections = @raw_input.split(delimiter).map { |section_input| AocInput.new(section_input) }
+  end
+
   private
   def configure_method_access
     @can_call = {

data/lib/aoc_rb_helpers/grid.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+# Provides helper methods for manipulating end querying two-dimensional grids.
+class Grid
+  # Returns a new {Grid} initialized with the given input.
+  #
+  # @param input [String] the unprocessed input text containing the grid
+  def self.from_input(input)
+    self.new(input.lines(chomp: true).map(&:chars))
+  end
+
+  # Returns a new {Grid} initialized with the provided two-dimensional array.
+  #
+  # @param grid [Array<Array<Object>>] the grid in a two-dimensional array
+  def initialize(grid)
+    @grid = grid
+  end
+
+  # Returns +true+ if the provided coordinates exceed the bounds of the grid; +false+ otherwise.
+  #
+  # @param row [Integer] the row index to test
+  # @param column [Integer] the column index to test
+  # @return [Boolean]
+  # @see #includes_coords?
+  def beyond_grid?(row, column)
+    !includes_coords?(row, column)
+  end
+
+  # Returns +true+ if the provided coordinates exist within the bounds of the grid; +false+ otherwise.
+  #
+  # @param row [Integer] the row index to test
+  # @param column [Integer] the column index to test
+  # @return [Boolean]
+  # @see #beyond_grid?
+  def includes_coords?(row, column)
+    row >= 0 && column >= 0 && row < @grid.length && column < @grid.first.length
+  end
+  alias_method(:within_grid?, :includes_coords?)
+
+  # Returns the value stored at coordinates +(row, column)+ within the grid.
+  #
+  # Returns +nil+ if the provided coordinates do not exist within the grid.
+  #
+  # Row and column numbers are zero-indexed.
+  #
+  # @param row [Integer] the row index of the desired cell
+  # @param column [Integer] the column index of the desired cell
+  # @return [Object] the value at the given coordinates within the grid
+  # @return [nil] if the given coordinates do not exist within the grid
+  # @see #set_cell
+  def cell(row, column)
+    return nil unless includes_coords?(row, column)
+    @grid[row][column]
+  end
+
+  # Updates the cell at coordinates +(row, column)+ with the object provided in +value+; returns the given object.
+  #
+  # Returns +nil+ if the provided coordinates do not exist within the grid.
+  #
+  # @param row [Integer] the row index of the cell you wish to update
+  # @param column [Integer] the column index of the cell you wish to update
+  # @param value [Object] the object to assign to the selected grid cell
+  # @return [Object] the given +value+
+  # @return [nil] if the provided coordinates do not exist within the grid
+  # @see #cell
+  def set_cell(row, column, value)
+    return nil unless includes_coords?(row, column)
+    @grid[row][column] = value
+  end
+
+  # Returns +true+ if the other grid has the same content in the same orientation, +false+ otherwise.
+  #
+  #   grid = Grid.new([1, 2], [3, 4])
+  #   grid == Grid.new([1, 2], [3, 4]) # => true
+  #   grid == Grid.new([0, 1], [2, 3]) # => false
+  #   grid == "non-grid object" # => false
+  #
+  # @param other [Grid] the grid you wish to compare with
+  # @return [Boolean]
+  def ==(other)
+    return false unless other.is_a?(self.class)
+    @grid == other.instance_variable_get(:@grid)
+  end
+
+  # Returns +true+ if the other grid can be rotated into an orientation where it is equal to +self+, +false+ otherwise.
+  #
+  #   grid = Grid.new([1, 2], [3, 4])
+  #   grid == Grid.new([1, 2], [3, 4]) # => true
+  #   grid == Grid.new([3, 1], [4, 2]) # => true
+  #   grid == Grid.new([1, 2], [4, 3]) # => false
+  #   grid == "non-grid object" # => false
+  #
+  # @param other [Grid] the grid you wish to compare with
+  def matches_with_rotations?(other)
+    other.all_rotations.any? { |rotated| self == rotated }
+  end
+
+  # Returns an array of {Grid} objects in all possible rotations, copied from +self+.
+  # @return [Array<Grid>] an array containing four {Grid} objects, one in each possible rotation
+  def all_rotations
+    rotations = []
+    current_grid = self.dup
+
+    4.times do
+      rotations << current_grid.dup
+      current_grid.rotate!
+    end
+
+    rotations
+  end
+
+  # Returns a new {Grid} as a copy of self.
+  # @return [Grid] a copy of +self+
+  def dup
+    self.class.new(@grid.map { |row| row.map { |cell| cell } })
+  end
+
+  # Updates +self+ with a rotated grid and returns +self+.
+  #
+  # Will rotate in a clockwise direction by default. Will rotate in an anticlockwise direction if passed
+  # a param which is not +:clockwise+.
+  #
+  # @param direction [Symbol]
+  # @return [self]
+  def rotate!(direction = :clockwise)
+    @grid = direction == :clockwise ? @grid.transpose.map(&:reverse) : @grid.map(&:reverse).transpose
+    self
+  end
+
+  # Calls the given block with each subgrid from +self+ with the size constraints provided; returns +self+.
+  #
+  # Returns an enumerator if no block is given
+  #
+  # @return [Enumerator] if no block is given.
+  # @return [self] after processing the provided block
+  # @yield [subgrid] calls the provided block with each subgrid as a new {Grid} object
+  # @yieldparam subgrid [Grid] a new {Grid} object containing a subgrid from the main grid
+  def each_subgrid(rows, columns)
+    return to_enum(__callee__, rows, columns) unless block_given?
+    @grid.each_cons(rows) do |rows|
+      rows[0].each_cons(columns).with_index do |_, col_index|
+        yield Grid.new(rows.map { |row| row[col_index, columns] })
+      end
+    end
+
+    self
+  end
+
+  # Returns an array containing all of the subgrids of the specified dimensions.
+  # @param rows [Integer] the number of rows each subgrid should contain.
+  #   Must be greater than zero and less than or equal to the number of rows in the grid.
+  # @param columns [Integer] the number of columns each subgrid should contain.
+  #   Must be greater than zero and less than or equal to the number of columns in the grid.
+  # @raise [ArgumentError] if the specified rows or columns are not {Integer} values, or exceed the grid's dimensions.
+  # @return [Array<Grid>]
+  def subgrids(rows, columns)
+    raise ArgumentError unless rows.is_a?(Integer) && rows > 0 && rows <= @grid.length
+    raise ArgumentError unless columns.is_a?(Integer) && columns > 0 && columns <= @grid.first.length
+    each_subgrid(rows, columns).to_a
+  end
+
+  # Returns the first coordinates within the grid containing the given value. Returns +nil+ if not found.
+  #
+  # If given an array of values, the first coordinate matching any of the given values will be returned.
+  #
+  # Searches the grid from top left (+[0, 0]+) to bottom right, by scanning each row.
+  #
+  # @param value [Object, Array<Object>] the value, or array of values, to search for.
+  # @return [Array<Integer>] if the value was located, its coordinates are returned in a 2-item array where:
+  #   - The first item is the row index.
+  #   - The second item is the column index.
+  # @return [nil] if the value was not located
+  def locate(value)
+    result = nil
+    if value.is_a? Array
+      value.each do |e|
+        result = locate(e)
+        break unless result.nil?
+      end
+    else
+      result = locate_value value
+    end
+    result
+  end
+
+  # Returns an array of coordinates for any location within the grid containing the given value.
+  #
+  # If given an array of values, the coordinates of any cell matching any of the given values will be returned.
+  #
+  # @param value [Object, Array<Object>] the value, or array of values, to search for.
+  # @return [Array<Array<Integer>>] an array of coordinates. Each coordinate is a 2-item array where:
+  #   - The first item is the row index.
+  #   - The second item is the column index.
+  def locate_all(value)
+    locations = []
+
+    if value.is_a? Array
+      @grid.each_with_index.select { |row, _r_index| value.any? { |el| row.include?(el) } }.each do |row, r_index|
+        row.each_with_index do |cell, c_index|
+          locations << [r_index, c_index] if value.include?(cell)
+        end
+      end
+    else
+      @grid.each_with_index.select { |row, _r_index| row.include?(value) }.each do |row, r_index|
+        row.each_with_index do |cell, c_index|
+          locations << [r_index, c_index] if cell == value
+        end
+      end
+    end
+
+    locations
+  end
+
+  # Iterates over each cell in the grid.
+  #
+  # When a block is given, passes the coordinates and value of each cell to the block; returns +self+:
+  #     g = Grid.new([
+  #           ["a", "b"],
+  #           ["c", "d"]
+  #         ])
+  #     g.each_cell { |coords, value| puts "#{coords.inspect} => #{value}" }
+  #
+  # Output:
+  #     [0, 0] => a
+  #     [0, 1] => b
+  #     [1, 0] => c
+  #     [1, 1] => d
+  #
+  # When no block is given, returns a new Enumerator:
+  #     g = Grid.new([
+  #           [:a, "b"],
+  #           [3, true]
+  #         ])
+  #     e = g.each_cell
+  #     e # => #<Enumerator: #<Grid: @grid=[[\"a\", \"b\"], [\"c\", \"d\"]]>:each_cell>
+  #     g1 = e.each { |coords, value| puts "#{coords.inspect} => #{value.class}: #{value}" }
+  #
+  # Output:
+  #     [0, 0] => Symbol: a
+  #     [0, 1] => String: b
+  #     [1, 0] => Integer: 3
+  #     [1, 1] => TrueClass: true
+  # @yieldparam coords [Array<Integer>] the coordinates of the cell in a 2-item array where:
+  #   #   - The first item is the row index.
+  #   #   - The second item is the column index.
+  # @yieldparam value [Object] the value stored within the cell
+  # @return [self]
+  def each_cell
+    return to_enum(__callee__) unless block_given?
+    @grid.each_with_index do |row, r_index|
+      row.each_with_index do |cell, c_index|
+        yield [[r_index, c_index], cell]
+      end
+    end
+    self
+  end
+
+  private
+
+  def locate_value(element)
+    row = @grid.index { |row| row.include?(element) }
+    return nil if row.nil?
+    column = @grid[row].index(element)
+    [row, column]
+  end
+end

data/lib/aoc_rb_helpers/version.rb

@@ -1,3 +1,3 @@
 module AocRbHelpers
-  VERSION = "0.0.3"
+  VERSION = "0.0.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aoc_rb_helpers
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.5
 platform: ruby
 authors:
 - Jon Pascoe
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-02 00:00:00.000000000 Z
+date: 2024-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aoc_rb
@@ -70,6 +70,7 @@ files:
 - lib/aoc_rb_helpers.rb
 - lib/aoc_rb_helpers/aoc_input.rb
 - lib/aoc_rb_helpers/dot_matrix.rb
+- lib/aoc_rb_helpers/grid.rb
 - lib/aoc_rb_helpers/solution/input_handling.rb
 - lib/aoc_rb_helpers/version.rb
 homepage: https://github.com/pacso/aoc_rb_helpers