Crate pallet_paged_list

Made with Substrate, for DotSama.

-

Paged List Pallet

A thin wrapper pallet around a paged_list::StoragePagedList. It provides an API for a single paginated list. It can be instantiated multiple times to provide multiple lists.

Overview

The pallet is quite unique since it does not expose any Calls, Errors or Events. All interaction goes through the implemented [StorageList][frame_support::storage::StorageList] trait.

A fuzzer for testing is provided in crate pallet-paged-list-fuzzer.

Examples

1. Appending some data to the list can happen either by Pallet::append_one:

#[test]
fn append_one_works() {
	test_closure(|| {
		PagedList::append_one(1);

		assert_eq!(PagedList::iter().collect::<Vec<_>>(), vec![1]);
	});
}

2. or by Pallet::append_many. This should always be preferred to repeated calls to Pallet::append_one:

#[test]
fn append_many_works() {
	test_closure(|| {
		PagedList::append_many(0..3);

		assert_eq!(PagedList::iter().collect::<Vec<_>>(), vec![0, 1, 2]);
	});
}

3. If you want to append many values (ie. in a loop), then best use the Pallet::appender:

#[test]
fn appender_works() {
	use frame_support::storage::StorageAppender;
	test_closure(|| {
		let mut appender = PagedList::appender();

		appender.append(0);
		appender.append(1); // Repeated calls are fine here.
		appender.append_many(2..4);

		assert_eq!(PagedList::iter().collect::<Vec<_>>(), vec![0, 1, 2, 3]);
	});
}

4. Iterating over the list can be done with Pallet::iter. It uses the standard Iterator trait:

#[test]
fn iter_works() {
	test_closure(|| {
		PagedList::append_many(0..10);
		let mut iter = PagedList::iter();

		assert_eq!(iter.next(), Some(0));
		assert_eq!(iter.next(), Some(1));
		assert_eq!(iter.collect::<Vec<_>>(), (2..10).collect::<Vec<_>>());
	});
}

5. Draining elements happens through the Pallet::drain iterator. Note that even peeking a value will already remove it.

#[test]
fn drain_works() {
	test_closure(|| {
		PagedList::append_many(0..3);
		PagedList::drain().next();
		assert_eq!(PagedList::iter().collect::<Vec<_>>(), vec![1, 2], "0 is drained");
		PagedList::drain().peekable().peek();
		assert_eq!(PagedList::iter().collect::<Vec<_>>(), vec![2], "Peeking removed 1");
	});
}

Pallet API

None. Only things to consider is the Config traits.

Low Level / Implementation Details

Implementation details are documented in paged_list::StoragePagedList. All storage entries are prefixed with a unique prefix that is generated by ListPrefix.

Re-exports

• pub use pallet::*;

Modules

• mock
  Helpers for tests.
• pallet
  The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.

Structs

• ListPrefix
  Generates a unique storage prefix for each instance of the pallet.
• StoragePagedList
  A paginated storage list.