Cyclic Double-Linked List

Overview

Double-Linked List

This crate provides a doubly-linked list with owned nodes, implemented as a cyclic list.

Usage

First, add dependency in your Cargo.toml:

[dependencies]
cyclic_list = "0.1"

Then enjoy it in your project.

Examples

use cyclic_list::List;
use std::iter::FromIterator;

let mut list = List::from_iter([1, 2, 3, 4]);

let mut cursor = list.cursor_start_mut();

cursor.insert(0); // insert 0 at the beginning of the list
assert_eq!(cursor.current(), Some(&1));
assert_eq!(cursor.view(), &List::from_iter([0, 1, 2, 3, 4]));

cursor.seek_to(3); // move the cursor to position 3, and removes it.
assert_eq!(cursor.remove(), Some(3));
assert_eq!(cursor.view(), &List::from_iter([0, 1, 2, 4]));

cursor.push_front(5); // pushing front to the list is also allowed
assert_eq!(cursor.view(), &List::from_iter([5, 0, 1, 2, 4]));

Introduction

The List allows inserting, removing elements at any given position in constant time. In compromise, accessing or mutating elements at any position take O(n) time.

Memory Layout

The memory layout is like the following graph:

         ┌─────────────────────────────────────────────────────────────────────┐
         ↓                                                     (Ghost) Node N  │
   ╔═══════════╗           ╔═══════════╗                        ┌───────────┐  │
   ║   next    ║ ────────→ ║   next    ║ ────────→ ┄┄ ────────→ │   next    │ ─┘
   ╟───────────╢           ╟───────────╢     Node 2, 3, ...     ├───────────┤
┌─ ║   prev    ║ ←──────── ║   prev    ║ ←──────── ┄┄ ←──────── │   prev    │
│  ╟───────────╢           ╟───────────╢                        ├───────────┤
│  ║ payload T ║           ║ payload T ║                        ┊No payload ┊
│  ╚═══════════╝           ╚═══════════╝                        └╌╌╌╌╌╌╌╌╌╌╌┘
│      Node 0                  Node 1                               ↑   ↑
└───────────────────────────────────────────────────────────────────┘   │
╔═══════════╗                                                           │
║   ghost   ║ ──────────────────────────────────────────────────────────┘
╟───────────╢
║   (len)   ║
╚═══════════╝
    List

Iteration

Iterating over a list is by the [Iter] and [IterMut] iterators. These are double-ended iterators and iterate the list like an array (fused and non-cyclic). [IterMut] provides mutability of the elements (but not the linked structure of the list).

Examples

use cyclic_list::List;
use std::iter::FromIterator;

let mut list = List::from_iter([1, 2, 3]);
let mut iter = list.iter();
assert_eq!(iter.next(), Some(&1));
assert_eq!(iter.next(), Some(&2));
assert_eq!(iter.next(), Some(&3));
assert_eq!(iter.next(), None);
assert_eq!(iter.next(), None); // Fused and non-cyclic

list.iter_mut().for_each(|item| *item *= 2);
assert_eq!(Vec::from_iter(list), vec![2, 4, 6]);

Cursor Views

Beside iteration, the cursors [Cursor] and [CursorMut] provide more flexible ways of viewing a list.

As the names suggest, they are like cursors and can move forward or backward over the list. In a list with length n, there are n + 1 valid locations for the cursor, indexed by 0, 1, ..., n, where n is the ghost node of the list.

Cursors can also be used as iterators, but are cyclic and not fused.

Warning: Though cursor iterators have methods rev, they DO NOT behave as double-ended iterators. Instead, they create a new iterator that reverses the moving direction of the cursor.

Examples

use cyclic_list::List;
use std::iter::FromIterator;

let list = List::from_iter([1, 2, 3]);
// Create a cursor iterator
let mut cursor_iter = list.cursor_start().into_iter();
assert_eq!(cursor_iter.next(), Some(&1));
assert_eq!(cursor_iter.next(), Some(&2));
assert_eq!(cursor_iter.next(), Some(&3));
assert_eq!(cursor_iter.next(), None);
assert_eq!(cursor_iter.next(), Some(&1)); // Not fused and cyclic

// Create a cursor back iterator which reverses the moving direction
// of the cursor
let mut cursor_iter = cursor_iter.rev();
assert_eq!(cursor_iter.next(), Some(&1)); // Iterate in reversed direction
assert_eq!(cursor_iter.next(), None); // Pass through the ghost node boundary
assert_eq!(cursor_iter.next(), Some(&3)); // Reaches the ghost node

Cursor Mutations

CursorMut provides many useful ways to mutate the list in any position.

  • insert: insert a new item at the cursor;
  • remove: remove the item at the cursor;
  • backspace: remove the item before the cursor;
  • split: split the list into a new one, from the cursor position to the end;
  • splice: splice another list before the cursor position;

Examples

use cyclic_list::List;
use std::iter::FromIterator;

let mut list = List::from_iter([1, 2, 3, 4]);

let mut cursor = list.cursor_start_mut();

cursor.insert(5); // becomes [5, 1, 2, 3, 4], points to 1
assert_eq!(cursor.current(), Some(&1));

assert!(cursor.seek_forward(2).is_ok());
assert_eq!(cursor.remove(), Some(3)); // becomes [5, 1, 2, 4], points to 4
assert_eq!(cursor.current(), Some(&4));

assert_eq!(cursor.backspace(), Some(2)); // becomes [5, 1, 4], points to 4
assert_eq!(cursor.current(), Some(&4));

assert_eq!(Vec::from_iter(list), vec![5, 1, 4]);

Develop Plans

Here is the develop plan of this project.

  • Basic supports: push, pop, insert, remove;
  • Cursor supports: move, seek, insert, remove, split, splice;
  • Iterator supports: from/into iterators, immutable/mutable iterators, double-ended iterators, cursor-like iterators;
  • Container operations:
    • rotate
    • reverse
  • Algorithm supports:
    • drain
    • find
    • sort
    • sub-range view
  • Advanced topics:
    • dynamic-sized types
    • concurrent support
You might also like...
Doubly-Linked List Implementation in Rust

Doubly-Linked List Implementation in Rust Purely for educational and recreational purposes. For real world production please use std::collections::Lin

Portable linked-list allocator designed for baremetal systems

Palloc Portable linked-list allocator for embedded / baremetal systems. Using the crate Include this in the [dependencies] section of Cargo.toml pallo

A doubly-linked list for Rust backed by generational-arena.

generational_token_list A doubly-linked list backed by generational-arena. Inspired by indexlist. Instead of returning pointers or numerical indices t

Doubly-linked list that stores key-node pairs.

key-node-list Doubly-linked list that stores key-node pairs. KeyNodeList is a doubly-linked list, it uses a hash map to maintain correspondence betwee

Experiments on blockchain technology (also known as Hashed & Zero-trust Verifiable Linked List)

AngeloChain Experiments on blockchain technology (also known as Hashed & Zero-trust Verifiable Linked List) ⚠️ Before We Get Started Before we get sta

Rust Vec Doubly Linked List

Rust Vec Doubly Linked List Just like doubly linked list(e.g. std::LinkedList), but supports that returning a index of the vec when push. And you can

The most fundamental type for async synchronization: an intrusive linked list of futures

wait-list This crate provides WaitList, the most fundamental type for async synchronization. WaitList is implemented as an intrusive linked list of fu

A safe `Pin`-based intrusive doubly-linked list in Rust

pin-list This crate provides PinList, a safe Pin-based intrusive doubly linked list. Example A thread-safe unfair async mutex. use pin_project_lite::p

LinkedBytes is a linked list of Bytes and BytesMut.
LinkedBytes is a linked list of Bytes and BytesMut.

LinkedBytes LinkedBytes is a linked list of Bytes and BytesMut (though we use VecDeque to implement it now). It is primarily used to manage Bytes and

A Rust doubly-linked intrusive list with Miri tests

Intrusive stack-allocated doubly-linked list example Quickstart cargo test Or to run the tests under Miri: rustup toolchain install nightly # if y

An inquiry into nondogmatic software development. An experiment showing double performance of the code running on JVM comparing to equivalent native C code.
An inquiry into nondogmatic software development. An experiment showing double performance of the code running on JVM comparing to equivalent native C code.

java-2-times-faster-than-c An experiment showing double performance of the code running on JVM comparing to equivalent native C code ⚠️ The title of t

Parallel finance a decentralized lending protocol built on top of the Polkadot ecosystem. Our unique approach will allow users to earn
Parallel finance a decentralized lending protocol built on top of the Polkadot ecosystem. Our unique approach will allow users to earn "double interests" from staking and lending their tokens simultaneously.

Parallel Finance A new Cumulus-based Substrate node, ready for hacking 🚀 Getting Started Follow these steps to get started with the Cumulus Template

Avoid double indirection in nested smart pointers.

Pierce Avoid double indirection in nested smart pointers. The Pierce stuct allows you to cache the deref result of doubly-nested smart pointers. Quick

🐎 Daac Horse: Double-Array Aho-Corasick in Rust

🐎 daachorse Daac Horse: Double-Array Aho-Corasick Overview A fast implementation of the Aho-Corasick algorithm using Double-Array Trie. Examples use

Pure Rust implementation of the Double Ratchet algorithm
Pure Rust implementation of the Double Ratchet algorithm

Double Ratchet A pure Rust implementation of the Double Ratchet, as specified by Trevor Perrin and Moxie Marlinspike. The Double Ratchet allows two us

Click-once - A small tiny little binary to fix undesired mouse double clicks in Windows, written in Rust.

click-once A small tiny little binary to fix malfunctioning mouse double clicks in Windows, written in Rust. Minimal executable with little to no over

Shellfirm - Intercept any risky patterns (default or defined by you) and prompt you a small challenge for double verification
Shellfirm - Intercept any risky patterns (default or defined by you) and prompt you a small challenge for double verification

shellfirm Opppppsss you did it again? 😱 😱 😰 Protect yourself from yourself! rm -rf * git reset --hard before saving? kubectl delete ns which going

🦞 Rust library of natural language dictionaries using character-wise double-array tries.

🦞 Crawdad: ChaRActer-Wise Double-Array Dictionary Overview Crawdad is a library of natural language dictionaries using character-wise double-array tr

🐎 A fast implementation of the Aho-Corasick algorithm using the compact double-array data structure. (Python wrapper for daachorse)

python-daachorse daachorse is a fast implementation of the Aho-Corasick algorithm using the compact double-array data structure. This is a Python wrap

wait-free spsc linked-list queue with individually reusable nodes

A wait-free single-producer single-consumer linked-list queue with individually reusable nodes.

glowcoil 22 Dec 26, 2022
Doubly-Linked List Implementation in Rust

Doubly-Linked List Implementation in Rust Purely for educational and recreational purposes. For real world production please use std::collections::Lin

Tsoding 9 Jul 28, 2022
A doubly-linked list for Rust backed by generational-arena.

generational_token_list A doubly-linked list backed by generational-arena. Inspired by indexlist. Instead of returning pointers or numerical indices t

null 9 Dec 10, 2022
Rust Vec Doubly Linked List

Rust Vec Doubly Linked List Just like doubly linked list(e.g. std::LinkedList), but supports that returning a index of the vec when push. And you can

~ 2 May 1, 2022
A Rust doubly-linked intrusive list with Miri tests

Intrusive stack-allocated doubly-linked list example Quickstart cargo test Or to run the tests under Miri: rustup toolchain install nightly # if y

Cliff L. Biffle 9 Dec 4, 2022
Avoid double indirection in nested smart pointers.

Pierce Avoid double indirection in nested smart pointers. The Pierce stuct allows you to cache the deref result of doubly-nested smart pointers. Quick

null 11 Jan 12, 2022
A number of collections, such as linked-lists, binary-trees, or B-Trees are most easily implemented with aliasing pointers.

StaticRc is a safe reference-counted pointer, similar to Rc or Arc, though performing its reference-counting at compile-time rather than run-time, and

null 372 Dec 19, 2022
Display linked packages for compiled rust binaries

cargo-linked Display the packages a rust binary is linked against. As cargo subcommand! Easy said: run cargo linked to find out which packages you mus

Jojii 1 Jun 7, 2021
A proof of concept implementation of cyclic data structures in stable, safe, Rust.

A proof of concept implementation of cyclic data structures in stable, safe, Rust. This demonstrates the combined power of the static-rc crate and the

null 157 Dec 28, 2022
wait-free spsc linked-list queue with individually reusable nodes

A wait-free single-producer single-consumer linked-list queue with individually reusable nodes.

glowcoil 22 Dec 26, 2022