Skip to main content

Entity

Trait Entity 

Source
pub trait Entity: Sized {
    type Key: PrimaryKey;

    const SCHEMA: &'static EntitySchema;

    // Required methods
    fn declaration_path() -> &'static str;
    fn key(&self) -> Self::Key;
    fn validate(&self) -> Result<(), Error>;
    fn encode(&self) -> Result<Vec<u8>, Error>;
    fn decode(bytes: &[u8]) -> Result<Self, Error>;
}
Expand description

Codec boundary emitted by #[entity]; hand-written implementations are unsupported. Typed references use Rust resolution; an unresolved name fails compilation:

ⓘ
use ic_db::entity;
#[entity(pk(field="id"), index(field="target"), fields(
    field(name="id",value(item(prim="Nat64"))),
    field(name="target",value(item(prim="Nat64")),references(entity="Missing"))))]
struct Example {}

Lookups require the declared key type; integers cannot stand in for ULIDs:

ⓘ
use ic_db::{entity, Database};
#[entity(pk(field="id"), fields(field(name="id",value(item(prim="Ulid")))))]
struct Asset {}
fn wrong_key(db: &Database) { let _ = db.get::<Asset>(7_u64); }

Integer key widths are exact, without implicit widening:

ⓘ
use ic_db::{entity, Database};
#[entity(pk(field="id"), fields(field(name="id",value(item(prim="Nat8")))))]
struct Small {}
fn wrong_width(db: &Database) { let _ = db.get::<Small>(7_u64); }

Field names come from the declaration. A missing name field cannot resolve to the entity’s logical name, even when Entity is in scope.

ⓘ
use ic_db::{entity, Entity};
#[entity(pk(field="id"), fields(field(name="id", value(item(prim="Nat64")))))]
struct Entry {}
let _ = Entry::NAME;
ⓘ
use ic_db::{entity, Entity};
#[entity(pk(field="id"), fields(field(name="id", value(item(prim="Nat64")))))]
struct Entry {}
let _ = Entry::ENTITY_NAME;

Required Associated Constants§

Source

const SCHEMA: &'static EntitySchema

This executable’s compiled entity contract.

Required Associated Types§

Source

type Key: PrimaryKey

Exact supplied primary-key type, selected by the declared field.

Required Methods§

Source

fn declaration_path() -> &'static str

Rust-resolved declaration path for host schema assembly.

Source

fn key(&self) -> Self::Key

Read the application’s primary key without encoding or inspecting indexes.

Source

fn validate(&self) -> Result<(), Error>

Validate declared field bounds before encoding; no persistent effects.

§Errors

Refuses values outside the authored field contract.

Source

fn encode(&self) -> Result<Vec<u8>, Error>

Encode canonical stored fields within the row envelope.

§Errors

Returns a limit refusal when the row cannot be encoded within its bounds.

Source

fn decode(bytes: &[u8]) -> Result<Self, Error>

Decode an admitted row; this does not open a database or admit a schema.

§Errors

Returns corruption for malformed stored bytes.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§