fractional_indexer 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb26a758da0bb2de8108cd4a77fc48779488abaa647e908a02bb3d8476a29b5e
-  data.tar.gz: 1ea8bf3b0c21a1d70daba1843bc15ff6a50943b1b1510a91631260c37ff53def
+  metadata.gz: c6ee81d4e4b26c262bb862ec3b52558808d483bfb67fdb4c32889a7b3cc6c822
+  data.tar.gz: 2bd077740a8272885e6703f04abdc1361f3171c43156a59794b40bada2c608fd
 SHA512:
-  metadata.gz: dffb6fcbf7e72af343944c33d35cd287a0e7fb7310b42064b6e567de50f6cbf551a5f05132102484080f6ce0062a762effd1b5eac6bc177c26f838ab6c35bfbc
-  data.tar.gz: d0316fe102d0e6259a76f699affc2016c1b6ac891d8e22740ef3c0b316124490475c406632f6bcbd75f21715da13e0991a0589ca57d76b023094823d28378b68
+  metadata.gz: 7cc2e6cc619a29bcb7cfae8c2fb6e2fbbda62ee17823b217717ac357e93de4bf24830fe3ffd98ce48ba5d19f293fb68d10df4bf4926b8619a61bcfd67be0f826
+  data.tar.gz: ef547fa499d8bf94c57db52da6fb1b146fe6ce4ba4f14b24123c5e30e125da4e904605918dc314ec76dfebf60deff5af406ab50dbe096b1b24f288e39b4093c0

data/README.md

@@ -1,10 +1,15 @@
-# FractionalIndexer
+# Fractional Indexer
 
 [![codecov](https://codecov.io/gh/kazu-2020/fractional_indexer/graph/badge.svg?token=OCCYE4EKT1)](https://codecov.io/gh/kazu-2020/fractional_indexer)
+[![test](https://github.com/kazu-2020/fractional_indexer/actions/workflows/ruby.yml/badge.svg?branch=main&event=push)](https://github.com/kazu-2020/fractional_indexer/actions/workflows/ruby.yml)
 
-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.
+> efficient data insertion and sorting through fractional indexing
 
-TODO: Delete this and the text above, and describe your gem
+This gem is designed to achieve "[Realtime editing of ordered sequences](https://www.figma.com/blog/realtime-editing-of-ordered-sequences/#fractional-indexing)" as featured in a Figma blog post.
+
+Specifically, it implements Fractional Indexing as a means of managing order, realized through strings. By managing indexes as strings, it significantly delays the occurrence of index duplication that can arise when implementing Fractional Indexing with floating-point numbers. Additionally, using strings allows for the representation of a much larger range of numbers in a single digit compared to decimal numbers (by default, a single digit is represented in base-62).
+
+This gem was implemented based on the excellent article "[Implementing Fractional Indexing.](https://observablehq.com/@dgreensp/implementing-fractional-indexing)" I would like to express my gratitude to David Greenspan, the author of the article.
 
 ## Installation
 
@@ -24,17 +29,91 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### 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).
+
+The characters that can be used in the strings are available for review in `FractionalIndexer.configuration.digits`.
+
+```ruby
+require 'fractional_indexer'
+
+# create first order key
+FractionalIndexer.generate_key
+# => "a0"
+
+# increment
+FractionalIndexer.generate_key(prev_key: 'a0')
+# => "a1"
+
+# decrement
+FractionalIndexer.generate_key(next_key: 'a0')
+# => "Zz"
+
+# between prev_key and next_key
+FractionalIndexer.generate_key(prev_key: 'a0', next_key: 'a2')
+# => "a1"
+
+# prev_key should be less than next_key
+FractionalIndexer.generate_key(prev_key: 'a2', next_key: 'a1')
+# => error
+FractionalIndexer.generate_key(prev_key: 'a1', next_key: 'a1')
+# => error
+```
+
+### Generate Multiple Order keys
+
+To generate multiple order keys, use the `FractionalIndexer.generate_keys` method.
+
+```ruby
+require 'fractional_indexer'
+
+# generate n order keys that sequentially follow a given prev_key.
+FractionalIndexer.generate_keys(prev_key: "b11", count: 5)
+# => ["b12", "b13", "b14", "b15", "b16"]
+
+# generate n order keys that sequentially precede a given next_key.
+FractionalIndexer.generate_keys(next_key: "b11", count: 5)
+# => ["b0w", "b0x", "b0y", "b0z", "b10"]
 
-## Development
+# generate n order keys between the given prev_key and next_key.
+FractionalIndexer.generate_keys(prev_key: "b10", next_key: "b11", count: 5)
+# => ["b108", "b10G", "b10V", "b10d", "b10l"]
+```
+
+## Configure
+
+### base
 
-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.
+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.)
 
-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).
+Note: base_10 is primarily intended for operational verification and debugging purposes.
+
+```ruby
+require 'fractional_indexer'
+
+FractionalIndexer.configure do |config|
+  config.base = :base_10
+end
+FractionalIndexer.configuration.digits.join
+# => "0123456789"
+
+FractionalIndexer.configure do |config|
+  config.base = :base_62
+end
+FractionalIndexer.configuration.digits.join
+# => "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+
+FractionalIndexer.configure do |config|
+  config.base = :base_94
+end
+FractionalIndexer.configuration.digits.join
+# => "!\"\#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~"
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/fractional_indexer.
+Bug reports and pull requests are welcome on GitHub at https://github.com/kazu-2020/fractional_indexer.
 
 ## License
 

data/lib/fractional_indexer/version.rb

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

data/lib/fractional_indexer.rb

@@ -50,6 +50,42 @@ module FractionalIndexer
     end
   end
 
+  def self.generate_keys(prev_key: nil, next_key: nil, count: 1)
+    return [] if count <= 0
+    return [generate_key(prev_key: prev_key, next_key: next_key)] if count == 1
+
+    if next_key.nil?
+      base_order_key = generate_key(prev_key: prev_key)
+      result = [base_order_key]
+
+      (count - 1).times do
+        result << generate_key(prev_key: result.last)
+      end
+
+      return result
+    end
+
+    if prev_key.nil?
+      base_order_key = generate_key(next_key: next_key)
+      result = [base_order_key]
+
+      (count - 1).times do
+        result << generate_key(next_key: result.last)
+      end
+
+      return result.reverse
+    end
+
+    mid = count / 2
+    base_order_key = generate_key(prev_key: prev_key, next_key: next_key)
+
+    [
+      *generate_keys(prev_key: prev_key, next_key: base_order_key, count: mid),
+      base_order_key,
+      *generate_keys(prev_key: base_order_key, next_key: next_key, count: count - mid - 1),
+    ]
+  end
+
   def self.decrement(order_key)
     return order_key.integer + Midpointer.execute("", order_key.fractional) if order_key.minimum_integer?
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fractional_indexer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - kazu