Struct Group

pub struct Group<T, K: ?Sized, I> { /* private fields */ }

Group of indexes distinguished by a prefix.

All indexes in the group have the same type. Indexes are initialized lazily; i.e., no initialization is performed when the group is created.

Safety

Using a group within a group (including indirectly via components) can lead to index collision if the keys in both groups have variable length (e.g., keys are strings). A collision in turn may result in logical errors and data corruption. For example:

type StrGroup<T> = Group<T, str, ListIndex<<T as Access>::Base, u64>>;

let db = TemporaryDB::new();
let fork = db.fork();
let outer_group: Group<_, str, StrGroup<_>> =
    FromAccess::from_access(&fork, "group".into()).unwrap();
outer_group.get("foo").get("bar").extend(vec![1, 2]);
outer_group.get("foob").get("ar").push(3);
// Both accessed lists have the same address and thus share the same data:
assert_eq!(
    fork.get_list(("group", "foobar")).iter().collect::<Vec<u64>>(),
    vec![1, 2, 3]
);

Examples

let db = TemporaryDB::new();
let fork = db.fork();
let group: Group<_, u64, ListIndex<_, u64>> = fork.get_group("group");
group.get(&1).push(1);
group.get(&2).extend(vec![1, 2, 3]);
// Members of the group can be accessed independently.
assert_eq!(fork.get_list::<_, u64>(("group", &2_u64)).len(), 3);

// It is possible to enumerate keys in the group, but only if the underlying access
// is readonly.
let group: Group<_, u64, ListIndex<_, u64>> = fork.readonly().get_group("group");
assert_eq!(group.keys().collect::<Vec<_>>(), vec![1, 2]);

Group keys can be unsized:

let group: Group<_, str, ListIndex<_, u64>> = fork.get_group("unsized_group");
group.get("foo").push(1);
group.get("bar").push(42);

Implementations

impl<T, K, I> Group<T, K, I>

where T: Access, K: BinaryKey + ?Sized, I: FromAccess<T>,

pub fn get(&self, key: &K) -> I

Gets an index corresponding to the specified key.

Panics

If the index is present and has a wrong type.

impl<T, K, I> Group<T, K, I>

where T: Access, T::Base: AsReadonly<Readonly = T::Base>, K: BinaryKey + ?Sized,

pub fn keys(&self) -> GroupKeys<T::Base, K>

Iterator over keys in this group.

The iterator buffers keys in memory and may become inconsistent. Although the Rust type system prevents iterating over keys in a group based on Fork, it it still possible to make the iterator return inconsistent results. Indeed, for a group is based on ReadonlyFork, it is possible to add new indexes via Fork while the iteration is in progress.

For this reason, it is advised to use this method for groups based on ReadonlyFork only in the case where stale reads are tolerated or are prevented on the application level. Groups based on Snapshot implementations (including Patches) are not affected by this issue.

Trait Implementations

impl<T: Debug, K: Debug + ?Sized, I: Debug> Debug for Group<T, K, I>

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

Formats the value using the given formatter.

impl<T, K, I> FromAccess<T> for Group<T, K, I>

where T: Access, K: BinaryKey + ?Sized, I: FromAccess<T>,

fn from_access(access: T, addr: IndexAddress) -> Result<Self, AccessError>

Constructs the object at the given address.

fn from_root(access: T) -> Result<Self, AccessError>

Constructs the object from the root of the access.