fractional_indexer 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6ee81d4e4b26c262bb862ec3b52558808d483bfb67fdb4c32889a7b3cc6c822
-  data.tar.gz: 2bd077740a8272885e6703f04abdc1361f3171c43156a59794b40bada2c608fd
+  metadata.gz: 9c3e15f1e2a102d07fb9fa39a650f28e959184a21bb347e8125df3c36437cfb5
+  data.tar.gz: c83b4e10bcf12bed2604dcc2b230f481c0ad46ce7bd6f2777f3cb1fad3b836ad
 SHA512:
-  metadata.gz: 7cc2e6cc619a29bcb7cfae8c2fb6e2fbbda62ee17823b217717ac357e93de4bf24830fe3ffd98ce48ba5d19f293fb68d10df4bf4926b8619a61bcfd67be0f826
-  data.tar.gz: ef547fa499d8bf94c57db52da6fb1b146fe6ce4ba4f14b24123c5e30e125da4e904605918dc314ec76dfebf60deff5af406ab50dbe096b1b24f288e39b4093c0
+  metadata.gz: ada9175bde75b29f21e7fe053cdcc0bb433c27c9fb9387de65d0b8816368f47a28108c410476b48f2bde9e5e4eb4855efe0aeef1fb0bce4291fd537a0403583b
+  data.tar.gz: 82ee500b85f2dd7ad0883e3fbdf7028141e335e47010e47b9d305837dd45fd6c55d7f6d2e6f12ec8e83ad01cc4790a57238e4a37e82583ee1838c11cc86ef591

data/README.md

@@ -21,17 +21,22 @@ gem 'fractional_indexer'
 
 And then execute:
 
-    $ bundle
+```sh
+bundle
+```
 
 Or install it yourself as:
 
-    $ gem install fractional_indexer
+```sh
+gem install fractional_indexer
+```
 
 ## Usage
 
 ### Generate Order key
 
-To generate an order key, use the `FractionalIndexer.generate_key` method. This method can take two arguments: prev_key and next_key, both of which can be either nil or a string (excluding empty strings).
+To generate an order key, use the `FractionalIndexer.generate_key` method.  
+This method can take two arguments: prev_key and next_key, both of which can be either nil or a string (excluding empty strings).
 
 The characters that can be used in the strings are available for review in `FractionalIndexer.configuration.digits`.
 
@@ -85,7 +90,8 @@ FractionalIndexer.generate_keys(prev_key: "b10", next_key: "b11", count: 5)
 
 ### base
 
-You can set the base (number system) used to represent each digit. The possible values are :base_10, :base_62, and :base_94. (The default is :base_62.)
+You can set the base (number system) used to represent each digit.  
+The possible values are :base_10, :base_62, and :base_94. (The default is :base_62)
 
 Note: base_10 is primarily intended for operational verification and debugging purposes.
 
@@ -111,9 +117,52 @@ FractionalIndexer.configuration.digits.join
 # => "!\"\#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
 ```
 
+## Order key
+
+This section explains the structure of the string that represents an Order Key.  
+An Order Key string is broadly divided into two parts: the integer part and the fractional part.
+
+Note: For ease of understanding, the explanation from here on will be based on the decimal system ('0' ~ '9')
+
+### Integer Part
+
+The integer part of the Order Key begins with a `mandatory prefix` that indicates the number of digits. This prefix is represented by one of the letters A to Z or a to z.  
+a is 1 digit, b is 2 digits, c is 3 digits ...... and z represents 26 digits.  
+The number of characters following the prefix must match the number of digits indicated by the prefix.  
+For example, if the prefix is a, a valid key could be 'a8', and if the prefix is c, a valid key could be 'c135'.
+
+```ruby
+'a9'    # Valid
+'b10'   # Valid
+'b9'    # Invalid (The prefix 'b' requires two digits)
+'c123'  # Valid
+'c12'   # Invalid (The prefix 'c' requires three digits)
+```
+
+Additionally, leveraging the characteristic that uppercase letters have a lower ASCII value than lowercase letters, a to z represent positive integers, while A to Z represent negative integers.
+
+### Fractional Part
+
+The Fractional Part refers to the portion of the string that follows the Integer Part, excluding the Integer Part itself.
+
+```ruby
+'a3012'
+# 'a3' : Integer Part
+# '012': Fractional Part
+```
+
+The Fractional Part cannot end with the first character of the base being used (e.g., '0' in base_10). This rule mirrors the mathematical principle that, for example, 0.3 and 0.30 represent the same value.
+
+```ruby
+'a32'  # Valid
+'a320' # Invalid (The Fractional Part cannot end with '0' in base_10)
+```
+
+This section clarifies the concept and rules regarding the Fractional Part of an Order Key, with examples to illustrate what constitutes a valid or invalid Fractional Part.
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/kazu-2020/fractional_indexer.
+Bug reports and pull requests are welcome on GitHub at <https://github.com/kazu-2020/fractional_indexer>.
 
 ## License
 

data/lib/fractional_indexer/decrementer.rb

@@ -39,9 +39,5 @@ module FractionalIndexer
     def borrow?(index)
       index == -1
     end
-
-    def digits
-      FractionalIndexer.configuration.digits
-    end
   end
 end

data/lib/fractional_indexer/incrementer.rb

@@ -39,9 +39,5 @@ module FractionalIndexer
     def carry_over?(index)
       index == digits.length
     end
-
-    def digits
-      FractionalIndexer.configuration.digits
-    end
   end
 end

data/lib/fractional_indexer/midpointer.rb

@@ -45,19 +45,15 @@ module FractionalIndexer
 
     private
 
-    def digits
-      FractionalIndexer.configuration.digits
-    end
-
     def validate_positions!(prev_pos, next_pos)
-      raise FractionalIndexerError, "prev_pos must be less than next_pos" if !next_pos.empty? && prev_pos >= next_pos
+      raise Error, "prev_pos must be less than next_pos" if !next_pos.empty? && prev_pos >= next_pos
 
       # NOTE
       # In a string, "0.3" and "0.30" are mathematically equivalent.
       # Therefore, a trailing "0" is prohibited.
       return unless prev_pos.end_with?(digits.first) || next_pos.end_with?(digits.first)
 
-      raise FractionalIndexerError, "prev_pos and next_pos cannot end with #{digits.first}"
+      raise Error, "prev_pos and next_pos cannot end with #{digits.first}"
     end
   end
 end

data/lib/fractional_indexer/order_key.rb

@@ -58,16 +58,16 @@ module FractionalIndexer
       integer == minimum_integer
     end
 
+    def minimum?
+      minimum_integer? && fractional.empty?
+    end
+
     def present?
       !(key.nil? || key.empty?)
     end
 
     private
 
-    def digits
-      FractionalIndexer.configuration.digits
-    end
-
     def integer_digits(key = self.key)
       if self.class.positive?(key)
         key.ord - "a".ord + INTEGER_BASE_DIGIT
@@ -82,14 +82,14 @@ module FractionalIndexer
       "z#{digits.last * POSITIVE_SIGNS.count}"
     end
 
-    def raise_error(description = nil)
-      raise FractionalIndexerError, "invalid order key: '#{key}' description: #{description}"
-    end
-
     def minimum_integer
       "A#{digits.first * POSITIVE_SIGNS.count}"
     end
 
+    def raise_error(description = nil)
+      raise Error, "invalid order key: '#{key}' description: #{description}"
+    end
+
     def valid_fractional?(fractional)
       !fractional.end_with?(digits.first)
     end

data/lib/fractional_indexer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FractionalIndexer
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/fractional_indexer.rb

@@ -2,17 +2,21 @@
 
 require "fractional_indexer/version"
 
-module FractionalIndexer
-  autoload :Configuration, "fractional_indexer/configuration"
-  autoload :Decrementer,   "fractional_indexer/decrementer"
-  autoload :Incrementer,   "fractional_indexer/incrementer"
-  autoload :Midpointer,    "fractional_indexer/midpointer"
-  autoload :OrderKey,      "fractional_indexer/order_key"
+require "fractional_indexer/configuration"
+require "fractional_indexer/decrementer"
+require "fractional_indexer/incrementer"
+require "fractional_indexer/midpointer"
+require "fractional_indexer/order_key"
 
-  class FractionalIndexerError < StandardError; end
+module FractionalIndexer
+  class Error < StandardError; end
 
   @configuration = Configuration.new
 
+  [Decrementer, Incrementer, Midpointer, OrderKey].each do |klass|
+    klass.send(:define_method, :digits) { FractionalIndexer.configuration.digits }
+  end
+
   def self.configure
     yield(configuration) if block_given?
 
@@ -26,10 +30,10 @@ module FractionalIndexer
   def self.generate_key(prev_key: nil, next_key: nil)
     return OrderKey.zero if prev_key.nil? && next_key.nil?
 
-    raise FractionalIndexerError, "prev_key and next_key cannot be empty" if prev_key&.empty? || next_key&.empty?
+    raise Error, "prev_key and next_key cannot be empty" if prev_key&.empty? || next_key&.empty?
 
     if !prev_key.nil? && !next_key.nil? && prev_key >= next_key
-      raise FractionalIndexerError, "#{prev_key} is not less than #{next_key}"
+      raise Error, "#{prev_key} is not less than #{next_key}"
     end
 
     prev_order_key = OrderKey.new(prev_key)
@@ -87,9 +91,20 @@ module FractionalIndexer
   end
 
   def self.decrement(order_key)
+    # NOTE: edge case
+    # If an Order key does not have a fractional part and its integer part is equal to
+    # the minimum value (for example, in base_62: 'A00000000000000000000000000'),
+    # further decrement operations become impossible and will fail.
+    # However, this situation is typically unlikely to occur.
+    if order_key.minimum?
+      raise Error, "order key not decremented: #{order_key} is the minimum value"
+    end
     return order_key.integer + Midpointer.execute("", order_key.fractional) if order_key.minimum_integer?
 
-    order_key.integer < order_key.key ? order_key.integer : order_key.decrement
+    decremented_order_key = OrderKey.new(order_key.integer < order_key.key ? order_key.integer : order_key.decrement)
+    return decremented_order_key.integer + Midpointer.execute if decremented_order_key.minimum?
+
+    decremented_order_key.key
   end
 
   def self.increment(order_key)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fractional_indexer
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - kazu
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-07 00:00:00.000000000 Z
+date: 2024-03-10 00:00:00.000000000 Z
 dependencies: []
 description: |
   FractionalIndexer is a Ruby gem designed to leverage fractional indexing for ordering within lists or data structures.