`fractional_index`

This crate implements fractional indexing, a term coined by Figma in their blog post
*Realtime Editing of Ordered Sequences*.

Specifically, this crate provides a type called `ZenoIndex`

. A `ZenoIndex`

acts as a
“black box” that has no accessor functions, can only be used by comparing it to
another `ZenoIndex`

, and can only be constructed from a default constructor or by
reference to an existing `ZenoIndex`

.

This is useful as a key in a `BTreeMap`

when we want to be able to arbitrarily insert or
re-order elements in a collection, but don't actually care what the key is.

For an ordered sequence data structure built atop this implementation, see the List implementation of Aper.

## Introduction

Let's say we want to build a data structure that acts like a list but has fast arbitrary inserts at any point. One way is to start with an ordered key-value store, and assign each value an arbitrary ascending key of some ordered type. However, our ability to perform an insert to an arbitrary position in the list will depend on our ability to construct a key between any two adjacent values.

A naive approach to this is to use a floating-point number as the key. To find a key between two adjacent values, we could average those two values. However, this runs into numerical precision issues where, as the gap between adjacent values becomes smaller, it becomes impossible to find a new value that is strictly between two others. (If you squint, this is like the line-numbering problem that plagued BASIC developers.)

One solution to this is to replace the floats with arbitrary-precision fractions, with which you can always represent a number strictly between two other (non-equal) numbers. Aside from polluting your data structure code with unnecessary arithmatic, the downside is that the room needed to store this representation tends to grow with repeated averaging. This happens in decimal, too: suppose we need to find a value between 0.76 and 0.63. Averaging gives us 0.695, which requires an extra digit to represent than the original two numbers. But for the purpose of ordering, we really just need a number x such that 0.63 < x < 0.76. We would be just as happy to use 0.7, which requires fewer digits than the original numbers to represent.

At the core of a `ZenoIndex`

is an arbitrary-precision floating-point number, but by limiting
the interface to comparisons and providing weaker semantics, the implementation is free to
make optimizations akin to the example above (albeit in base-256) in order to optimize for
space.

Figma's post sketches the approach they use, which is based on a string representation of fractional numbers, and some of the implementation details are left up to the reader. This crate attempts to formalize the math behind the approach and provide a clean interface that abstracts the implementation details away from the crate user.

## Zeno Index

To differentiate between the *concept* of fractional indexing and the mathematical implementation used here, I have called the mathematical implementation I used a **Zeno index** after the philosopher Zeno of Elea, whose dichotomy paradox has fun parallels to the implementation.

This crate exposes the `ZenoIndex`

struct. The things you can do with a `ZenoIndex`

are, by design,
very limited:

- Construct a default
`ZenoIndex`

(`Default`

implementation). - Given any
`ZenoIndex`

, construct another`ZenoIndex`

before or after it. - Given any two
`ZenoIndex`

es, construct a`ZenoIndex`

between them. - Compare two
`ZenoIndex`

es for order and equality. - Serialize and deserialize using serde (with the
`serde`

crate feature, which is enabled by default).

Notably, `ZenoIndex`

es are opaque: even though they represent a number, they don't
provide an interface for accessing that number directly. Additionally, they
don't provide guarantees about representation beyond what is exposed by the interface,
which gives the implementation room to optimize for space.

## Examples

```
use ZenoIndex;
```

## Considerations

All operations on a `ZenoIndex`

are deterministic, which means that if you construct a
`ZenoIndex`

by reference to the same other `ZenoIndex`

es, you will get the same
`ZenoIndex`

back. Without care, this may mean that an insert replaces an existing value
in your data structure. The right solution to this will depend on your use-case, but options
include:

- Only ever use
`new_between`

for keys that are adjacent in your data structure, only use`new_before`

on the least key in your data structure, and only use`new_after`

on the greatest key. This way, you will never construct a`ZenoIndex`

that is already a key in your data structure. - When inserting into your data structure, look for a value that already has that key;
if it does, transform the key by calling
`new_between`

with its adjacent key.

## Stability

The byte representation of a `ZenoIndex`

can be relied upon to be fully forward- and
backward-compatible with future versions of this crate, meaning that the serialized
representation of two `ZenoIndex`

es produced by any version of this crate will compare
the same way when deserialized in any other version.

The actual byte representation of `ZenoIndex`

es created by `new_before`

, `new_after`

,
and `new_between`

may differ between versions, but the result will always compare
appropriately with the reference `ZenoIndex`

(s) used for construction regardless
of version.

## Serialization

With the `serde`

crate feature, which is enabled by default, `ZenoIndex`

can be serialized into a `Vec<u8>`

. This encodes efficiently when using bincode or similar binary serialization formats, which is a good way to pass data when both the sender and receiver are implemented in Rust.

In cases where you want to produce data that is encoded as JSON or consumed by JavaScript, a `Vec<u8>`

is not an efficient method of encoding data on the wire. Also, because the comparison between Zeno indices is not lexicographic, it takes extra work to compare two Zeno indices in a language other than Rust.

To solve both of these problems, an alternate serializer called `lexico`

is provided. It can be used as follows:

```
use ZenoIndex;
use ;
]
ZenoIndex
);
```

The `lexico`

representation of a `ZenoIndex`

is its underlying bytes represented as a hexadecimal string, followed by "80". The addition of "80" makes it so that when strings are compared lexicographically, the ordering will be the same as the underlying Zeno indices they represent.

## Implementation

One of the goals of this crate is to provide an opaque interface that you can use without needing to study the implementation, but if you're interested in making changes to the implementation or just curious, this section describes the implementation.

### Representation

Each `ZenoIndex`

is backed by a (private) `Vec<u8>`

, i.e. a sequence of bytes.
Mathematically, the numeric value represented by this sequence of bytes is:

Where *n* is the number of bytes and *vi* is the value of the *ith* byte (zero-indexed).

The right term alone would be sufficient as an arbitrary-precision fraction representation, but the left term serves several purposes:

- It makes it impossible to represent zero. This is necessary because we always need to be able to represent a value
*between*a`ZenoIndex`

and zero. - It ensures that no two differing sequences of bytes represent the same number (without it, trailing zeros could be added without changing the represented numeric value).
- It removes the “floor bias” that would bias the representation towards zero. In particular, it means that an empty sequence of bytes represents ½ instead of 0.

It is possible to obtain a reference to the raw bytes of a `ZenoIndex`

with the `as_bytes()`

method, which
can be used for serialization that does not depend on `serde`

. This byte representation can be passed to
the `from_bytes`

constructor.

### Comparisons

To compare two numbers using this representation, we iterate through them byte-wise. If they differ at a given index, we can simply compare those values to determine the order.

Things get more complicated when one string of bytes is a prefix of the other. Without the first term, our representation would be lexicographic and we could say the shorter one comes before the longer one. Due to the first term, though, the longer one could either be before or after. So we check the following byte to see if it is at most 127 (in which case the longer string comes *before* its prefix) or not (in which case the longer string comes *after*).

To simpilify the code, we take advantage of some properties of infinite series. The representation above is equivalent to

which we can rewrite as

by defining *v'i* as the *ith* byte when *i* < *n* or 127.5 if *i* ≥ *n*.

Since it's impossible to represent 127.5 as a byte, we convert bytes into an `enum`

representation where they can take either a standard `u8`

byte value, or the “magic” value of
127.5 (the word *magic* here is used more in the wizard sense than the computational one). The comparison operator is implemented on
this enum such that the magic value compares as greater than 127 but less than 128.

### Construction

There are three ways to construct a new `ZenoIndex`

:

- From nothing:
`ZenoIndex`

implements`Default`

. Under the hood, this constructs a Zeno Index backed by an empty byte string -- i.e., equivalent to 0.5. - In relation to one other
`ZenoIndex`

(either before or after). We walk through the reference`ZenoIndex`

's byte string, and see if we can increment or decrement it. If we get to the end, we add another byte to the end to get a new`ZenoIndex`

with the desired order. - In between two other
`ZenoIndex`

es. We find the first byte index at which they differ. If the values of the index at which they differ fall on different sides of 127.5, we use the prefix that both share as the representation of the newly constructed`ZenoIndex`

. Otherwise, we look for a byte value between the two, and extend the representation by a byte if that isn't possible.

These are not the only way to satisfy the public interface of `ZenoIndex`

, so they represent
certain design considerations. In particular, the decision to increment or decrement by 1
instead of averaging with 0 or 255 comes from the fact that we expect a new item to
often come directly after the last new item. In the limit case of a data structure that is only
ever appended to, this allows us to grow the size of the underlying representation by a byte
only once every 64 new items, instead of every 8 if we averaged.

Likewise, the decision to check whether two differing bytes straddle 127.5 is not strictly necessary, but allows us to find opportunities to use a smaller underlying representation in cases where items have been removed from a data structure. If we instead were to just average the two values, it would be likely that a collection of elements would grow in representation size over successive additions and deletions, even if the number of elements stayed constant.