Struct RangedIndex 

pub struct RangedIndex<Tbl: Table, IndexType, Idx: IndexIsRanged> { /* private fields */ }

A handle to a B-Tree or Direct index on a table.

To get one of these from a ReducerContext, use:

ctx.db.{table}().{index}()

for a table table and an index index.

Example:

use spacetimedb::{table, RangedIndex, ReducerContext, DbContext};

#[table(accessor = user,
    index(accessor = dogs_and_name, btree(columns = [dogs, name])))]
struct User {
    id: u32,
    name: String,
    /// Number of dogs owned by the user.
    dogs: u64
}

fn demo(ctx: &ReducerContext) {
    let by_dogs_and_name: RangedIndex<_, (u64, String), _> = ctx.db.user().dogs_and_name();
}

For single-column indexes, use the name of the column:

use spacetimedb::{table, RangedIndex, ReducerContext, DbContext};

#[table(accessor = user)]
struct User {
    id: u32,
    username: String,
    #[index(btree)]
    dogs: u64
}

fn demo(ctx: &ReducerContext) {
    let by_dogs: RangedIndex<_, (u64,), _> = ctx.db().user().dogs();
}

Implementations

impl<Tbl: Table, IndexType, Idx: IndexIsRanged> RangedIndex<Tbl, IndexType, Idx>

pub fn filter<B, K>( &self, b: B, ) -> impl Iterator<Item = Tbl::Row> + use<B, K, Tbl, IndexType, Idx>

where B: IndexScanRangeBounds<IndexType, K>,

Returns an iterator over all rows in the database state where the indexed column(s) match the bounds b.

This method accepts a variable numbers of arguments using the [IndexScanRangeBounds] trait. This depends on the type of the B-Tree index. b may be:

• A value for the first indexed column.
• A range of values for the first indexed column.
• A tuple of values for any prefix of the indexed columns, optionally terminated by a range for the next.

For example:

use spacetimedb::{table, ReducerContext, RangedIndex};

#[table(accessor = user,
    index(accessor = dogs_and_name, btree(columns = [dogs, name])))]
struct User {
    id: u32,
    name: String,
    dogs: u64
}

fn demo(ctx: &ReducerContext) {
    let by_dogs_and_name: RangedIndex<_, (u64, String), _> = ctx.db.user().dogs_and_name();

    // Find user with exactly 25 dogs.
    for user in by_dogs_and_name.filter(25u64) { // The `u64` is required, see below.
        /* ... */
    }

    // Find user with at least 25 dogs.
    for user in by_dogs_and_name.filter(25u64..) {
        /* ... */
    }

    // Find user with exactly 25 dogs, and a name beginning with "J".
    for user in by_dogs_and_name.filter((25u64, "J".."K")) {
        /* ... */
    }

    // Find user with exactly 25 dogs, and exactly the name "Joseph".
    for user in by_dogs_and_name.filter((25u64, "Joseph")) {
        /* ... */
    }

    // You can also pass arguments by reference if desired.
    for user in by_dogs_and_name.filter((&25u64, &"Joseph".to_string())) {
        /* ... */
    }
}

NOTE: An unfortunate interaction between Rust’s trait solver and integer literal defaulting rules means that you must specify the types of integer literals passed to filter and find methods via the suffix syntax, like 21u32.

If you don’t, you’ll see a compiler error like:

error[E0271]: type mismatch resolving `<i32 as FilterableValue>::Column == u32`
   --> modules/rust-wasm-test/src/lib.rs:356:48
    |
356 |     for person in ctx.db.person().age().filter(21) {
    |                                         ------ ^^ expected `u32`, found `i32`
    |                                         |
    |                                         required by a bound introduced by this call
    |
    = note: required for `i32` to implement `IndexScanRangeBounds<(u32,), SingleBound>`
note: required by a bound in `RangedIndex::<Tbl, IndexType, Idx>::filter`
    |
410 |     pub fn filter<B, K>(&self, b: B) -> impl Iterator<Item = Tbl::Row>
    |            ------ required by a bound in this associated function
411 |     where
412 |         B: IndexScanRangeBounds<IndexType, K>,
    |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `RangedIndex::<Tbl, IndexType, Idx>::filter`

pub fn delete<B, K>(&self, b: B) -> u64

where B: IndexScanRangeBounds<IndexType, K>,

Deletes all rows in the database state where the indexed column(s) match the bounds b.

This method accepts a variable numbers of arguments using the [IndexScanRangeBounds] trait. This depends on the type of the B-Tree index. b may be:

• A value for the first indexed column.
• A range of values for the first indexed column.
• A tuple of values for any prefix of the indexed columns, optionally terminated by a range for the next.

For example:

use spacetimedb::{table, ReducerContext, RangedIndex};

#[table(accessor = user,
    index(accessor = dogs_and_name, btree(columns = [dogs, name])))]
struct User {
    id: u32,
    name: String,
    dogs: u64
}

fn demo(ctx: &ReducerContext) {
    let by_dogs_and_name: RangedIndex<_, (u64, String), _> = ctx.db.user().dogs_and_name();

    // Delete users with exactly 25 dogs.
    by_dogs_and_name.delete(25u64); // The `u64` is required, see below.

    // Delete users with at least 25 dogs.
    by_dogs_and_name.delete(25u64..);

    // Delete users with exactly 25 dogs, and a name beginning with "J".
    by_dogs_and_name.delete((25u64, "J".."K"));

    // Delete users with exactly 25 dogs, and exactly the name "Joseph".
    by_dogs_and_name.delete((25u64, "Joseph"));

    // You can also pass arguments by reference if desired.
    by_dogs_and_name.delete((&25u64, &"Joseph".to_string()));
}

NOTE: An unfortunate interaction between Rust’s trait solver and integer literal defaulting rules means that you must specify the types of integer literals passed to filter and find methods via the suffix syntax, like 21u32.

If you don’t, you’ll see a compiler error like:

error[E0271]: type mismatch resolving `<i32 as FilterableValue>::Column == u32`
   --> modules/rust-wasm-test/src/lib.rs:356:48
    |
356 |     for person in ctx.db.person().age().filter(21) {
    |                                         ------ ^^ expected `u32`, found `i32`
    |                                         |
    |                                         required by a bound introduced by this call
    |
    = note: required for `i32` to implement `IndexScanRangeBounds<(u32,), SingleBound>`
note: required by a bound in `RangedIndex::<Tbl, IndexType, Idx>::filter`
    |
410 |     pub fn filter<B, K>(&self, b: B) -> impl Iterator<Item = Tbl::Row>
    |            ------ required by a bound in this associated function
411 |     where
412 |         B: IndexScanRangeBounds<IndexType, K>,
    |            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ required by this bound in `RangedIndex::<Tbl, IndexType, Idx>::filter`

May panic if deleting any one of the rows would violate a constraint, though at present no such constraints exist.