A library that adds new operations to Scala Seq for when a sequence needs to be considered circular, its elements forming a ring — the element after the last wraps back to the first.

It works on any immutable or mutable Seq and sub-type (Vector, List, String, ArraySeq, ListBuffer, …), acting as a decorator via Scala 3 extension or Scala 2 implicit class.

Available for Scala 3.3.7 and 2.13.18, cross-published for the JVM, Scala.js, and Scala Native. Zero runtime dependencies.

Add the dependency to your build.sbt:

libraryDependencies += "io.github.scala-tessella" %% "ring-seq" % "0.7.0"
// Use %%% instead of %% for Scala.js or Scala Native

Then import the RingSeq object — every collection under Seq gains the new methods:

import io.github.scala_tessella.ring_seq.RingSeq.*

// Indexing wraps around
Seq(10, 20, 30).applyO(4)                   // 20

// Rotation produces a new collection of the same type
"RING".rotateRight(1).mkString              // "GRIN"
List(0, 1, 2, 3).startAt(2)                 // List(2, 3, 0, 1)

// Comparison up to rotation
Seq(0, 1, 2).isRotationOf(Seq(2, 0, 1))     // true

// Canonical (necklace) form — for deduplication or hashing
Seq(2, 0, 1).canonical                      // Seq(0, 1, 2)

// Symmetry detection
Seq(0, 1, 0, 1).rotationalSymmetry          // 2

The alternative circular versions of methods that already exist on Seq keep the same name with an appended O suffix (meaning ring) — for example applyO is the circular version of apply. Operations with no standard-library counterpart use plain names.

Circular operations involve random indexing, which is O(1) on IndexedSeq (e.g. Vector, ArraySeq, String) and O(n) on LinearSeq (e.g. List).

For best performance on large sequences:

• Prefer Vector (or any IndexedSeq) over List.
• If you start from a List and call several circular operations, convert once with .toVector.

• Bioinformatics — circular DNA/RNA sequence alignment and comparison
• Graphics — polygon vertex manipulation, closed curve operations
• Procedural generation — tile rings, symmetry-aware pattern generation
• Music theory — pitch-class sets, chord inversions
• Combinatorics — necklace/bracelet enumeration, Burnside's lemma
• Embedded / robotics — circular sensor arrays, rotary encoder positions

• Website — narrative docs and examples.
• Usage walkthrough.
• Scaladoc API — the Scala 3 API reference is valid for Scala 2.13 as well.
• Changelog.

The same library, adapted for the specific idiom, is available also for:

• Python — ring-seq-py
• Rust — ring-seq-rs

Licensed under either of

• Apache License, Version 2.0
• MIT License

at your option.