Functional Pearl: Enumerating the Rationals is a paper that's been on my “to-read” list for a long time. I finally got around to reading it a while back, and ended up implementing the algorithm it describes and publishing it as a crate. This article briefly describes that algorithm and some of the Rust-specific details of implementing it.

The Algorithm

The paper describes an algorithm which, starting from a base case, iterates through every possible rational number (up to the limitations of machine precision). The algorithm is interesting because:

• each value of the iterator is calculated from only the previous value (no extra state), and
• each value can be calculated in a fixed number of arithmetic operations.

There's a lengthy proof of why the algorithm works, but the essence is just a few lines of Haskell:

rationals :: [Rational]
rationals = iterate next 1
next x = 
  recip (fromInteger n + 1 - y)
  where (n, y) = properFraction x

Where iterate, recip, fromInteger, and properFraction are functions from the Haskell prelude.

The equivalent Rust code is something like:

impl<T> Iterator for Rationals<T>
where
    T: Integer + Clone + core::ops::Add,
{
    type Item = Ratio<T>;

    fn next(&mut self) -> Option<Self::Item> {
        let r = self.state.clone();
        let n = r.trunc();
        let y = r.fract();
        let next = (n + T::one() - y).recip();
        self.state = next;
        Some(r)
    }
}

The interesting part of the Rust implementation is how it's made generic over any numeric type that supports trunc, fract, and recip, and how that integrates with the broader Rust ecosystem.

The Implementation

The iterator is implemented on a struct which takes one generic parameter T, which must be an integer type. It yields ratios of integers of type T. Rather than just picking one integer type or implementing the iterator separately for u8, u32, u64, etc. we use:

Generic Numeric Traits

Specifically, it's implemented as a Ratio<Integer>, which together provide all the operations we need for our algorithm.

These come from a two different crates:

• num-rational provides Ratio
• num-integer provides Integer.

Integer is implemented for all the native integer types, so we can iterator over Ratios of u8, u32, u64. There are also other types that implement Integer (e.g: num_bigint::BigInt) which might be useful in different circumstances (e.g: for arbitrary precision arithmetic which is accurate but slow).

Directly implementing Iterator

Rust has functions like iter::repeat_with that would let us more or less copy the Haskell code above, but it ended up being just as easy to implement Iterator directly. This also made the algorithm:

no-std

Since the implementation is just a bit of math and the types are all straightforward (at least in terms of memory) it ended up not depending on the Rust standard library (i.e. it's no-std), although at the time of writing, num-traits was having some difficulty with it's no-std builds that meant I couldn't actually test this.

I just published the first (v0.1.0) release of tiddly-wiki-server, which implements the TiddlyWiki WebServer API in Rust using Axum, SerDe, and TiddlyWiki.

Motivation

One might ask why a new TiddlyWiki server is necessary, since

• TiddlyWiki5 includes a first-party NodeJS web server, and
• one of TiddlyWiki's beautiful features is that it works as as static HTML file.

These are valid points. I confess, this project fulfills quite a narrow use case: I like to self-host my tools on a small, cheap VPS, and the first-party NodeJS server consumes about 100MB of RAM. This isn't huge, but it's a decent chunk of my available resources. This server consumes much less (about 10MB, and that's before I've done anything to optimize it).

This was also a project that let me combine two technologies that I like an awful lot, so if it seems self-indulgent, well... maybe it is.

Components

The server makes use of some very nice Crates; I'll mention some of the big ones:

axum, a web framework

I've tried a number of Rust web frameworks (Tide, Rocket, simple-http-server); this one's the first one I feel like I really understood and was productive with (though that might also just be that I'm slowly getting better at Rust). Of particular note is that Axum is compatible with tower-http , so many services and middlewares that you might want already exist.

rusqlite, a SQLite binding

I use SQLite for most of my tiny side projects; this one's no exception. The TiddlyWiki back end mostly treats tiddlers as opaque bags of objects, so the database is little more than a key-value store.

serde_json, a loosely-typed JSON interface

If you're reading about Rust you're probably familiar with serde, but since I wanted to retain TiddlyWiki's fairly open schema I needed an ergonomic way to work with un-typed JSON objects.

Future Work

There are lots of ways this project could be added or improved:

• More testing; I want this server to be feature-compatible with the first party server.
• User authentication and access control
• Streaming large responses to keep memory small

If any of that sounds interesting to you, pull requests and bug reports are very much welcome!