Struct FixedSet 

pub struct FixedSet<T, const SIZE: usize> { /* private fields */ }

A fixed-capacity set for storing unique elements.

FixedSet maintains a collection of unique elements with compile-time capacity bounds. It provides efficient insertion, removal, and lookup operations while maintaining element uniqueness.

Type Parameters

• T - The element type. Must implement Default + Copy + PartialEq.
• SIZE - The maximum number of elements the set can hold (compile-time constant).

Examples

use satellite_bitcoin::generic::fixed_set::FixedSet;

let mut set: FixedSet<u32, 8> = FixedSet::new();

set.insert(3).unwrap();
set.insert(5).unwrap();
assert!(set.contains(&3));
assert_eq!(set.len(), 2);

// Duplicate insertion fails
assert!(set.insert(3).is_err());

// Remove elements
assert_eq!(set.remove(&3), Some(3));
assert_eq!(set.len(), 1);

Memory Layout

The set stores elements in a contiguous array followed by a length field. Element order is not preserved across insertions and removals due to the swap-remove optimization used for O(1) removal.

Bytemuck Compatibility

FixedSet implements Pod and Zeroable when T implements these traits, making it suitable for zero-copy serialization in on-chain programs.

Implementations

impl<T, const SIZE: usize> FixedSet<T, SIZE>

where T: Default + Copy + PartialEq,

pub fn new() -> FixedSet<T, SIZE>

Creates an empty FixedSet.

Examples

use satellite_bitcoin::generic::fixed_set::FixedSet;

let set: FixedSet<u32, 10> = FixedSet::new();
assert!(set.is_empty());
assert_eq!(set.len(), 0);

pub fn len(&self) -> usize

Returns the number of elements currently stored in the set.

Examples

use satellite_bitcoin::generic::fixed_set::FixedSet;

let mut set: FixedSet<u32, 10> = FixedSet::new();
assert_eq!(set.len(), 0);

set.insert(42).unwrap();
assert_eq!(set.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if the set contains no elements.

Examples

use satellite_bitcoin::generic::fixed_set::FixedSet;

let mut set: FixedSet<u32, 10> = FixedSet::new();
assert!(set.is_empty());

set.insert(42).unwrap();
assert!(!set.is_empty());

pub fn iter(&self) -> impl Iterator<Item = &T>

Returns an iterator over all items currently in the set.

Examples

use satellite_bitcoin::generic::fixed_set::FixedSet;

let mut set: FixedSet<u32, 10> = FixedSet::new();
set.insert(1).unwrap();
set.insert(2).unwrap();

let collected: Vec<_> = set.iter().copied().collect();
assert_eq!(collected.len(), 2);
assert!(collected.contains(&1));
assert!(collected.contains(&2));

pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut T>

Returns a mutable iterator over all items currently in the set.

Examples

use satellite_bitcoin::generic::fixed_set::FixedSet;

let mut set: FixedSet<u32, 10> = FixedSet::new();
set.insert(1).unwrap();
set.insert(2).unwrap();

for item in set.iter_mut() {
    *item *= 10;
}

assert!(set.contains(&10));
assert!(set.contains(&20));

pub fn insert_or_modify<E, F>(&mut self, item: T, modify: F) -> Result<(), E>

where F: FnMut(&mut T) -> Result<(), E>, E: From<FixedSetError>,

Inserts item into the set if it is not already present. If it is present, modifies it using the provided function.

This is useful for implementing “upsert” semantics where you want to insert a new item or update an existing one.

Examples

use satellite_bitcoin::generic::fixed_set::{FixedSet, FixedSetError};

#[derive(Clone, Copy, Debug, Default)]
struct Counter { id: u32, count: u32 }

impl PartialEq for Counter {
    fn eq(&self, other: &Self) -> bool {
        self.id == other.id // Only compare by ID
    }
}

impl Eq for Counter {}

#[derive(Debug)]
enum MyError {
    SetError(FixedSetError),
}

impl From<FixedSetError> for MyError {
    fn from(e: FixedSetError) -> Self {
        MyError::SetError(e)
    }
}

let mut set: FixedSet<Counter, 10> = FixedSet::new();

// Insert new item
set.insert_or_modify(
    Counter { id: 1, count: 1 },
    |_| Ok::<(), MyError>(())
).unwrap();

// Update existing item
set.insert_or_modify(
    Counter { id: 1, count: 0 }, // count doesn't matter for lookup
    |existing| { existing.count += 1; Ok::<(), MyError>(()) }
).unwrap();

assert_eq!(set.find(&Counter { id: 1, count: 0 }).unwrap().count, 2);

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

where T: PartialEq<Q>,

Returns true if the set already contains item.

Examples

use satellite_bitcoin::generic::fixed_set::FixedSet;

let mut set: FixedSet<u32, 10> = FixedSet::new();
assert!(!set.contains(&42));

set.insert(42).unwrap();
assert!(set.contains(&42));

pub fn find<Q>(&self, item: &Q) -> Option<&T>

where T: PartialEq<Q>,

Returns the first item equal to item in the set.

This is useful when you need to access the actual stored item that matches your query, especially when using custom equality implementations.

Examples

use satellite_bitcoin::generic::fixed_set::FixedSet;

let mut set: FixedSet<u32, 10> = FixedSet::new();
set.insert(42).unwrap();

assert_eq!(set.find(&42), Some(&42));
assert_eq!(set.find(&99), None);

pub fn find_mut<Q>(&mut self, item: &Q) -> Option<&mut T>

where T: PartialEq<Q>,

Returns the first item equal to item in the set (mutable reference).

Examples

use satellite_bitcoin::generic::fixed_set::FixedSet;

let mut set: FixedSet<u32, 10> = FixedSet::new();
set.insert(42).unwrap();

if let Some(item) = set.find_mut(&42) {
    *item = 100;
}

assert!(set.contains(&100));
assert!(!set.contains(&42));

pub fn insert(&mut self, item: T) -> Result<(), FixedSetError>

Attempts to insert item into the set.

Errors

• Returns Err(FixedSetError::Duplicate) if the item already exists in the set.
• Returns Err(FixedSetError::Full) if the set is at full capacity.

Examples

use satellite_bitcoin::generic::fixed_set::{FixedSet, FixedSetError};

let mut set: FixedSet<u32, 2> = FixedSet::new();
assert!(set.insert(1).is_ok());
assert!(set.insert(2).is_ok());

// Duplicate
assert_eq!(set.insert(1), Err(FixedSetError::Duplicate));
// Full
assert_eq!(set.insert(3), Err(FixedSetError::Full));

pub fn remove<Q>(&mut self, item: &Q) -> Option<T>

where T: PartialEq<Q>,

Removes an item equal to item from the set and returns it.

Uses swap-remove for O(1) performance, which means element order is not preserved.

Examples

use satellite_bitcoin::generic::fixed_set::FixedSet;

let mut set: FixedSet<u32, 10> = FixedSet::new();
set.insert(42).unwrap();

assert_eq!(set.remove(&42), Some(42));
assert_eq!(set.remove(&42), None);
assert_eq!(set.len(), 0);

pub fn pop(&mut self) -> Option<T>

Removes and returns an arbitrary element from the set (the last one).

pub fn as_slice(&self) -> &[T]

Returns the elements of the set as a slice.

pub fn as_mut_slice(&mut self) -> &mut [T]

Returns the elements of the set as a mutable slice.

pub fn try_from_iter<I>(iter: I) -> Result<FixedSet<T, SIZE>, FixedSetError>

where I: IntoIterator<Item = T>,

Creates a FixedSet from any iterator, returning an error if the number of unique elements exceeds the set’s capacity.

Duplicate elements yielded by the iterator are ignored (because a set cannot contain the same value twice). However, if inserting additional unique elements would exceed the compile-time capacity SIZE, the construction fails with FixedSetError::Full.

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

Returns a reference to the first element in the set (if any).

This is a convenience helper useful when the set is known to hold at most one element (e.g. single‐rune outputs). It avoids having to call as_slice().first() at every call-site.

Trait Implementations

impl<T, const SIZE: usize> Clone for FixedSet<T, SIZE>

where T: Clone,

fn clone(&self) -> FixedSet<T, SIZE>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T, const SIZE: usize> Copy for FixedSet<T, SIZE>

where T: Copy,

impl<T, const SIZE: usize> Debug for FixedSet<T, SIZE>

where T: Debug,

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

Formats the value using the given formatter.

impl<T, const SIZE: usize> Default for FixedSet<T, SIZE>

where T: Default + Copy + PartialEq,

fn default() -> FixedSet<T, SIZE>

Returns the “default value” for a type.

impl<T, const SIZE: usize> FixedCapacitySet for FixedSet<T, SIZE>

where T: Default + Copy + PartialEq + Debug,

type Item = T

The element type stored in the set.

fn capacity(&self) -> usize

Maximum number of elements the set can hold.

fn len(&self) -> usize

Current number of stored elements.

fn contains<Q>(&self, item: &Q) -> bool

where <FixedSet<T, SIZE> as FixedCapacitySet>::Item: PartialEq<Q>,

Check whether the set currently contains item.

fn find<Q>( &self, item: &Q, ) -> Option<&<FixedSet<T, SIZE> as FixedCapacitySet>::Item>

where <FixedSet<T, SIZE> as FixedCapacitySet>::Item: PartialEq<Q>,

Find the first item equal to item in the set.

fn find_mut<Q>( &mut self, item: &Q, ) -> Option<&mut <FixedSet<T, SIZE> as FixedCapacitySet>::Item>

where <FixedSet<T, SIZE> as FixedCapacitySet>::Item: PartialEq<Q>,

Find the first item equal to item in the set and return it.

fn insert( &mut self, item: <FixedSet<T, SIZE> as FixedCapacitySet>::Item, ) -> Result<(), FixedSetError>

Attempt to insert item. Returns Ok(()) on success or an appropriate FixedSetError.

fn insert_or_modify<E, F>( &mut self, item: <FixedSet<T, SIZE> as FixedCapacitySet>::Item, modify: F, ) -> Result<(), E>

where F: FnMut(&mut <FixedSet<T, SIZE> as FixedCapacitySet>::Item) -> Result<(), E>, E: From<FixedSetError>,

Inserts item into the set if it is not already present. If it is present, modifies it using the provided function. Returns Ok(()) on success or an appropriate FixedSetError.

fn remove<Q>( &mut self, item: &Q, ) -> Option<<FixedSet<T, SIZE> as FixedCapacitySet>::Item>

where <FixedSet<T, SIZE> as FixedCapacitySet>::Item: PartialEq<Q>,

Remove item if present, returning it.

fn as_slice(&self) -> &[<FixedSet<T, SIZE> as FixedCapacitySet>::Item]

Access the underlying slice of active items.

fn as_mut_slice( &mut self, ) -> &mut [<FixedSet<T, SIZE> as FixedCapacitySet>::Item]

Returns the elements of the set as a mutable slice.

fn iter(&self) -> impl Iterator<Item = &Self::Item>

Iterate over the set.

fn iter_mut(&mut self) -> impl Iterator<Item = &mut Self::Item>

Iterate over the set mutably.

impl<T, const SIZE: usize> From<FixedList<T, SIZE>> for FixedSet<T, SIZE>

where T: Default + Copy + PartialEq,

fn from(list: FixedList<T, SIZE>) -> FixedSet<T, SIZE>

Converts to this type from the input type.

impl<T, const SIZE: usize> From<FixedSet<T, SIZE>> for FixedList<T, SIZE>

where T: Default + Clone + Copy + PartialEq,

fn from(set: FixedSet<T, SIZE>) -> FixedList<T, SIZE>

Converts to this type from the input type.

impl<T, const SIZE: usize> Pod for FixedSet<T, SIZE>

where T: Pod,

impl<T, const SIZE: usize> PushPopCollection<T> for FixedSet<T, SIZE>

where T: Default + Copy + PartialEq,

fn push(&mut self, item: T) -> Result<(), PushPopError>

Adds an element to the collection.

fn pop(&mut self) -> Option<T>

Removes and returns the last element, or None if the collection is empty.

fn as_slice(&self) -> &[T]

Returns a slice view of all elements in the collection.

fn len(&self) -> usize

Returns the number of elements in the collection.

fn max_size(&self) -> usize

Returns the maximum number of elements the collection can hold.

impl<T, const SIZE: usize> TryFrom<&[T]> for FixedSet<T, SIZE>

where T: Default + Copy + PartialEq,

type Error = FixedSetError

The type returned in the event of a conversion error.

fn try_from( slice: &[T], ) -> Result<FixedSet<T, SIZE>, <FixedSet<T, SIZE> as TryFrom<&[T]>>::Error>

Performs the conversion.

impl<T, const SIZE: usize> Zeroable for FixedSet<T, SIZE>

where T: Zeroable,

fn zeroed() -> Self

Calls zeroed.