Struct NearList 

pub struct NearList<T> { /* private fields */ }

A linked list of T values stored in a Region.

Layout

#[repr(C)] — 8 bytes, align_of::<i32>() alignment:

Offset	Field	Type	Description
0	head	i32	Self-relative offset to first segment
4	len	u32	TOTAL element count across all segments

When len == 0, head is 0 (no valid segment). When non-empty, head is a self-relative offset from the head field itself to the first Segment<T>.

NearList<T> is not Copy or Clone — moving it would invalidate the self-relative offset.

After trim, all elements live in a single contiguous segment for cache-friendly iteration.

Segment chain

A non-empty list consists of one or more Segment<T> nodes linked by self-relative next pointers (next == 0 terminates the chain). Each segment stores a contiguous array of T values immediately after its header.

Mutation operations (splice_list, push_front, extend_list) may produce multi-segment lists. trim compacts all segments into one, restoring O(1) indexing and cache-friendly iteration.

Soundness

Provenance: Segment walking uses with_exposed_provenance to follow self-relative next pointers, recovering the allocation’s provenance exposed by AlignedBuf::grow. Same pattern as Near<T>.

Invariant: len == 0 ⟺ head == 0. Enforced by all list-patching methods which write both fields atomically.

Implementations

impl<T: Flat> NearList<T>

pub const fn len(&self) -> usize

Returns the number of elements.

Examples

use nearest::{Flat, NearList, Region, empty, list};

#[derive(Flat)]
struct Root { items: NearList<u32> }

let region = Region::new(Root::make(list([1u32, 2, 3])));
assert_eq!(region.items.len(), 3);

let empty_region = Region::new(Root::make(empty()));
assert_eq!(empty_region.items.len(), 0);

pub const fn is_empty(&self) -> bool

Returns true if the list has no elements.

Examples

use nearest::{Flat, NearList, Region, empty, list};

#[derive(Flat)]
struct Root { items: NearList<u32> }

let region = Region::new(Root::make(empty()));
assert!(region.items.is_empty());

let region = Region::new(Root::make(list([1u32])));
assert!(!region.items.is_empty());

pub fn segment_count(&self) -> usize

Returns the number of segments in the chain.

After trim, this is always 0 (empty) or 1.

Examples

use nearest::{Flat, NearList, Region, list};

#[derive(Flat)]
struct Root { items: NearList<u32> }

let mut region = Region::new(Root::make(list([1u32, 2, 3])));
assert_eq!(region.items.segment_count(), 1);

// push_front adds a new segment.
region.session(|s| {
  let items = s.nav(s.root(), |r| &r.items);
  s.push_front(items, 0u32);
});
assert_eq!(region.items.segment_count(), 2);

// trim consolidates into one segment.
region.trim();
assert_eq!(region.items.segment_count(), 1);

pub fn last(&self) -> Option<&T>

Returns a reference to the last element, or None if empty.

O(n): requires full traversal of the segment chain to find the last segment, then indexes its final element.

Examples

use nearest::{Flat, NearList, Region, empty, list};

#[derive(Flat)]
struct Root { items: NearList<u32> }

let region = Region::new(Root::make(list([10u32, 20, 30])));
assert_eq!(region.items.last(), Some(&30));

let region = Region::new(Root::make(empty()));
assert_eq!(region.items.last(), None);

pub fn contains(&self, item: &T) -> bool

where T: PartialEq,

Returns true if the list contains an element equal to the given value.

Examples

use nearest::{Flat, NearList, Region, empty, list};

#[derive(Flat)]
struct Root { items: NearList<u32> }

let region = Region::new(Root::make(list([1u32, 2, 3])));
assert!(region.items.contains(&2));
assert!(!region.items.contains(&4));

let region = Region::new(Root::make(empty()));
assert!(!region.items.contains(&1));

pub fn first(&self) -> Option<&T>

Returns a reference to the first element, or None if empty.

Examples

use nearest::{Flat, NearList, Region, empty, list};

#[derive(Flat)]
struct Root { items: NearList<u32> }

let region = Region::new(Root::make(list([10u32, 20])));
assert_eq!(region.items.first(), Some(&10));

let region = Region::new(Root::make(empty()));
assert_eq!(region.items.first(), None);

pub fn iter(&self) -> NearListIter<'_, T>

Returns an iterator over the elements.

Construction is O(1). Within a segment, iteration is contiguous (ptr.add(1)). At segment boundaries, follows next pointers to the next segment. After trim, iteration is pure array traversal.

Examples

use nearest::{Flat, NearList, Region, list};

#[derive(Flat)]
struct Root { items: NearList<u32> }

let region = Region::new(Root::make(list([10u32, 20, 30])));
let sum: u32 = region.items.iter().sum();
assert_eq!(sum, 60);

// Also works with for-in (via IntoIterator for &NearList<T>).
let mut count = 0;
for item in &region.items {
  count += 1;
  assert!(*item >= 10);
}
assert_eq!(count, 3);

impl<T: Flat> NearList<T>

pub fn get(&self, index: usize) -> Option<&T>

Returns a reference to the element at index, or None if out of bounds.

O(1) when all elements are in a single segment (always true after trim). Falls back to O(n) segment walk otherwise.

Examples

use nearest::{Flat, NearList, Region, list};

#[derive(Flat)]
struct Root { items: NearList<u32> }

let region = Region::new(Root::make(list([10u32, 20, 30])));
assert_eq!(region.items.get(0), Some(&10));
assert_eq!(region.items.get(2), Some(&30));
assert_eq!(region.items.get(3), None);

Trait Implementations

impl<T: Flat + Debug> Debug for NearList<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Flat + Display> Display for NearList<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Flat> Flat for NearList<T>

unsafe fn deep_copy(&self, p: &mut impl Patch, at: Pos)

Deep-copy self into the buffer at position at, patching all self-relative pointers so they remain valid in the new location.

fn validate(addr: usize, buf: &[u8]) -> Result<(), ValidateError>

Validate that buf[addr..] contains a valid representation of Self.

fn validate_option(addr: usize, buf: &[u8]) -> Result<(), ValidateError>

Validate an Option<Self> at addr in buf.

impl<T: Flat> Index<usize> for NearList<T>

fn index(&self, index: usize) -> &T

Access the element at index.

O(1) when all elements are in a single segment (always true after trim). Falls back to O(n) segment walk otherwise.

Panics

Panics if index >= self.len().

type Output = T

The returned type after indexing.

impl<'a, T: Flat> IntoIterator for &'a NearList<T>

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = NearListIter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: Flat + PartialEq> PartialEq for NearList<T>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Flat + Eq> Eq for NearList<T>