Skip to content

Reference

This page lists all the features provided by the library.

The RingSeq class

RingSeq[T] wraps any Iterable[T], storing it internally as an immutable tuple. The class is generic, hashable, orderable, and implements the Python Sequence protocol — with all built-in operations (len, indexing, slicing, iteration, containment) made circular.

Instances are built with the constructor:

>>> from ring_seq import RingSeq
>>> RingSeq('ABC')
RingSeq(('A', 'B', 'C'))

Equality is positional and is agnostic to the input iterable kind used at construction:

>>> RingSeq('ABC') == RingSeq(['A', 'B', 'C']) == RingSeq(('A', 'B', 'C'))
True

Use to_list(), to_tuple(), or to_str() to unwrap at the boundary:

>>> RingSeq('ABC').rotate_left(1).to_str()
'BCA'
>>> RingSeq([1, 2, 3]).reflect_at().to_list()
[1, 3, 2]

Methods

Methods fall into the following categories:

Native sequence protocol (circular)

  • __getitem__ — circular indexing and slicing, e.g. rs[-1], rs[30001], rs[1:10], rs[::-1]
  • __len__, __iter__, __reversed__, __contains__ — standard protocol
  • __eq__, __lt__, __le__, __hash__ — positional comparison and hashing
  • get — like rs[i], but returns a default on an empty ring
  • index — circular element lookup
  • index_of_slice — circular lookup of a contiguous, possibly wrapping slice
  • contains_slice — slice containment, wrapping included

Unwrap

Indexing helper

Rotation and reflection

Slicing primitives

Iterators

Comparisons

Symmetry

Canonical forms (necklace / bracelet)

  • canonical_index — starting index of the lexicographically smallest rotation (two-pointer minimal rotation, O(n) time, O(1) space)
  • canonical — the lex-smallest rotation; useful for hashing/deduplicating equivalent rings
  • bracelet — the lex-smallest representative under both rotation and reflection