fractional_indexer 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d3588d2624cbc372dd3013729e5543eeabf9ab227005bf5c7a02e59360d7dcb
-  data.tar.gz: 1b11cf313ea2e71ed55bab5f394fcab8d1797e08b7a86df7012bcfafe43d0f68
+  metadata.gz: 9c3e15f1e2a102d07fb9fa39a650f28e959184a21bb347e8125df3c36437cfb5
+  data.tar.gz: c83b4e10bcf12bed2604dcc2b230f481c0ad46ce7bd6f2777f3cb1fad3b836ad
 SHA512:
-  metadata.gz: d8735e7f53ea599b2a3cbfdaafd34cd2c854991c461d02b4383a7a47fb36ab956d9bbdbd80c0cf018ab668050133e0039c4e117e654cba77da2ee9fe964b70b9
-  data.tar.gz: 6b4c53291cb4fb77ebb3fb279531693a8b2c6c74dd1ad775e6bb69d19bd2e23d742a3316c9922df94dcaad24a3af0c260b14aa3caacf4b7f142844f1fb9537bc
+  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/order_key.rb

@@ -58,6 +58,10 @@ module FractionalIndexer
       integer == minimum_integer
     end
 
+    def minimum?
+      minimum_integer? && fractional.empty?
+    end
+
     def present?
       !(key.nil? || key.empty?)
     end
@@ -78,14 +82,14 @@ module FractionalIndexer
       "z#{digits.last * POSITIVE_SIGNS.count}"
     end
 
-    def raise_error(description = nil)
-      raise Error, "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.1"
+  VERSION = "0.4.0"
 end

data/lib/fractional_indexer.rb

@@ -91,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.1
+  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.