Struct Collection 

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

An ordered collection of items addressed by Id.

Stored as a map from id to { k: order key, v: value }. Editing an item writes only that item; a move rewrites one order key; concurrent inserts from several collaborators interleave deterministically; deleting an item never disturbs another item’s identity. This is the default container for anything a user adds, reorders or removes.

A collection read from a document remembers each item’s order key, so a later change re-reads only the items it touched (Model::refresh) instead of the whole collection.

Cloning a collection shares its items: a clone copies one pointer per item, and an item is copied only when one of the collections sharing it changes it. A view holding the state it was shown therefore costs the next change one copied item, not a copy of every item.

Implementations

impl<T> Collection<T>

pub fn new() -> Collection<T>

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn membership(&self) -> Membership

Which ids the collection holds, in which order ([Membership]). Editing an item keeps it; adding, removing or moving one changes it.

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

Items in collection order.

pub fn at(&self, position: usize) -> Option<(&Id, &T)>

The item at position in collection order.

pub fn iter_mut(&mut self) -> IterMut<'_, T>

pub fn values(&self) -> Values<'_, T>

pub fn ids(&self) -> Ids<'_, T>

pub fn contains(&self, id: &Id) -> bool

pub fn position(&self, id: &Id) -> Option<usize>

pub fn get(&self, id: &Id) -> Option<&T>

pub fn get_mut(&mut self, id: &Id) -> Option<&mut T>

The item id, to change. Copies it first when a clone of this collection still shares it; no other item is copied.

pub fn quarantined(&self) -> &[Quarantined]

The stored items that did not read, each with why: the view shows the rest, and these are repaired by pushing a whole item under the id or removed ([Quarantined]).

pub fn discard(&mut self, id: &Id) -> bool

Forget the quarantined item id: the next write deletes it from the document, as it deletes any item no longer in the collection. Whether it was quarantined.

pub fn push(&mut self, id: Id, item: T) -> Id

Append an item. Returns its id for chaining. An id already present is replaced in place; a quarantined one is repaired by it.

pub fn insert(&mut self, index: usize, id: Id, item: T) -> Id

Insert an item at index (clamped to the end). An id already present is moved there.

pub fn remove(&mut self, id: &Id) -> Option<T>

pub fn move_to(&mut self, id: &Id, index: usize) -> bool

Move an item to index (clamped to the end). Returns whether it exists.

pub fn retain(&mut self, keep: impl FnMut(&Id, &T) -> bool)

pub fn sort_by(&mut self, compare: impl FnMut(&T, &T) -> Ordering)

Trait Implementations

impl ChildList for Collection<ChildRef>

fn listed(&self) -> Vec<(&Id, &ChildRef)>

Every child outside the trash, in order.

fn listed_of(&self, kind: &str) -> Vec<&Id>

The children of kind outside the trash, in order.

fn under(&self, group: Option<&Id>) -> Vec<&Id>

The children listed under group (none: at the top), outside the trash, in order.

fn in_trash(&self) -> Vec<&Id>

The children in the trash, in order.

fn lists(&self, id: &Id) -> bool

Whether id is listed outside the trash.

impl<T> Clone for Collection<T>

where T: Clone,

fn clone(&self) -> Collection<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Collection<T>

where T: Debug,

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

Formats the value using the given formatter.

impl<T> Default for Collection<T>

fn default() -> Collection<T>

Returns the “default value” for a type.

impl<T> FromIterator<(Id, T)> for Collection<T>

fn from_iter<I>(iter: I) -> Collection<T>

where I: IntoIterator<Item = (Id, T)>,

Creates a value from an iterator.

impl<T> Index<&Id> for Collection<T>

type Output = T

The returned type after indexing.

fn index(&self, id: &Id) -> &T

Performs the indexing (container[index]) operation.

impl<T> ItemSource for Collection<T>

where T: Model,

fn item_collection(&self, field: &'static str) -> ItemCollection

The first page of items with their labels.

fn item_presence(&self) -> usize

1 when there is an item, 0 when there is none.

fn label_of_item(&self, id: &Id) -> Option<String>

The label of the item id, when there is one.

fn item_texts(&self, field: &'static str, found: &mut Vec<ItemText>)

The labelled items with all their text, for search.

fn nested_items(&self, field: &'static str, out: &mut Vec<ItemCollection>)

The collections inside the first page of items, placed within them.

impl<T> Model for Collection<T>

where T: Model,

const SHAPE: Shape

How the value is laid out in the document; see Shape. Types written whole keep the default.

const CHECKS: bool = T::CHECKS

Whether this type or any value inside it has a #[model(check)] invariant; Self::check has nothing to do otherwise.

const OPS: bool = T::OPS

Whether this type or a value inside it has a vocabulary of its own (Operations, rich text’s): a record routes those edits’ gestures, landing places and schemas only into such fields, and never instantiates the routing for the others.

const TABLE: &'static ModelTable

The type’s functions as data, which a record holding it reaches it through ([crate::table]): by default its own functions, erased.

type Paths<R> = Path<R, Collection<T>>

The typed paths into a value of this type, rooted in the record R: a struct of field paths for a record, the Path itself for a value edited whole or through its own operations.

fn value_schema() -> Value

The JSON Schema of this value’s JSON form (Self::to_json), as the published field edit describes what a path takes; the default accepts any value.

fn field_type(types: &mut TypeSet) -> FieldType

This value’s type in the language-neutral vocabulary a surface publishes (FieldType), declaring the records and enums it names in types. The default describes no type: any value.

fn paths_at<R>(path: Path<R, Collection<T>>) -> Path<R, Collection<T>>

The paths of the value at path.

fn op_coalesces( path: &[Segment], previous: &Value, next: &Value, ) -> Option<bool>

Whether two edits in the own vocabulary of the value at path below this type are one gesture (Operations); None when nothing there has one.

fn op_continuable(path: &[Segment], op: &Value) -> Option<bool>

Whether a gesture may go on after the edit op at path.

fn op_describe(path: &[Segment], op: &Value) -> Option<OpDescription>

What the edit op at path below this type did, in the history entry’s terms (Operations::describe).

fn op_lands(&self, path: &[Segment], op: &Value) -> Option<Place>

Where the actor of the edit op at path below this value is after it applied.

fn op_schemas(prefix: &str, out: &mut Vec<(String, Value)>)

The schemas of the own vocabularies of the values below this type, by path pattern from prefix (* for every item).

fn to_json(&self) -> Value

The value as JSON: what [EditOp::Set] carries and history shows.

fn from_json(value: &Value) -> Result<Collection<T>, ModelError>

A value from its Self::to_json form.

fn edit( doc: &mut AutoCommit, slot: Slot<'_>, path: &[Segment], op: &EditOp, cx: &mut ActionCx, ) -> Result<(), ModelError>

Apply the field edit op at path, below the value in slot, touching only what it changes, then run the invariants of the values it touched. The default edits a value only as a whole.

fn check(&self) -> Result<(), Refusal>

Run every #[model(check)] invariant of this value and the values inside it.

fn get_at(&self, path: &[Segment]) -> Option<&(dyn Any + 'static)>

The value at path below this one, if it is there. A value with nothing inside it is found only at the empty path.

fn diff<R>( &self, after: &Collection<T>, path: &[Segment], out: &mut Vec<Edit<R>>, )

The field edits that turn self into after, at path below the record: what a surface that edited a local copy submits. The default sets the value whole when it changed; containers and records edit only what differs, item by item and field by field. A value that would store as it is (Self::stores_as) is compared in memory, without turning either side into JSON.

fn load( doc: &AutoCommit, value: &Value<'_>, id: &ExId, ) -> Result<Collection<T>, ModelError>

Read from the value a parent found in its slot.

fn store(&self, doc: &mut AutoCommit, slot: Slot<'_>) -> Result<(), ModelError>

Write self into slot, changing only what differs from what the slot already holds.

fn stores_as(&self, before: &Collection<T>) -> bool

Whether writing self over a slot that holds before, as a store left it, would change nothing: an in-memory comparison, so an action that changed one item of a long collection does not visit the others. Must only answer true when store would write no operation; the default answers false (unknown).

fn store_changed( &self, before: &Collection<T>, doc: &mut AutoCommit, slot: Slot<'_>, dirty: &Delta, ) -> Result<(), ModelError>

Write self into slot, which holds before: exactly the operations store would write, found by comparing with before where store would read the document.

fn refresh( &mut self, doc: &AutoCommit, value: &Value<'_>, id: &ExId, delta: &Delta, ) -> Result<(), ModelError>

Bring a value read earlier up to date after the changes in delta, re-reading only what they touched. value and id are what the parent’s slot holds now — the same object as when self was read, or the parent would have read it anew. The default reads the value again, which is right for scalars and short values.

fn collect_text(&self, out: &mut Vec<String>)

Append the human-readable text this value carries, for search indexing.

fn missing() -> Result<Collection<T>, ModelError>

The value of an absent slot. Types with a natural empty value return it, so a field added to a schema reads older documents without migration.

const NULLABLE: bool = false

Whether null is a value of the type: an absent Option. A field edit setting any other type to null is refused.

const SCALAR: bool = false

Whether store writes one scalar, with nothing inside it that a concurrent writer could add to. A record made just now leaves out such a field holding its missing value: an absent key reads as it. An object (text, a map, a list) is always made with its record, so two writers fill the same one.

fn nested_collections(&self) -> Vec<ItemCollection>

The item collections inside this value, when it is an item of a collection itself (a slide’s elements); #[derive(Model)] lists a record’s, the default has none.

fn read_whole(&mut self, doc: &AutoCommit) -> Result<(), ModelError>

Read everything this value holds, for a field marked #[model(whole)]: a value read lazily (rich text reads its paragraphs as views ask for them) reads all of it, so every reader of the record — a verb, search, read_content — sees all of it. The default has nothing more to read.

fn label(&self) -> Option<String>

What names this value for people (#[model(label)]): history, search, agents and item resources use it.

impl<T> PartialEq for Collection<T>

where T: PartialEq,

fn eq(&self, other: &Collection<T>) -> bool

Equal items in equal order; where each item’s order key came from is bookkeeping, not content. An item two clones still share is the same value and is not compared field by field.

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> PublishedItems for Collection<T>

where T: Model,

const ITEM_TABLE: &'static ModelTable = T::TABLE