Struct DataDoc 

pub struct DataDoc { /* private fields */ }

A replicated document.

Holds named collections (map, list, text, counter). Concurrent edits from any replica merge deterministically, and applying the same change twice is a no-op, which is what lets this layer ride a transport ladder that only promises at-least-once, unordered delivery.

Implementations

impl DataDoc

pub fn new() -> Self

Create an empty document.

Examples found in repository

examples/offline_merge.rs (line 31)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One shared starting point: Ada writes, and Bo receives that change.
    let mut ada = DataDoc::new();
    ada.map_set("meta", "title", text("Coast road"))?;
    ada.list_push("packing", text("water"))?;
    let shared = ada.commit()?.expect("a change to share");

    let mut bo = DataDoc::new();
    bo.import(&shared.bytes)?;

    println!("both start at: {}", bo.export_json()?);

    // The link goes away here. Neither side can see the other's edits, and
    // neither side blocks on that.
    ada.map_set("meta", "title", text("Coast road, Friday"))?;
    ada.list_push("packing", text("map"))?;
    ada.text_insert("notes", 0, "leave at six")?;
    ada.counter_increment("edits", 1.0)?;
    let from_ada = ada.commit()?.expect("Ada's offline work");

    bo.map_set("meta", "title", text("Coast road, Saturday"))?;
    bo.list_push("packing", text("torch"))?;
    bo.text_insert("notes", 0, "bring the tent, ")?;
    bo.counter_increment("edits", 1.0)?;
    let from_bo = bo.commit()?.expect("Bo's offline work");

    println!("apart, Ada has: {}", ada.export_json()?);
    println!("apart, Bo has:  {}", bo.export_json()?);

    // The link comes back. Each side imports what the other committed. Order
    // does not matter and neither does arriving twice: importing the same
    // bytes again is a no-op, which is why at-least-once delivery is enough.
    ada.import(&from_bo.bytes)?;
    bo.import(&from_ada.bytes)?;
    bo.import(&from_ada.bytes)?;

    let ada_state = ada.export_json()?;
    let bo_state = bo.export_json()?;

    println!("together, Ada: {ada_state}");
    println!("together, Bo:  {bo_state}");
    println!("identical:     {}", ada_state == bo_state);

    // Read that state against the four collection types:
    //
    // - `meta.title` is a map key two people wrote. One value wins, both
    //   replicas pick the same one, and neither ends up holding half of each.
    //   That is the reason to put independently editable fields in separate
    //   keys rather than in one JSON blob.
    // - `packing` kept every insertion. A list loses nothing to a concurrent
    //   push.
    // - `notes` merged at character level, so both sentences survive.
    // - `edits` is 2. Two offline increments of 1 add up rather than
    //   overwriting each other, which is what makes a counter a counter and
    //   not an integer in a map.
    println!("packing:       {} entries", ada.list_len("packing")?);
    println!("notes:         {:?}", ada.text_value("notes")?);
    println!("edits:         {}", ada.counter_value("edits")?);

    Ok(())
}

pub fn is_poisoned(&self) -> bool

Whether this handle has been poisoned by a decode failure.

A poisoned handle never recovers. The owner drops it and re-opens the document from storage, which is a decision only the owner can make.

pub fn import(&mut self, bytes: &[u8]) -> DataResult<ImportOutcome>

Apply an encoded snapshot or delta.

Every blob reaching this method comes back out of a sealed protocol-state record, so an AEAD tag has already established that these are bytes this SDK wrote and nobody altered. That is the real containment for the engine’s known import-panic classes, and the reason no code path may ever feed unverified bytes here: the catch_unwind below is a second line, which poisons this handle when it catches, and under panic = "abort" it does not exist at all. It wraps the engine’s apply step only. The header decode just above it, like DataDoc::inspect, runs outside it, so a panic there unwinds to the caller and leaves this handle live.

Returns whether the blob applied or is parked behind a missing predecessor. Callers that can destroy history (compaction, log truncation) must branch on it: see ImportOutcome.

Examples found in repository

examples/offline_merge.rs (line 37)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One shared starting point: Ada writes, and Bo receives that change.
    let mut ada = DataDoc::new();
    ada.map_set("meta", "title", text("Coast road"))?;
    ada.list_push("packing", text("water"))?;
    let shared = ada.commit()?.expect("a change to share");

    let mut bo = DataDoc::new();
    bo.import(&shared.bytes)?;

    println!("both start at: {}", bo.export_json()?);

    // The link goes away here. Neither side can see the other's edits, and
    // neither side blocks on that.
    ada.map_set("meta", "title", text("Coast road, Friday"))?;
    ada.list_push("packing", text("map"))?;
    ada.text_insert("notes", 0, "leave at six")?;
    ada.counter_increment("edits", 1.0)?;
    let from_ada = ada.commit()?.expect("Ada's offline work");

    bo.map_set("meta", "title", text("Coast road, Saturday"))?;
    bo.list_push("packing", text("torch"))?;
    bo.text_insert("notes", 0, "bring the tent, ")?;
    bo.counter_increment("edits", 1.0)?;
    let from_bo = bo.commit()?.expect("Bo's offline work");

    println!("apart, Ada has: {}", ada.export_json()?);
    println!("apart, Bo has:  {}", bo.export_json()?);

    // The link comes back. Each side imports what the other committed. Order
    // does not matter and neither does arriving twice: importing the same
    // bytes again is a no-op, which is why at-least-once delivery is enough.
    ada.import(&from_bo.bytes)?;
    bo.import(&from_ada.bytes)?;
    bo.import(&from_ada.bytes)?;

    let ada_state = ada.export_json()?;
    let bo_state = bo.export_json()?;

    println!("together, Ada: {ada_state}");
    println!("together, Bo:  {bo_state}");
    println!("identical:     {}", ada_state == bo_state);

    // Read that state against the four collection types:
    //
    // - `meta.title` is a map key two people wrote. One value wins, both
    //   replicas pick the same one, and neither ends up holding half of each.
    //   That is the reason to put independently editable fields in separate
    //   keys rather than in one JSON blob.
    // - `packing` kept every insertion. A list loses nothing to a concurrent
    //   push.
    // - `notes` merged at character level, so both sentences survive.
    // - `edits` is 2. Two offline increments of 1 add up rather than
    //   overwriting each other, which is what makes a counter a counter and
    //   not an integer in a map.
    println!("packing:       {} entries", ada.list_len("packing")?);
    println!("notes:         {:?}", ada.text_value("notes")?);
    println!("edits:         {}", ada.counter_value("edits")?);

    Ok(())
}

pub fn inspect(&self, bytes: &[u8]) -> DataResult<BlobMeta>

Judge a blob against this document without letting the engine touch it.

The whole point is that this runs first. Header decoding with the checksum on is the cheap part; the verdicts it produces are what let a caller refuse the two blob shapes that are known to end a process rather than return an error.

pub fn import_remote(&mut self, bytes: &[u8]) -> DataResult<RemoteImport>

Apply a blob that arrived from a peer.

DataDoc::import exists for bytes that came back out of a sealed record, where an AEAD tag has already established that this SDK wrote them. Nothing of the sort is true here: a peer is authenticated, which says who sent the bytes and nothing at all about their shape. So this path re-judges every blob with DataDoc::inspect and declines the two shapes the engine is known to panic on, rather than relying on the unwinding catch in DataDoc::import: it covers the apply step only, poisons this handle when it fires, and does not exist in a host built with panic = "abort".

Refusing is not a failure: a duplicate is the ladder keeping its at-least-once promise, and a trimmed-history gap in a run of changes is answered by asking for a snapshot. Both are recorded outcomes, not errors. The same refusal on a snapshot is the exception: it means the replicas have diverged past anything a frame can carry, and the caller has nothing left to ask for.

pub fn export_since(&self, from: &VersionToken) -> DataResult<CatchUp>

Encode what a replica at from is missing.

from is a token that replica produced with DataDoc::version. A token this document cannot decode is treated as corrupt rather than as “send everything”: on the sync path the token is remote input, and answering a malformed one with the whole document would make a garbled byte an amplification lever.

pub fn mark_persisted(&mut self)

Declare everything currently in the document as already persisted.

Called after loading a snapshot and its delta log, so the next commit exports only genuinely new changes instead of re-emitting the history that was just read off disk.

pub fn commit(&mut self) -> DataResult<Option<Delta>>

Commit pending edits and return the change they produced.

Ok(None) means nothing had changed. The returned delta is exactly the bytes needed to bring a replica at the previous version up to the current one, which is what the delta log stores and what F3 will send.

Examples found in repository

examples/offline_merge.rs (line 34)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One shared starting point: Ada writes, and Bo receives that change.
    let mut ada = DataDoc::new();
    ada.map_set("meta", "title", text("Coast road"))?;
    ada.list_push("packing", text("water"))?;
    let shared = ada.commit()?.expect("a change to share");

    let mut bo = DataDoc::new();
    bo.import(&shared.bytes)?;

    println!("both start at: {}", bo.export_json()?);

    // The link goes away here. Neither side can see the other's edits, and
    // neither side blocks on that.
    ada.map_set("meta", "title", text("Coast road, Friday"))?;
    ada.list_push("packing", text("map"))?;
    ada.text_insert("notes", 0, "leave at six")?;
    ada.counter_increment("edits", 1.0)?;
    let from_ada = ada.commit()?.expect("Ada's offline work");

    bo.map_set("meta", "title", text("Coast road, Saturday"))?;
    bo.list_push("packing", text("torch"))?;
    bo.text_insert("notes", 0, "bring the tent, ")?;
    bo.counter_increment("edits", 1.0)?;
    let from_bo = bo.commit()?.expect("Bo's offline work");

    println!("apart, Ada has: {}", ada.export_json()?);
    println!("apart, Bo has:  {}", bo.export_json()?);

    // The link comes back. Each side imports what the other committed. Order
    // does not matter and neither does arriving twice: importing the same
    // bytes again is a no-op, which is why at-least-once delivery is enough.
    ada.import(&from_bo.bytes)?;
    bo.import(&from_ada.bytes)?;
    bo.import(&from_ada.bytes)?;

    let ada_state = ada.export_json()?;
    let bo_state = bo.export_json()?;

    println!("together, Ada: {ada_state}");
    println!("together, Bo:  {bo_state}");
    println!("identical:     {}", ada_state == bo_state);

    // Read that state against the four collection types:
    //
    // - `meta.title` is a map key two people wrote. One value wins, both
    //   replicas pick the same one, and neither ends up holding half of each.
    //   That is the reason to put independently editable fields in separate
    //   keys rather than in one JSON blob.
    // - `packing` kept every insertion. A list loses nothing to a concurrent
    //   push.
    // - `notes` merged at character level, so both sentences survive.
    // - `edits` is 2. Two offline increments of 1 add up rather than
    //   overwriting each other, which is what makes a counter a counter and
    //   not an integer in a map.
    println!("packing:       {} entries", ada.list_len("packing")?);
    println!("notes:         {:?}", ada.text_value("notes")?);
    println!("edits:         {}", ada.counter_value("edits")?);

    Ok(())
}

pub fn rewind_last_commit(&mut self)

Undo the bookkeeping of the last commit, so its change is handed out again by the next one.

For the caller whose write failed. The document keeps the edits (they happened, and the application is looking at them); what is undone is only the claim that someone has taken responsibility for persisting them. Without this a failed write loses the change at the next restart, silently, which is the worst shape a storage error can take.

Safe to call spuriously: re-exporting a delta that did reach storage costs one duplicate record, and duplicates are free by construction.

pub fn version(&self) -> VersionToken

The current version of the document.

pub fn export_compacted(&self) -> DataResult<Vec<u8>>

Encode the document compactly, discarding history.

This is what a document record stores: a 10,000 operation document compacts to under a kilobyte here, against tens of kilobytes of full history, which is what keeps a document inside one sealed record and a catch-up inside one message.

pub fn export_raw(&self) -> DataResult<Vec<u8>>

Encode the document with its full history.

Part of the escape hatch: an application can always take this and leave. Prefer DataDoc::export_compacted for storage and transfer.

pub fn export_json(&self) -> DataResult<String>

The document’s current state as plain JSON.

The second half of the escape hatch, and the one that does not require the reader to know anything about this SDK at all.

Examples found in repository

examples/offline_merge.rs (line 39)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One shared starting point: Ada writes, and Bo receives that change.
    let mut ada = DataDoc::new();
    ada.map_set("meta", "title", text("Coast road"))?;
    ada.list_push("packing", text("water"))?;
    let shared = ada.commit()?.expect("a change to share");

    let mut bo = DataDoc::new();
    bo.import(&shared.bytes)?;

    println!("both start at: {}", bo.export_json()?);

    // The link goes away here. Neither side can see the other's edits, and
    // neither side blocks on that.
    ada.map_set("meta", "title", text("Coast road, Friday"))?;
    ada.list_push("packing", text("map"))?;
    ada.text_insert("notes", 0, "leave at six")?;
    ada.counter_increment("edits", 1.0)?;
    let from_ada = ada.commit()?.expect("Ada's offline work");

    bo.map_set("meta", "title", text("Coast road, Saturday"))?;
    bo.list_push("packing", text("torch"))?;
    bo.text_insert("notes", 0, "bring the tent, ")?;
    bo.counter_increment("edits", 1.0)?;
    let from_bo = bo.commit()?.expect("Bo's offline work");

    println!("apart, Ada has: {}", ada.export_json()?);
    println!("apart, Bo has:  {}", bo.export_json()?);

    // The link comes back. Each side imports what the other committed. Order
    // does not matter and neither does arriving twice: importing the same
    // bytes again is a no-op, which is why at-least-once delivery is enough.
    ada.import(&from_bo.bytes)?;
    bo.import(&from_ada.bytes)?;
    bo.import(&from_ada.bytes)?;

    let ada_state = ada.export_json()?;
    let bo_state = bo.export_json()?;

    println!("together, Ada: {ada_state}");
    println!("together, Bo:  {bo_state}");
    println!("identical:     {}", ada_state == bo_state);

    // Read that state against the four collection types:
    //
    // - `meta.title` is a map key two people wrote. One value wins, both
    //   replicas pick the same one, and neither ends up holding half of each.
    //   That is the reason to put independently editable fields in separate
    //   keys rather than in one JSON blob.
    // - `packing` kept every insertion. A list loses nothing to a concurrent
    //   push.
    // - `notes` merged at character level, so both sentences survive.
    // - `edits` is 2. Two offline increments of 1 add up rather than
    //   overwriting each other, which is what makes a counter a counter and
    //   not an integer in a map.
    println!("packing:       {} entries", ada.list_len("packing")?);
    println!("notes:         {:?}", ada.text_value("notes")?);
    println!("edits:         {}", ada.counter_value("edits")?);

    Ok(())
}

pub fn measure(&mut self) -> DataResult<usize>

Measure the compacted encoding and refresh the size bookkeeping.

pub fn check_size(&mut self) -> DataResult<(SizeVerdict, Option<usize>)>

Check the document against the size cap, measuring only when the running estimate says a breach is possible.

Returns the verdict and, when a measurement happened, the true size.

pub fn stats(&mut self) -> DataResult<DocStats>

Statistics for compaction and cap decisions.

pub fn commits_since_compaction(&self) -> u32

Commits recorded since the last compaction.

pub fn mark_compacted(&mut self, compacted_bytes: usize)

Reset the compaction counter, after the owner has written a fresh compacted record and dropped the folded delta records.

pub fn restore_bookkeeping( &mut self, compacted_bytes: usize, log_bytes: usize, commits: u32, )

Adopt the bookkeeping of a document just loaded from storage.

Without this a reopened document starts as though it were empty, and the cheap size estimate then under-reports by the entire size of what was loaded: a document already near the cap would look far from it and sail past without ever triggering a real measurement. Passing the record sizes in keeps the estimate an over-estimate, which is the property the whole check depends on.

compacted_bytes is the size of the stored snapshot and log_bytes the total size of the delta records replayed on top of it.

pub fn map_set( &mut self, collection: &str, key: &str, value: DataValue, ) -> DataResult<()>

Set a key in a map collection.

Examples found in repository

examples/offline_merge.rs (line 32)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One shared starting point: Ada writes, and Bo receives that change.
    let mut ada = DataDoc::new();
    ada.map_set("meta", "title", text("Coast road"))?;
    ada.list_push("packing", text("water"))?;
    let shared = ada.commit()?.expect("a change to share");

    let mut bo = DataDoc::new();
    bo.import(&shared.bytes)?;

    println!("both start at: {}", bo.export_json()?);

    // The link goes away here. Neither side can see the other's edits, and
    // neither side blocks on that.
    ada.map_set("meta", "title", text("Coast road, Friday"))?;
    ada.list_push("packing", text("map"))?;
    ada.text_insert("notes", 0, "leave at six")?;
    ada.counter_increment("edits", 1.0)?;
    let from_ada = ada.commit()?.expect("Ada's offline work");

    bo.map_set("meta", "title", text("Coast road, Saturday"))?;
    bo.list_push("packing", text("torch"))?;
    bo.text_insert("notes", 0, "bring the tent, ")?;
    bo.counter_increment("edits", 1.0)?;
    let from_bo = bo.commit()?.expect("Bo's offline work");

    println!("apart, Ada has: {}", ada.export_json()?);
    println!("apart, Bo has:  {}", bo.export_json()?);

    // The link comes back. Each side imports what the other committed. Order
    // does not matter and neither does arriving twice: importing the same
    // bytes again is a no-op, which is why at-least-once delivery is enough.
    ada.import(&from_bo.bytes)?;
    bo.import(&from_ada.bytes)?;
    bo.import(&from_ada.bytes)?;

    let ada_state = ada.export_json()?;
    let bo_state = bo.export_json()?;

    println!("together, Ada: {ada_state}");
    println!("together, Bo:  {bo_state}");
    println!("identical:     {}", ada_state == bo_state);

    // Read that state against the four collection types:
    //
    // - `meta.title` is a map key two people wrote. One value wins, both
    //   replicas pick the same one, and neither ends up holding half of each.
    //   That is the reason to put independently editable fields in separate
    //   keys rather than in one JSON blob.
    // - `packing` kept every insertion. A list loses nothing to a concurrent
    //   push.
    // - `notes` merged at character level, so both sentences survive.
    // - `edits` is 2. Two offline increments of 1 add up rather than
    //   overwriting each other, which is what makes a counter a counter and
    //   not an integer in a map.
    println!("packing:       {} entries", ada.list_len("packing")?);
    println!("notes:         {:?}", ada.text_value("notes")?);
    println!("edits:         {}", ada.counter_value("edits")?);

    Ok(())
}

pub fn map_delete(&mut self, collection: &str, key: &str) -> DataResult<()>

Remove a key from a map collection.

pub fn map_get( &self, collection: &str, key: &str, ) -> DataResult<Option<DataValue>>

Read a key from a map collection.

pub fn list_push( &mut self, collection: &str, value: DataValue, ) -> DataResult<()>

Append to a list collection.

Examples found in repository

examples/offline_merge.rs (line 33)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One shared starting point: Ada writes, and Bo receives that change.
    let mut ada = DataDoc::new();
    ada.map_set("meta", "title", text("Coast road"))?;
    ada.list_push("packing", text("water"))?;
    let shared = ada.commit()?.expect("a change to share");

    let mut bo = DataDoc::new();
    bo.import(&shared.bytes)?;

    println!("both start at: {}", bo.export_json()?);

    // The link goes away here. Neither side can see the other's edits, and
    // neither side blocks on that.
    ada.map_set("meta", "title", text("Coast road, Friday"))?;
    ada.list_push("packing", text("map"))?;
    ada.text_insert("notes", 0, "leave at six")?;
    ada.counter_increment("edits", 1.0)?;
    let from_ada = ada.commit()?.expect("Ada's offline work");

    bo.map_set("meta", "title", text("Coast road, Saturday"))?;
    bo.list_push("packing", text("torch"))?;
    bo.text_insert("notes", 0, "bring the tent, ")?;
    bo.counter_increment("edits", 1.0)?;
    let from_bo = bo.commit()?.expect("Bo's offline work");

    println!("apart, Ada has: {}", ada.export_json()?);
    println!("apart, Bo has:  {}", bo.export_json()?);

    // The link comes back. Each side imports what the other committed. Order
    // does not matter and neither does arriving twice: importing the same
    // bytes again is a no-op, which is why at-least-once delivery is enough.
    ada.import(&from_bo.bytes)?;
    bo.import(&from_ada.bytes)?;
    bo.import(&from_ada.bytes)?;

    let ada_state = ada.export_json()?;
    let bo_state = bo.export_json()?;

    println!("together, Ada: {ada_state}");
    println!("together, Bo:  {bo_state}");
    println!("identical:     {}", ada_state == bo_state);

    // Read that state against the four collection types:
    //
    // - `meta.title` is a map key two people wrote. One value wins, both
    //   replicas pick the same one, and neither ends up holding half of each.
    //   That is the reason to put independently editable fields in separate
    //   keys rather than in one JSON blob.
    // - `packing` kept every insertion. A list loses nothing to a concurrent
    //   push.
    // - `notes` merged at character level, so both sentences survive.
    // - `edits` is 2. Two offline increments of 1 add up rather than
    //   overwriting each other, which is what makes a counter a counter and
    //   not an integer in a map.
    println!("packing:       {} entries", ada.list_len("packing")?);
    println!("notes:         {:?}", ada.text_value("notes")?);
    println!("edits:         {}", ada.counter_value("edits")?);

    Ok(())
}

pub fn list_insert( &mut self, collection: &str, index: usize, value: DataValue, ) -> DataResult<()>

Insert into a list collection at index.

pub fn list_delete( &mut self, collection: &str, index: usize, count: usize, ) -> DataResult<()>

Delete count entries from a list collection at index.

pub fn list_len(&self, collection: &str) -> DataResult<usize>

Number of entries in a list collection.

Examples found in repository

examples/offline_merge.rs (line 84)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One shared starting point: Ada writes, and Bo receives that change.
    let mut ada = DataDoc::new();
    ada.map_set("meta", "title", text("Coast road"))?;
    ada.list_push("packing", text("water"))?;
    let shared = ada.commit()?.expect("a change to share");

    let mut bo = DataDoc::new();
    bo.import(&shared.bytes)?;

    println!("both start at: {}", bo.export_json()?);

    // The link goes away here. Neither side can see the other's edits, and
    // neither side blocks on that.
    ada.map_set("meta", "title", text("Coast road, Friday"))?;
    ada.list_push("packing", text("map"))?;
    ada.text_insert("notes", 0, "leave at six")?;
    ada.counter_increment("edits", 1.0)?;
    let from_ada = ada.commit()?.expect("Ada's offline work");

    bo.map_set("meta", "title", text("Coast road, Saturday"))?;
    bo.list_push("packing", text("torch"))?;
    bo.text_insert("notes", 0, "bring the tent, ")?;
    bo.counter_increment("edits", 1.0)?;
    let from_bo = bo.commit()?.expect("Bo's offline work");

    println!("apart, Ada has: {}", ada.export_json()?);
    println!("apart, Bo has:  {}", bo.export_json()?);

    // The link comes back. Each side imports what the other committed. Order
    // does not matter and neither does arriving twice: importing the same
    // bytes again is a no-op, which is why at-least-once delivery is enough.
    ada.import(&from_bo.bytes)?;
    bo.import(&from_ada.bytes)?;
    bo.import(&from_ada.bytes)?;

    let ada_state = ada.export_json()?;
    let bo_state = bo.export_json()?;

    println!("together, Ada: {ada_state}");
    println!("together, Bo:  {bo_state}");
    println!("identical:     {}", ada_state == bo_state);

    // Read that state against the four collection types:
    //
    // - `meta.title` is a map key two people wrote. One value wins, both
    //   replicas pick the same one, and neither ends up holding half of each.
    //   That is the reason to put independently editable fields in separate
    //   keys rather than in one JSON blob.
    // - `packing` kept every insertion. A list loses nothing to a concurrent
    //   push.
    // - `notes` merged at character level, so both sentences survive.
    // - `edits` is 2. Two offline increments of 1 add up rather than
    //   overwriting each other, which is what makes a counter a counter and
    //   not an integer in a map.
    println!("packing:       {} entries", ada.list_len("packing")?);
    println!("notes:         {:?}", ada.text_value("notes")?);
    println!("edits:         {}", ada.counter_value("edits")?);

    Ok(())
}

pub fn text_insert( &mut self, collection: &str, position: usize, text: &str, ) -> DataResult<()>

Insert text into a text collection at a character position.

Examples found in repository

examples/offline_merge.rs (line 45)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One shared starting point: Ada writes, and Bo receives that change.
    let mut ada = DataDoc::new();
    ada.map_set("meta", "title", text("Coast road"))?;
    ada.list_push("packing", text("water"))?;
    let shared = ada.commit()?.expect("a change to share");

    let mut bo = DataDoc::new();
    bo.import(&shared.bytes)?;

    println!("both start at: {}", bo.export_json()?);

    // The link goes away here. Neither side can see the other's edits, and
    // neither side blocks on that.
    ada.map_set("meta", "title", text("Coast road, Friday"))?;
    ada.list_push("packing", text("map"))?;
    ada.text_insert("notes", 0, "leave at six")?;
    ada.counter_increment("edits", 1.0)?;
    let from_ada = ada.commit()?.expect("Ada's offline work");

    bo.map_set("meta", "title", text("Coast road, Saturday"))?;
    bo.list_push("packing", text("torch"))?;
    bo.text_insert("notes", 0, "bring the tent, ")?;
    bo.counter_increment("edits", 1.0)?;
    let from_bo = bo.commit()?.expect("Bo's offline work");

    println!("apart, Ada has: {}", ada.export_json()?);
    println!("apart, Bo has:  {}", bo.export_json()?);

    // The link comes back. Each side imports what the other committed. Order
    // does not matter and neither does arriving twice: importing the same
    // bytes again is a no-op, which is why at-least-once delivery is enough.
    ada.import(&from_bo.bytes)?;
    bo.import(&from_ada.bytes)?;
    bo.import(&from_ada.bytes)?;

    let ada_state = ada.export_json()?;
    let bo_state = bo.export_json()?;

    println!("together, Ada: {ada_state}");
    println!("together, Bo:  {bo_state}");
    println!("identical:     {}", ada_state == bo_state);

    // Read that state against the four collection types:
    //
    // - `meta.title` is a map key two people wrote. One value wins, both
    //   replicas pick the same one, and neither ends up holding half of each.
    //   That is the reason to put independently editable fields in separate
    //   keys rather than in one JSON blob.
    // - `packing` kept every insertion. A list loses nothing to a concurrent
    //   push.
    // - `notes` merged at character level, so both sentences survive.
    // - `edits` is 2. Two offline increments of 1 add up rather than
    //   overwriting each other, which is what makes a counter a counter and
    //   not an integer in a map.
    println!("packing:       {} entries", ada.list_len("packing")?);
    println!("notes:         {:?}", ada.text_value("notes")?);
    println!("edits:         {}", ada.counter_value("edits")?);

    Ok(())
}

pub fn text_delete( &mut self, collection: &str, position: usize, count: usize, ) -> DataResult<()>

Delete count characters from a text collection at position.

pub fn text_value(&self, collection: &str) -> DataResult<String>

The current contents of a text collection.

Examples found in repository

examples/offline_merge.rs (line 85)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One shared starting point: Ada writes, and Bo receives that change.
    let mut ada = DataDoc::new();
    ada.map_set("meta", "title", text("Coast road"))?;
    ada.list_push("packing", text("water"))?;
    let shared = ada.commit()?.expect("a change to share");

    let mut bo = DataDoc::new();
    bo.import(&shared.bytes)?;

    println!("both start at: {}", bo.export_json()?);

    // The link goes away here. Neither side can see the other's edits, and
    // neither side blocks on that.
    ada.map_set("meta", "title", text("Coast road, Friday"))?;
    ada.list_push("packing", text("map"))?;
    ada.text_insert("notes", 0, "leave at six")?;
    ada.counter_increment("edits", 1.0)?;
    let from_ada = ada.commit()?.expect("Ada's offline work");

    bo.map_set("meta", "title", text("Coast road, Saturday"))?;
    bo.list_push("packing", text("torch"))?;
    bo.text_insert("notes", 0, "bring the tent, ")?;
    bo.counter_increment("edits", 1.0)?;
    let from_bo = bo.commit()?.expect("Bo's offline work");

    println!("apart, Ada has: {}", ada.export_json()?);
    println!("apart, Bo has:  {}", bo.export_json()?);

    // The link comes back. Each side imports what the other committed. Order
    // does not matter and neither does arriving twice: importing the same
    // bytes again is a no-op, which is why at-least-once delivery is enough.
    ada.import(&from_bo.bytes)?;
    bo.import(&from_ada.bytes)?;
    bo.import(&from_ada.bytes)?;

    let ada_state = ada.export_json()?;
    let bo_state = bo.export_json()?;

    println!("together, Ada: {ada_state}");
    println!("together, Bo:  {bo_state}");
    println!("identical:     {}", ada_state == bo_state);

    // Read that state against the four collection types:
    //
    // - `meta.title` is a map key two people wrote. One value wins, both
    //   replicas pick the same one, and neither ends up holding half of each.
    //   That is the reason to put independently editable fields in separate
    //   keys rather than in one JSON blob.
    // - `packing` kept every insertion. A list loses nothing to a concurrent
    //   push.
    // - `notes` merged at character level, so both sentences survive.
    // - `edits` is 2. Two offline increments of 1 add up rather than
    //   overwriting each other, which is what makes a counter a counter and
    //   not an integer in a map.
    println!("packing:       {} entries", ada.list_len("packing")?);
    println!("notes:         {:?}", ada.text_value("notes")?);
    println!("edits:         {}", ada.counter_value("edits")?);

    Ok(())
}

pub fn counter_increment( &mut self, collection: &str, amount: f64, ) -> DataResult<()>

Add to a counter collection. Negative values subtract.

Examples found in repository

examples/offline_merge.rs (line 46)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One shared starting point: Ada writes, and Bo receives that change.
    let mut ada = DataDoc::new();
    ada.map_set("meta", "title", text("Coast road"))?;
    ada.list_push("packing", text("water"))?;
    let shared = ada.commit()?.expect("a change to share");

    let mut bo = DataDoc::new();
    bo.import(&shared.bytes)?;

    println!("both start at: {}", bo.export_json()?);

    // The link goes away here. Neither side can see the other's edits, and
    // neither side blocks on that.
    ada.map_set("meta", "title", text("Coast road, Friday"))?;
    ada.list_push("packing", text("map"))?;
    ada.text_insert("notes", 0, "leave at six")?;
    ada.counter_increment("edits", 1.0)?;
    let from_ada = ada.commit()?.expect("Ada's offline work");

    bo.map_set("meta", "title", text("Coast road, Saturday"))?;
    bo.list_push("packing", text("torch"))?;
    bo.text_insert("notes", 0, "bring the tent, ")?;
    bo.counter_increment("edits", 1.0)?;
    let from_bo = bo.commit()?.expect("Bo's offline work");

    println!("apart, Ada has: {}", ada.export_json()?);
    println!("apart, Bo has:  {}", bo.export_json()?);

    // The link comes back. Each side imports what the other committed. Order
    // does not matter and neither does arriving twice: importing the same
    // bytes again is a no-op, which is why at-least-once delivery is enough.
    ada.import(&from_bo.bytes)?;
    bo.import(&from_ada.bytes)?;
    bo.import(&from_ada.bytes)?;

    let ada_state = ada.export_json()?;
    let bo_state = bo.export_json()?;

    println!("together, Ada: {ada_state}");
    println!("together, Bo:  {bo_state}");
    println!("identical:     {}", ada_state == bo_state);

    // Read that state against the four collection types:
    //
    // - `meta.title` is a map key two people wrote. One value wins, both
    //   replicas pick the same one, and neither ends up holding half of each.
    //   That is the reason to put independently editable fields in separate
    //   keys rather than in one JSON blob.
    // - `packing` kept every insertion. A list loses nothing to a concurrent
    //   push.
    // - `notes` merged at character level, so both sentences survive.
    // - `edits` is 2. Two offline increments of 1 add up rather than
    //   overwriting each other, which is what makes a counter a counter and
    //   not an integer in a map.
    println!("packing:       {} entries", ada.list_len("packing")?);
    println!("notes:         {:?}", ada.text_value("notes")?);
    println!("edits:         {}", ada.counter_value("edits")?);

    Ok(())
}

pub fn counter_value(&self, collection: &str) -> DataResult<f64>

The current value of a counter collection.

Examples found in repository

examples/offline_merge.rs (line 86)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // One shared starting point: Ada writes, and Bo receives that change.
    let mut ada = DataDoc::new();
    ada.map_set("meta", "title", text("Coast road"))?;
    ada.list_push("packing", text("water"))?;
    let shared = ada.commit()?.expect("a change to share");

    let mut bo = DataDoc::new();
    bo.import(&shared.bytes)?;

    println!("both start at: {}", bo.export_json()?);

    // The link goes away here. Neither side can see the other's edits, and
    // neither side blocks on that.
    ada.map_set("meta", "title", text("Coast road, Friday"))?;
    ada.list_push("packing", text("map"))?;
    ada.text_insert("notes", 0, "leave at six")?;
    ada.counter_increment("edits", 1.0)?;
    let from_ada = ada.commit()?.expect("Ada's offline work");

    bo.map_set("meta", "title", text("Coast road, Saturday"))?;
    bo.list_push("packing", text("torch"))?;
    bo.text_insert("notes", 0, "bring the tent, ")?;
    bo.counter_increment("edits", 1.0)?;
    let from_bo = bo.commit()?.expect("Bo's offline work");

    println!("apart, Ada has: {}", ada.export_json()?);
    println!("apart, Bo has:  {}", bo.export_json()?);

    // The link comes back. Each side imports what the other committed. Order
    // does not matter and neither does arriving twice: importing the same
    // bytes again is a no-op, which is why at-least-once delivery is enough.
    ada.import(&from_bo.bytes)?;
    bo.import(&from_ada.bytes)?;
    bo.import(&from_ada.bytes)?;

    let ada_state = ada.export_json()?;
    let bo_state = bo.export_json()?;

    println!("together, Ada: {ada_state}");
    println!("together, Bo:  {bo_state}");
    println!("identical:     {}", ada_state == bo_state);

    // Read that state against the four collection types:
    //
    // - `meta.title` is a map key two people wrote. One value wins, both
    //   replicas pick the same one, and neither ends up holding half of each.
    //   That is the reason to put independently editable fields in separate
    //   keys rather than in one JSON blob.
    // - `packing` kept every insertion. A list loses nothing to a concurrent
    //   push.
    // - `notes` merged at character level, so both sentences survive.
    // - `edits` is 2. Two offline increments of 1 add up rather than
    //   overwriting each other, which is what makes a counter a counter and
    //   not an integer in a map.
    println!("packing:       {} entries", ada.list_len("packing")?);
    println!("notes:         {:?}", ada.text_value("notes")?);
    println!("edits:         {}", ada.counter_value("edits")?);

    Ok(())
}

Trait Implementations

impl Debug for DataDoc

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

Formats the value using the given formatter.

impl Default for DataDoc

fn default() -> Self

Returns the “default value” for a type.