fractional_indexer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cb26a758da0bb2de8108cd4a77fc48779488abaa647e908a02bb3d8476a29b5e
+  data.tar.gz: 1ea8bf3b0c21a1d70daba1843bc15ff6a50943b1b1510a91631260c37ff53def
+SHA512:
+  metadata.gz: dffb6fcbf7e72af343944c33d35cd287a0e7fb7310b42064b6e567de50f6cbf551a5f05132102484080f6ce0062a762effd1b5eac6bc177c26f838ab6c35bfbc
+  data.tar.gz: d0316fe102d0e6259a76f699affc2016c1b6ac891d8e22740ef3c0b316124490475c406632f6bcbd75f21715da13e0991a0589ca57d76b023094823d28378b68

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 kazu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,41 @@
+# FractionalIndexer
+
+[![codecov](https://codecov.io/gh/kazu-2020/fractional_indexer/graph/badge.svg?token=OCCYE4EKT1)](https://codecov.io/gh/kazu-2020/fractional_indexer)
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/fractional_indexer`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fractional_indexer'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install fractional_indexer
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/fractional_indexer.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/fractional_indexer/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module FractionalIndexer
+  class Configuration
+    attr_writer :base
+
+    # allow only ASCII characters
+    DIGITS_LIST = {
+      base_10: ("0".."9").to_a,
+      base_62: ("0".."9").to_a + ("A".."Z").to_a + ("a".."z").to_a,
+      base_94: ("!".."~").to_a,
+    }.freeze
+
+    def digits
+      DIGITS_LIST[base] || DIGITS_LIST[:base_62]
+    end
+
+    private
+
+    attr_reader :base
+  end
+end

data/lib/fractional_indexer/decrementer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module FractionalIndexer
+  class Decrementer
+    def self.execute(order_key)
+      new.execute(order_key)
+    end
+
+    def execute(order_key)
+      prefix, *digs = order_key.integer.chars
+      borrow = true
+
+      (digs.length - 1).downto(0) do |i|
+        decremented_index = digits.index(digs[i]) - 1
+
+        if borrow?(decremented_index)
+          digs[i] = digits[-1]
+        else
+          digs[i] = digits[decremented_index]
+          borrow  = false
+
+          break
+        end
+      end
+
+      return prefix + digs.join unless borrow
+
+      return "Z#{digits[-1]}" if prefix == "a"
+      return if prefix == "A"
+
+      new_key = (prefix.ord - 1).chr
+      new_key < "Z" ? digs.push(digits[-1]) : digs.pop
+
+      new_key + digs.join
+    end
+
+    private
+
+    def borrow?(index)
+      index == -1
+    end
+
+    def digits
+      FractionalIndexer.configuration.digits
+    end
+  end
+end

data/lib/fractional_indexer/incrementer.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module FractionalIndexer
+  class Incrementer
+    def self.execute(order_key)
+      new.execute(order_key)
+    end
+
+    def execute(order_key)
+      prefix, *digs = order_key.integer.chars
+      carry = true
+
+      (digs.length - 1).downto(0) do |i|
+        incremented_index = digits.index(digs[i]) + 1
+
+        if carry_over?(incremented_index)
+          digs[i] = digits[0]
+        else
+          digs[i] = digits[incremented_index]
+          carry   = false
+
+          break
+        end
+      end
+
+      return prefix + digs.join unless carry
+
+      return order_key.class.zero if prefix == "Z"
+      return if prefix == "z"
+
+      new_key = (prefix.ord + 1).chr
+      new_key > "a" ? digs.push("0") : digs.pop
+
+      new_key + digs.join
+    end
+
+    private
+
+    def carry_over?(index)
+      index == digits.length
+    end
+
+    def digits
+      FractionalIndexer.configuration.digits
+    end
+  end
+end

data/lib/fractional_indexer/midpointer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module FractionalIndexer
+  class Midpointer
+    def self.execute(prev_pos = nil, next_pos = nil)
+      new.execute(prev_pos, next_pos)
+    end
+
+    def execute(prev_pos = nil, next_pos = nil)
+      prev_pos = prev_pos.to_s
+      next_pos = next_pos.to_s
+
+      return digits[digits.length / 2] if prev_pos.empty? && next_pos.empty?
+
+      validate_positions!(prev_pos, next_pos)
+
+      unless next_pos.empty?
+        n = 0
+
+        # Get a common prefix for prev_pos and next_pos.
+        # Also add to the prefix the number of consecutive "0 "s in next_pos.
+        # Example:
+        #  prev_pos = "123", next_pos = "1230005"
+        #  prefix = "123000"
+        n += 1 while (prev_pos[n] || digits.first) == next_pos[n]
+
+        return next_pos[0, n] + execute(prev_pos[n..], next_pos[n..]) if n.positive?
+      end
+
+      digit_a = prev_pos.empty?   ? 0             : digits.index(prev_pos[0])
+      digit_b = next_pos.empty?   ? digits.length : digits.index(next_pos[0])
+
+      if digit_b - digit_a > 1
+        mid_digit = ((digit_a + digit_b) / 2.0).round
+
+        return digits[mid_digit]
+      end
+
+      if next_pos.length > 1
+        next_pos[0]
+      else
+        digits[digit_a] + execute(prev_pos[1..], nil)
+      end
+    end
+
+    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
+
+      # 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}"
+    end
+  end
+end

data/lib/fractional_indexer/order_key.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module FractionalIndexer
+  class OrderKey
+    INTEGER_BASE_DIGIT = 2
+    POSITIVE_SIGNS = ("a".."z").freeze
+    NEGATIVE_SIGNS = ("A".."Z").freeze
+
+    attr_reader :key
+
+    def initialize(key)
+      @key = key
+    end
+
+    def self.negative?(key)
+      NEGATIVE_SIGNS.cover?(key[0])
+    end
+
+    def self.positive?(key)
+      POSITIVE_SIGNS.cover?(key[0])
+    end
+
+    def self.zero
+      "a#{FractionalIndexer.configuration.digits.first}"
+    end
+
+    def decrement
+      new_order_key = Decrementer.execute(self)
+      raise_error("it cannot decrement for min integer") if new_order_key.nil?
+
+      new_order_key
+    end
+
+    def fractional
+      validate!
+
+      key[integer_digits..]
+    end
+
+    def increment
+      new_order_key = Incrementer.execute(self)
+      raise_error("it cannot increment for max integer") if new_order_key.nil?
+
+      new_order_key
+    end
+
+    def integer
+      validate!
+
+      key[0, integer_digits]
+    end
+
+    def maximum_integer?
+      integer == maximum_integer
+    end
+
+    def minimum_integer?
+      integer == minimum_integer
+    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
+      elsif self.class.negative?(key)
+        "Z".ord - key.ord + INTEGER_BASE_DIGIT
+      else
+        raise_error("prefix '#{key[0]}' is invalid. It should be a-z or A-Z.")
+      end
+    end
+
+    def maximum_integer
+      "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 valid_fractional?(fractional)
+      !fractional.end_with?(digits.first)
+    end
+
+    def valid_integer?(integer)
+      integer.length == integer_digits
+    end
+
+    def validate!
+      integer = key[0, integer_digits]
+      raise_error("integer '#{integer}' is invalid.") unless valid_integer?(integer)
+
+      fractional = key[integer_digits..]
+      raise_error("fractional '#{fractional}' is invalid.") unless valid_fractional?(fractional)
+    end
+  end
+end

data/lib/fractional_indexer/version.rb

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

data/lib/fractional_indexer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+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"
+
+  class FractionalIndexerError < StandardError; end
+
+  @configuration = Configuration.new
+
+  def self.configure
+    yield(configuration) if block_given?
+
+    configuration
+  end
+
+  def self.configuration
+    @configuration
+  end
+
+  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?
+
+    if !prev_key.nil? && !next_key.nil? && prev_key >= next_key
+      raise FractionalIndexerError, "#{prev_key} is not less than #{next_key}"
+    end
+
+    prev_order_key = OrderKey.new(prev_key)
+    next_order_key = OrderKey.new(next_key)
+
+    return decrement(next_order_key) unless prev_order_key.present?
+    return increment(prev_order_key) unless next_order_key.present?
+
+    if prev_order_key.integer == next_order_key.integer
+      return prev_order_key.integer + Midpointer.execute(prev_order_key.fractional, next_order_key.fractional)
+    end
+
+    incremented_order_key = prev_order_key.increment
+    if incremented_order_key < next_key
+      incremented_order_key
+    else
+      prev_order_key.integer + Midpointer.execute(prev_order_key.fractional, nil)
+    end
+  end
+
+  def self.decrement(order_key)
+    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
+  end
+
+  def self.increment(order_key)
+    return order_key.integer + Midpointer.execute(order_key.fractional, "") if order_key.maximum_integer?
+
+    order_key.increment
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: fractional_indexer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kazu
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-03-07 00:00:00.000000000 Z
+dependencies: []
+description: |
+  FractionalIndexer is a Ruby gem designed to leverage fractional indexing for ordering within lists or data structures.
+  it enables efficient sorting and insertion of large volumes of data.
+email:
+- matazou@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/fractional_indexer.rb
+- lib/fractional_indexer/configuration.rb
+- lib/fractional_indexer/decrementer.rb
+- lib/fractional_indexer/incrementer.rb
+- lib/fractional_indexer/midpointer.rb
+- lib/fractional_indexer/order_key.rb
+- lib/fractional_indexer/version.rb
+homepage: https://github.com/kazu-2020/fractional_indexer
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kazu-2020/fractional_indexer
+  changelog_uri: https://github.com/kazu-2020/fractional_indexer
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: efficient data insertion and sorting through fractional indexing
+test_files: []