sashite-cell 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b6d0de28c9ac29d6db74cc1bc6b143e01dba768e20de71d5f275d9f67aa72d1
-  data.tar.gz: 53e8dc478b6ec299f1fc4b5ec41f18063052bf86e5700dc13bce9cf3bee5e428
+  metadata.gz: ac0688e4dc618a3549c4b3d62db1bad731255cea5b239a87e85ac7017ce47869
+  data.tar.gz: 44ed86405deacc70b71982e07ffd2337ce9600682aab31bf524f5e2d4a9ff40d
 SHA512:
-  metadata.gz: 79db4a1d8046ffc61bb4f6042cf24b905a53a93f9c9ea3c9e96fe0efbbbc99c97899593043084407e7872a608c54a0532a2ed38d4a344f51725210b582658c04
-  data.tar.gz: 32747b087363bb7f04537cd15b6e5d19c4b2c755a4b8793366130b6eae636fbfe22b751df8e65a73a1304074a715047a5b96c59762f75ae700a8ec3c6f4db782
+  metadata.gz: ee5405dba3da3d7f8825cfd9af6220a42f34b3ca2b90a3f07b1fca3151f30d0e59e8c154468c1c57430d4e9925e531e3db81d521cc98c0756c69ecabae088fbc
+  data.tar.gz: 640048dd47362c161dbb1e3f3e6b7ea560fd4f80b915f5de37e5854f870b17ac7d511e6ddc6c96c274c60ca53b4d598abec23ce5ad59d048835e9f6277ace309

data/README.md

@@ -52,8 +52,8 @@ coord.dimensions # => 2
 coord = Sashite::Cell.parse("a1A")
 coord.indices # => [0, 0, 0]
 
-# Invalid input raises ArgumentError
-Sashite::Cell.parse("a0") # => raises ArgumentError
+# Invalid input raises Sashite::Cell::Errors::Argument
+Sashite::Cell.parse("a0") # => raises Sashite::Cell::Errors::Argument
 ```
 
 ### Formatting (Coordinate → String)
@@ -76,7 +76,7 @@ Sashite::Cell.format(2, 2, 2) # => "c3C"
 Sashite::Cell.valid?("e4") # => true
 
 # Detailed error
-Sashite::Cell.validate("a0") # => raises ArgumentError, "leading zero"
+Sashite::Cell.validate("a0") # => raises Sashite::Cell::Errors::Argument, "leading zero"
 ```
 
 ### Accessing Coordinate Data
@@ -103,7 +103,7 @@ coord.indices[1] # => 3
 # Coordinate represents a parsed CELL coordinate with up to 3 dimensions.
 class Sashite::Cell::Coordinate
   # Creates a Coordinate from 1 to 3 indices.
-  # Raises ArgumentError if no indices provided or more than 3.
+  # Raises Sashite::Cell::Errors::Argument if no indices provided or more than 3.
   #
   # @param indices [Array<Integer>] 0-indexed coordinate values (0-255)
   # @return [Coordinate]
@@ -129,20 +129,20 @@ end
 ### Constants
 
 ```ruby
-Sashite::Cell::Coordinate::MAX_DIMENSIONS = 3
-Sashite::Cell::Coordinate::MAX_INDEX_VALUE = 255
-Sashite::Cell::Coordinate::MAX_STRING_LENGTH = 7
+Sashite::Cell::Constants::MAX_DIMENSIONS   # => 3
+Sashite::Cell::Constants::MAX_INDEX_VALUE  # => 255
+Sashite::Cell::Constants::MAX_STRING_LENGTH # => 7
 ```
 
 ### Parsing
 
 ```ruby
 # Parses a CELL string into a Coordinate.
-# Raises ArgumentError if the string is not valid.
+# Raises Sashite::Cell::Errors::Argument if the string is not valid.
 #
 # @param string [String] CELL coordinate string
 # @return [Coordinate]
-# @raise [ArgumentError] if invalid
+# @raise [Sashite::Cell::Errors::Argument] if invalid
 def Sashite::Cell.parse(string)
 ```
 
@@ -161,11 +161,11 @@ def Sashite::Cell.format(*indices)
 
 ```ruby
 # Validates a CELL string.
-# Raises ArgumentError with descriptive message if invalid.
+# Raises Sashite::Cell::Errors::Argument with descriptive message if invalid.
 #
 # @param string [String] CELL coordinate string
 # @return [nil]
-# @raise [ArgumentError] if invalid
+# @raise [Sashite::Cell::Errors::Argument] if invalid
 def Sashite::Cell.validate(string)
 
 # Reports whether string is a valid CELL coordinate.
@@ -177,7 +177,7 @@ def Sashite::Cell.valid?(string)
 
 ### Errors
 
-All parsing and validation errors raise `ArgumentError` with descriptive messages:
+All parsing and validation errors raise `Sashite::Cell::Errors::Argument` (a subclass of `ArgumentError`) with descriptive messages:
 
 | Message | Cause |
 |---------|-------|
@@ -189,11 +189,27 @@ All parsing and validation errors raise `ArgumentError` with descriptive message
 | `"exceeds 3 dimensions"` | More than 3 dimensions |
 | `"index exceeds 255"` | Decoded value out of range |
 
+```ruby
+begin
+  Sashite::Cell.parse("a0")
+rescue Sashite::Cell::Errors::Argument => e
+  puts e.message # => "leading zero"
+end
+
+# Also catchable as ArgumentError for compatibility
+begin
+  Sashite::Cell.parse("a0")
+rescue ArgumentError => e
+  puts e.message # => "leading zero"
+end
+```
+
 ## Design Principles
 
 - **Bounded values**: Index validation prevents overflow
 - **Object-oriented**: `Coordinate` class enables methods and encapsulation
-- **Ruby idioms**: `valid?` predicate, `to_s` conversion, `ArgumentError` for invalid input
+- **Ruby idioms**: `valid?` predicate, `to_s` conversion
+- **Custom error class**: `Errors::Argument` inherits from `ArgumentError` for precise error handling
 - **Immutable coordinates**: Frozen indices array prevents mutation
 - **No dependencies**: Pure Ruby standard library only
 

data/lib/sashite/cell/constants.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Cell
+    module Constants
+      # Maximum number of dimensions supported by a CELL coordinate.
+      # Sufficient for 1D, 2D, and 3D game boards.
+      MAX_DIMENSIONS = 3
+
+      # Maximum value for a single coordinate index.
+      # Fits in an 8-bit unsigned integer (0-255).
+      MAX_INDEX_VALUE = 255
+
+      # Maximum length of a CELL string representation.
+      # Corresponds to "iv256IV" (worst case for all dimensions at 255).
+      MAX_STRING_LENGTH = 7
+    end
+  end
+end

data/lib/sashite/cell/coordinate.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "constants"
+require_relative "errors"
+require_relative "formatter"
+
 module Sashite
   module Cell
     # Represents a parsed CELL coordinate with up to 3 dimensions.
@@ -17,35 +21,34 @@ module Sashite
     #   coord = Sashite::Cell::Coordinate.new(0, 0, 0)
     #   coord.to_s # => "a1A"
     class Coordinate
-      # Maximum number of dimensions supported.
-      MAX_DIMENSIONS = 3
-
-      # Maximum value for any single index (0-255).
-      MAX_INDEX_VALUE = 255
-
-      # Maximum length of a CELL coordinate string.
-      MAX_STRING_LENGTH = 7
-
       # Returns the coordinate indices as a frozen array.
       #
       # @return [Array<Integer>] 0-indexed coordinate values
+      #
+      # @example
+      #   Sashite::Cell::Coordinate.new(4, 3).indices # => [4, 3]
       attr_reader :indices
 
       # Creates a Coordinate from 1 to 3 indices.
       #
       # @param indices [Array<Integer>] 0-indexed coordinate values (0-255 each)
-      # @raise [ArgumentError] if no indices provided, more than 3, or values out of range
+      # @raise [Sashite::Cell::Errors::Argument] if no indices provided, more than 3, or values out of range
       #
       # @example
       #   Sashite::Cell::Coordinate.new(4, 3)    # 2D coordinate
       #   Sashite::Cell::Coordinate.new(0, 0, 0) # 3D coordinate
       def initialize(*indices)
-        raise ::ArgumentError, "empty input" if indices.empty?
-        raise ::ArgumentError, "exceeds #{MAX_DIMENSIONS} dimensions" if indices.size > MAX_DIMENSIONS
+        if indices.empty?
+          raise Errors::Argument, Errors::Argument::Messages::NO_INDICES
+        end
+
+        if indices.size > Constants::MAX_DIMENSIONS
+          raise Errors::Argument, Errors::Argument::Messages::TOO_MANY_DIMENSIONS
+        end
 
         indices.each do |index|
-          unless index.is_a?(::Integer) && index >= 0 && index <= MAX_INDEX_VALUE
-            raise ::ArgumentError, "index exceeds #{MAX_INDEX_VALUE}"
+          unless index.is_a?(::Integer) && index >= 0 && index <= Constants::MAX_INDEX_VALUE
+            raise Errors::Argument, Errors::Argument::Messages::INDEX_OUT_OF_RANGE
           end
         end
 
@@ -69,13 +72,16 @@ module Sashite
       # @example
       #   Sashite::Cell::Coordinate.new(4, 3).to_s # => "e4"
       def to_s
-        Dumper.indices_to_string(@indices)
+        Formatter.indices_to_string(@indices)
       end
 
       # Checks equality with another Coordinate.
       #
       # @param other [Object] object to compare
       # @return [Boolean] true if equal, false otherwise
+      #
+      # @example
+      #   Sashite::Cell::Coordinate.new(4, 3) == Sashite::Cell::Coordinate.new(4, 3) # => true
       def ==(other)
         other.is_a?(Coordinate) && @indices == other.indices
       end
@@ -85,6 +91,10 @@ module Sashite
       # Returns hash code for use in Hash keys.
       #
       # @return [Integer] hash code
+      #
+      # @example
+      #   coord = Sashite::Cell::Coordinate.new(4, 3)
+      #   hash = { coord => "value" }
       def hash
         @indices.hash
       end
@@ -92,6 +102,9 @@ module Sashite
       # Returns a human-readable representation.
       #
       # @return [String] inspection string
+      #
+      # @example
+      #   Sashite::Cell::Coordinate.new(4, 3).inspect # => "#<Sashite::Cell::Coordinate e4>"
       def inspect
         "#<#{self.class} #{self}>"
       end

data/lib/sashite/cell/errors/argument/messages.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Cell
+    module Errors
+      class Argument < ::ArgumentError
+        # Error messages for validation failures.
+        # Kept as constants to ensure consistency across the library.
+        module Messages
+          EMPTY_INPUT          = "empty input"
+          INPUT_TOO_LONG       = "input exceeds 7 characters"
+          INVALID_START        = "must start with lowercase letter"
+          UNEXPECTED_CHARACTER = "unexpected character"
+          LEADING_ZERO         = "leading zero"
+          TOO_MANY_DIMENSIONS  = "exceeds 3 dimensions"
+          INDEX_OUT_OF_RANGE   = "index exceeds 255"
+          NO_INDICES           = "at least one index required"
+        end
+      end
+    end
+  end
+end

data/lib/sashite/cell/errors/argument.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "argument/messages"
+
+module Sashite
+  module Cell
+    module Errors
+      # Custom error class for CELL parsing and validation failures.
+      #
+      # Inherits from ArgumentError to maintain semantic meaning
+      # while allowing specific rescue of CELL-related errors.
+      #
+      # @example Rescuing specific CELL errors
+      #   begin
+      #     Sashite::Cell.parse("invalid")
+      #   rescue Sashite::Cell::Errors::Argument => e
+      #     puts "CELL error: #{e.message}"
+      #   end
+      #
+      # @example Rescuing as ArgumentError
+      #   begin
+      #     Sashite::Cell.parse("invalid")
+      #   rescue ArgumentError => e
+      #     puts "Argument error: #{e.message}"
+      #   end
+      class Argument < ::ArgumentError
+      end
+    end
+  end
+end

data/lib/sashite/cell/errors.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "errors/argument"

data/lib/sashite/cell/formatter.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Cell
+    # Formats index arrays into CELL coordinate strings.
+    #
+    # This module handles the conversion from numeric indices to their
+    # CELL string representation following the cyclic pattern:
+    # - Dimension 1, 4, 7...: lowercase letters (a-z, aa-iv)
+    # - Dimension 2, 5, 8...: positive integers (1-256)
+    # - Dimension 3, 6, 9...: uppercase letters (A-Z, AA-IV)
+    #
+    # @example
+    #   Formatter.indices_to_string([4, 3])    # => "e4"
+    #   Formatter.indices_to_string([0, 0, 0]) # => "a1A"
+    #
+    # @api private
+    module Formatter
+      # Formats an indices array to a CELL string.
+      #
+      # @param indices [Array<Integer>] 0-indexed coordinate values
+      # @return [String] CELL coordinate string
+      #
+      # @example
+      #   Formatter.indices_to_string([4, 3])       # => "e4"
+      #   Formatter.indices_to_string([255, 255, 255]) # => "iv256IV"
+      def self.indices_to_string(indices)
+        result = +""
+
+        indices.each_with_index do |index, i|
+          dimension_type = i % 3
+
+          result << case dimension_type
+                    when 0 then encode_to_lower(index)
+                    when 1 then encode_to_number(index)
+                    when 2 then encode_to_upper(index)
+                    end
+        end
+
+        result.freeze
+      end
+
+      # Encodes an index (0-255) as lowercase letters (a-z, aa-iv).
+      #
+      # @param index [Integer] 0-indexed value (0-255)
+      # @return [String] lowercase letter sequence
+      #
+      # @example
+      #   encode_to_lower(0)   # => "a"
+      #   encode_to_lower(25)  # => "z"
+      #   encode_to_lower(26)  # => "aa"
+      #   encode_to_lower(255) # => "iv"
+      private_class_method def self.encode_to_lower(index)
+        encode_to_letters(index, base: "a")
+      end
+
+      # Encodes an index (0-255) as uppercase letters (A-Z, AA-IV).
+      #
+      # @param index [Integer] 0-indexed value (0-255)
+      # @return [String] uppercase letter sequence
+      #
+      # @example
+      #   encode_to_upper(0)   # => "A"
+      #   encode_to_upper(25)  # => "Z"
+      #   encode_to_upper(26)  # => "AA"
+      #   encode_to_upper(255) # => "IV"
+      private_class_method def self.encode_to_upper(index)
+        encode_to_letters(index, base: "A")
+      end
+
+      # Encodes an index to a letter sequence.
+      #
+      # @param index [Integer] 0-indexed value (0-255)
+      # @param base [String] base character ("a" or "A")
+      # @return [String] letter sequence
+      private_class_method def self.encode_to_letters(index, base:)
+        base_ord = base.ord
+
+        if index < 26
+          (base_ord + index).chr
+        else
+          adjusted = index - 26
+          first = adjusted / 26
+          second = adjusted % 26
+          (base_ord + first).chr + (base_ord + second).chr
+        end
+      end
+
+      # Encodes an index (0-255) as a 1-based positive integer string.
+      #
+      # @param index [Integer] 0-indexed value (0-255)
+      # @return [String] number string (1-indexed)
+      #
+      # @example
+      #   encode_to_number(0)   # => "1"
+      #   encode_to_number(255) # => "256"
+      private_class_method def self.encode_to_number(index)
+        (index + 1).to_s
+      end
+    end
+  end
+end

data/lib/sashite/cell/parser.rb

@@ -1,9 +1,24 @@
 # frozen_string_literal: true
 
+require_relative "constants"
+require_relative "errors"
+
 module Sashite
   module Cell
     # Parses CELL coordinate strings into index arrays.
     #
+    # This module handles the conversion from CELL string representation
+    # to numeric indices, following the cyclic pattern:
+    # - Dimension 1, 4, 7...: lowercase letters (a-z, aa-iv)
+    # - Dimension 2, 5, 8...: positive integers (1-256)
+    # - Dimension 3, 6, 9...: uppercase letters (A-Z, AA-IV)
+    #
+    # Security considerations:
+    # - Character-by-character parsing (no regex, no ReDoS risk)
+    # - Fail-fast on invalid input
+    # - Bounded iteration (max 7 characters)
+    # - Explicit ASCII validation
+    #
     # @example
     #   Parser.parse_to_indices("e4")  # => [4, 3]
     #   Parser.parse_to_indices("a1A") # => [0, 0, 0]
@@ -14,106 +29,205 @@ module Sashite
       #
       # @param string [String] CELL coordinate string
       # @return [Array<Integer>] 0-indexed coordinate values
-      # @raise [ArgumentError] if parsing fails
+      # @raise [Sashite::Cell::Errors::Argument] if parsing fails
+      #
+      # @example
+      #   Parser.parse_to_indices("e4")      # => [4, 3]
+      #   Parser.parse_to_indices("iv256IV") # => [255, 255, 255]
       def self.parse_to_indices(string)
-        raise ::ArgumentError, "empty input" if string.empty?
-        if string.length > Coordinate::MAX_STRING_LENGTH
-          raise ::ArgumentError, "input exceeds #{Coordinate::MAX_STRING_LENGTH} characters"
-        end
-        raise ::ArgumentError, "must start with lowercase letter" unless string[0].match?(/[a-z]/)
+        raise Errors::Argument, Errors::Argument::Messages::EMPTY_INPUT if string.empty?
 
-        indices = []
-        remaining = string
-        dimension = 1
+        if string.length > Constants::MAX_STRING_LENGTH
+          raise Errors::Argument, Errors::Argument::Messages::INPUT_TOO_LONG
+        end
 
-        until remaining.empty?
-          value, consumed = parse_dimension(remaining, dimension)
-          indices << value
-          remaining = remaining[consumed..]
-          dimension += 1
+        first_byte = string.getbyte(0)
+        unless lowercase?(first_byte)
+          raise Errors::Argument, Errors::Argument::Messages::INVALID_START
         end
 
-        if indices.size > Coordinate::MAX_DIMENSIONS
-          raise ::ArgumentError, "exceeds #{Coordinate::MAX_DIMENSIONS} dimensions"
+        indices = []
+        pos = 0
+        dimension_type = 0 # 0: lowercase, 1: integer, 2: uppercase
+
+        while pos < string.length
+          if indices.size >= Constants::MAX_DIMENSIONS
+            raise Errors::Argument, Errors::Argument::Messages::TOO_MANY_DIMENSIONS
+          end
+
+          case dimension_type
+          when 0
+            value, consumed = parse_lowercase(string, pos)
+            indices << value
+            pos += consumed
+            dimension_type = 1
+          when 1
+            value, consumed = parse_integer(string, pos)
+            indices << value
+            pos += consumed
+            dimension_type = 2
+          when 2
+            value, consumed = parse_uppercase(string, pos)
+            indices << value
+            pos += consumed
+            dimension_type = 0
+          end
         end
 
         indices
       end
 
-      # Parses a single dimension from the remaining string.
+      # Checks if a byte is a lowercase ASCII letter (a-z).
       #
-      # @param remaining [String] remaining string to parse
-      # @param dimension [Integer] current dimension number (1-based)
-      # @return [Array(Integer, Integer)] parsed value and characters consumed
-      # @raise [ArgumentError] if parsing fails
-      private_class_method def self.parse_dimension(remaining, dimension)
-        case dimension % 3
-        when 1 then parse_lowercase(remaining)
-        when 2 then parse_integer(remaining)
-        when 0 then parse_uppercase(remaining)
-        end
+      # @param byte [Integer, nil] byte value
+      # @return [Boolean] true if lowercase letter
+      private_class_method def self.lowercase?(byte)
+        byte && byte >= 97 && byte <= 122 # 'a' = 97, 'z' = 122
+      end
+
+      # Checks if a byte is an uppercase ASCII letter (A-Z).
+      #
+      # @param byte [Integer, nil] byte value
+      # @return [Boolean] true if uppercase letter
+      private_class_method def self.uppercase?(byte)
+        byte && byte >= 65 && byte <= 90 # 'A' = 65, 'Z' = 90
+      end
+
+      # Checks if a byte is an ASCII digit (0-9).
+      #
+      # @param byte [Integer, nil] byte value
+      # @return [Boolean] true if digit
+      private_class_method def self.digit?(byte)
+        byte && byte >= 48 && byte <= 57 # '0' = 48, '9' = 57
       end
 
-      # Parses lowercase letters dimension.
+      # Parses lowercase letters starting at position.
       #
-      # @param remaining [String] remaining string to parse
-      # @return [Array(Integer, Integer)] parsed value and characters consumed
-      # @raise [ArgumentError] if parsing fails
-      private_class_method def self.parse_lowercase(remaining)
-        match = remaining.match(/\A([a-z]+)/)
-        raise ::ArgumentError, "unexpected character" unless match
+      # @param string [String] input string
+      # @param pos [Integer] starting position
+      # @return [Array(Integer, Integer)] decoded value and characters consumed
+      # @raise [Sashite::Cell::Errors::Argument] if parsing fails
+      private_class_method def self.parse_lowercase(string, pos)
+        byte = string.getbyte(pos)
+        unless lowercase?(byte)
+          raise Errors::Argument, Errors::Argument::Messages::UNEXPECTED_CHARACTER
+        end
 
-        value = decode_letters(match[1])
-        raise ::ArgumentError, "index exceeds #{Coordinate::MAX_INDEX_VALUE}" if value > Coordinate::MAX_INDEX_VALUE
+        chars = [byte]
+        pos += 1
 
-        [value, match[1].length]
+        while pos < string.length && lowercase?(string.getbyte(pos))
+          chars << string.getbyte(pos)
+          pos += 1
+        end
+
+        value = decode_lowercase(chars)
+        if value > Constants::MAX_INDEX_VALUE
+          raise Errors::Argument, Errors::Argument::Messages::INDEX_OUT_OF_RANGE
+        end
+
+        [value, chars.size]
       end
 
-      # Parses positive integer dimension.
+      # Parses a positive integer starting at position.
       #
-      # @param remaining [String] remaining string to parse
-      # @return [Array(Integer, Integer)] parsed value and characters consumed
-      # @raise [ArgumentError] if parsing fails
-      private_class_method def self.parse_integer(remaining)
-        match = remaining.match(/\A(0|[1-9][0-9]*)/)
-        raise ::ArgumentError, "unexpected character" unless match
-        raise ::ArgumentError, "leading zero" if match[1] == "0"
-
-        value = match[1].to_i - 1
-        raise ::ArgumentError, "index exceeds #{Coordinate::MAX_INDEX_VALUE}" if value > Coordinate::MAX_INDEX_VALUE
-
-        [value, match[1].length]
+      # @param string [String] input string
+      # @param pos [Integer] starting position
+      # @return [Array(Integer, Integer)] decoded value and characters consumed
+      # @raise [Sashite::Cell::Errors::Argument] if parsing fails
+      private_class_method def self.parse_integer(string, pos)
+        byte = string.getbyte(pos)
+        unless digit?(byte)
+          raise Errors::Argument, Errors::Argument::Messages::UNEXPECTED_CHARACTER
+        end
+
+        # Check for leading zero
+        if byte == 48 # '0'
+          raise Errors::Argument, Errors::Argument::Messages::LEADING_ZERO
+        end
+
+        chars = [byte]
+        pos += 1
+
+        while pos < string.length && digit?(string.getbyte(pos))
+          chars << string.getbyte(pos)
+          pos += 1
+        end
+
+        value = decode_integer(chars)
+        if value < 0 || value > Constants::MAX_INDEX_VALUE
+          raise Errors::Argument, Errors::Argument::Messages::INDEX_OUT_OF_RANGE
+        end
+
+        [value, chars.size]
       end
 
-      # Parses uppercase letters dimension.
+      # Parses uppercase letters starting at position.
       #
-      # @param remaining [String] remaining string to parse
-      # @return [Array(Integer, Integer)] parsed value and characters consumed
-      # @raise [ArgumentError] if parsing fails
-      private_class_method def self.parse_uppercase(remaining)
-        match = remaining.match(/\A([A-Z]+)/)
-        raise ::ArgumentError, "unexpected character" unless match
+      # @param string [String] input string
+      # @param pos [Integer] starting position
+      # @return [Array(Integer, Integer)] decoded value and characters consumed
+      # @raise [Sashite::Cell::Errors::Argument] if parsing fails
+      private_class_method def self.parse_uppercase(string, pos)
+        byte = string.getbyte(pos)
+        unless uppercase?(byte)
+          raise Errors::Argument, Errors::Argument::Messages::UNEXPECTED_CHARACTER
+        end
 
-        value = decode_letters(match[1].downcase)
-        raise ::ArgumentError, "index exceeds #{Coordinate::MAX_INDEX_VALUE}" if value > Coordinate::MAX_INDEX_VALUE
+        chars = [byte]
+        pos += 1
 
-        [value, match[1].length]
+        while pos < string.length && uppercase?(string.getbyte(pos))
+          chars << string.getbyte(pos)
+          pos += 1
+        end
+
+        value = decode_uppercase(chars)
+        if value > Constants::MAX_INDEX_VALUE
+          raise Errors::Argument, Errors::Argument::Messages::INDEX_OUT_OF_RANGE
+        end
+
+        [value, chars.size]
+      end
+
+      # Decodes lowercase letter bytes to an index.
+      #
+      # @param bytes [Array<Integer>] byte values
+      # @return [Integer] decoded index (0-255)
+      private_class_method def self.decode_lowercase(bytes)
+        if bytes.size == 1
+          bytes[0] - 97 # 'a' = 97
+        else
+          first = bytes[0] - 97
+          second = bytes[1] - 97
+          26 + (first * 26) + second
+        end
       end
 
-      # Decodes letter sequence to index (a=0, z=25, aa=26, ...).
+      # Decodes uppercase letter bytes to an index.
       #
-      # @param letters [String] lowercase letter sequence
-      # @return [Integer] decoded index
-      private_class_method def self.decode_letters(letters)
-        letters = letters.downcase
-        return letters.ord - "a".ord if letters.length == 1
-
-        # Multi-letter: aa=26, ab=27, ..., zz=701
-        result = 0
-        letters.each_char do |char|
-          result = (result * 26) + (char.ord - "a".ord)
-        end
-        result + 26
+      # @param bytes [Array<Integer>] byte values
+      # @return [Integer] decoded index (0-255)
+      private_class_method def self.decode_uppercase(bytes)
+        if bytes.size == 1
+          bytes[0] - 65 # 'A' = 65
+        else
+          first = bytes[0] - 65
+          second = bytes[1] - 65
+          26 + (first * 26) + second
+        end
+      end
+
+      # Decodes digit bytes to an index (1-based to 0-based).
+      #
+      # @param bytes [Array<Integer>] byte values
+      # @return [Integer] decoded index (0-255)
+      private_class_method def self.decode_integer(bytes)
+        value = 0
+        bytes.each do |byte|
+          value = (value * 10) + (byte - 48) # '0' = 48
+        end
+        value - 1 # Convert from 1-based to 0-based
       end
     end
   end

data/lib/sashite/cell.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "cell/errors"
+require_relative "cell/formatter"
 require_relative "cell/coordinate"
-require_relative "cell/dumper"
 require_relative "cell/parser"
 
 module Sashite
@@ -28,11 +29,12 @@ module Sashite
     #
     # @param string [String] CELL coordinate string
     # @return [Coordinate] parsed coordinate
-    # @raise [ArgumentError] if the string is not a valid CELL coordinate
+    # @raise [Sashite::Cell::Errors::Argument] if the string is not a valid CELL coordinate
     #
     # @example
     #   Sashite::Cell.parse("e4")  # => #<Sashite::Cell::Coordinate e4>
-    #   Sashite::Cell.parse("a0")  # => raises ArgumentError
+    #   Sashite::Cell.parse("a1A") # => #<Sashite::Cell::Coordinate a1A>
+    #   Sashite::Cell.parse("a0")  # => raises Sashite::Cell::Errors::Argument
     def self.parse(string)
       Coordinate.new(*Parser.parse_to_indices(string))
     end
@@ -41,7 +43,7 @@ module Sashite
     #
     # @param indices [Array<Integer>] 0-indexed coordinate values (0-255)
     # @return [String] CELL coordinate string
-    # @raise [ArgumentError] if indices are invalid
+    # @raise [Sashite::Cell::Errors::Argument] if indices are invalid
     #
     # @example
     #   Sashite::Cell.format(4, 3)    # => "e4"
@@ -54,11 +56,11 @@ module Sashite
     #
     # @param string [String] CELL coordinate string
     # @return [nil]
-    # @raise [ArgumentError] if the string is not a valid CELL coordinate
+    # @raise [Sashite::Cell::Errors::Argument] if the string is not a valid CELL coordinate
     #
     # @example
     #   Sashite::Cell.validate("e4")  # => nil
-    #   Sashite::Cell.validate("a0")  # => raises ArgumentError
+    #   Sashite::Cell.validate("a0")  # => raises Sashite::Cell::Errors::Argument
     def self.validate(string)
       Parser.parse_to_indices(string)
       nil
@@ -75,7 +77,7 @@ module Sashite
     def self.valid?(string)
       validate(string)
       true
-    rescue ::ArgumentError
+    rescue Errors::Argument
       false
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-cell
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -22,8 +22,12 @@ files:
 - README.md
 - lib/sashite-cell.rb
 - lib/sashite/cell.rb
+- lib/sashite/cell/constants.rb
 - lib/sashite/cell/coordinate.rb
-- lib/sashite/cell/dumper.rb
+- lib/sashite/cell/errors.rb
+- lib/sashite/cell/errors/argument.rb
+- lib/sashite/cell/errors/argument/messages.rb
+- lib/sashite/cell/formatter.rb
 - lib/sashite/cell/parser.rb
 homepage: https://github.com/sashite/cell.rb
 licenses:

data/lib/sashite/cell/dumper.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Cell
-    # Formats index arrays into CELL coordinate strings.
-    #
-    # @example
-    #   Dumper.indices_to_string([4, 3])    # => "e4"
-    #   Dumper.indices_to_string([0, 0, 0]) # => "a1A"
-    #
-    # @api private
-    module Dumper
-      # Formats indices array to CELL string.
-      #
-      # @param indices [Array<Integer>] 0-indexed coordinate values
-      # @return [String] CELL coordinate string
-      def self.indices_to_string(indices)
-        indices.each_with_index.map do |index, i|
-          dimension = i + 1
-          case dimension % 3
-          when 1 then encode_letters(index, uppercase: false)
-          when 2 then encode_integer(index)
-          when 0 then encode_letters(index, uppercase: true)
-          end
-        end.join
-      end
-
-      # Encodes index to letter sequence (0=a, 25=z, 26=aa, ...).
-      #
-      # @param index [Integer] 0-indexed value
-      # @param uppercase [Boolean] whether to use uppercase letters
-      # @return [String] letter sequence
-      private_class_method def self.encode_letters(index, uppercase:)
-        base_char = uppercase ? "A" : "a"
-
-        if index < 26
-          (base_char.ord + index).chr
-        else
-          adjusted = index - 26
-          first = adjusted / 26
-          second = adjusted % 26
-          (base_char.ord + first).chr + (base_char.ord + second).chr
-        end
-      end
-
-      # Encodes index to number string (0=1, 1=2, ...).
-      #
-      # @param index [Integer] 0-indexed value
-      # @return [String] number string (1-indexed)
-      private_class_method def self.encode_integer(index)
-        (index + 1).to_s
-      end
-    end
-  end
-end