Struct Transaction

pub struct Transaction<'a> { /* private fields */ }

A transaction on a document. Transactions group operations into a single change so that no other operations can happen in-between.

Created from Automerge::transaction().

Drop

This transaction should be manually committed or rolled back. If not done manually then it will be rolled back when it is dropped. This is to prevent the document being in an unsafe intermediate state. This is consistent with ? error handling.

Implementations

impl<'a> Transaction<'a>

pub fn hash_for_opid(&self, opid: &ExId) -> Option<ChangeHash>

Get the hash of the change that contains the given opid.

Returns none if the opid:

• is the root object id
• does not exist in this document
• is for an operation in this transaction

impl<'a> Transaction<'a>

pub fn get_heads(&self) -> Vec<ChangeHash>

Get the heads of the document before this transaction was started.

pub fn commit(self) -> (Option<ChangeHash>, PatchLog)

Commit the operations performed in this transaction, returning the hashes corresponding to the new heads.

pub fn commit_with( self, options: CommitOptions, ) -> (Option<ChangeHash>, PatchLog)

Commit the operations in this transaction with some options.

let mut doc = Automerge::new();
let mut tx = doc.transaction();
tx.put_object(ROOT, "todos", ObjType::List).unwrap();
let now = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap().as_secs() as
i64;
tx.commit_with(CommitOptions::default().with_message("Create todos list").with_time(now));

pub fn rollback(self) -> usize

Undo the operations added in this transaction, returning the number of cancelled operations.

Trait Implementations

impl<'a> Debug for Transaction<'a>

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

Formats the value using the given formatter.

impl<'a> Drop for Transaction<'a>

fn drop(&mut self)

If a transaction is not commited or rolled back manually then it can leave the document in an intermediate state. This defaults to rolling back the transaction to be compatible with ? error returning before reaching a call to Self::commit().

impl<'a> ReadDoc for Transaction<'a>

fn keys<O: AsRef<ExId>>(&self, obj: O) -> Keys<'_>

Get the keys of the object obj.

fn keys_at<O: AsRef<ExId>>(&self, obj: O, heads: &[ChangeHash]) -> Keys<'_>

Get the keys of the object obj as at heads

fn map_range<'b, O: AsRef<ExId>, R: RangeBounds<String> + 'b>( &'b self, obj: O, range: R, ) -> MapRange<'b, R>

Iterate over the keys and values of the map obj in the given range.

fn map_range_at<'b, O: AsRef<ExId>, R: RangeBounds<String> + 'b>( &'b self, obj: O, range: R, heads: &[ChangeHash], ) -> MapRange<'b, R>

Iterate over the keys and values of the map obj in the given range as at heads

fn list_range<O: AsRef<ExId>, R: RangeBounds<usize>>( &self, obj: O, range: R, ) -> ListRange<'_, R>

Iterate over the indexes and values of the list or text obj in the given range.

fn list_range_at<O: AsRef<ExId>, R: RangeBounds<usize>>( &self, obj: O, range: R, heads: &[ChangeHash], ) -> ListRange<'_, R>

Iterate over the indexes and values of the list or text obj in the given range as at heads

fn values<O: AsRef<ExId>>(&self, obj: O) -> Values<'_>

Iterate over the values in a map, list, or text object

fn values_at<O: AsRef<ExId>>(&self, obj: O, heads: &[ChangeHash]) -> Values<'_>

Iterate over the values in a map, list, or text object as at heads

fn length<O: AsRef<ExId>>(&self, obj: O) -> usize

Get the length of the given object.

fn length_at<O: AsRef<ExId>>(&self, obj: O, heads: &[ChangeHash]) -> usize

Get the length of the given object as at heads

fn object_type<O: AsRef<ExId>>(&self, obj: O) -> Result<ObjType, AutomergeError>

Get the type of this object, if it is an object.

fn text<O: AsRef<ExId>>(&self, obj: O) -> Result<String, AutomergeError>

Get the string represented by the given text object.

fn text_at<O: AsRef<ExId>>( &self, obj: O, heads: &[ChangeHash], ) -> Result<String, AutomergeError>

Get the string represented by the given text object as at heads, see Self::text()

fn spans<O: AsRef<ExId>>(&self, obj: O) -> Result<Spans<'_>, AutomergeError>

Return the sequence of text and block markers in the text object obj

fn spans_at<O: AsRef<ExId>>( &self, obj: O, heads: &[ChangeHash], ) -> Result<Spans<'_>, AutomergeError>

Return the sequence of text and block markers in the text object obj as at heads

fn get_cursor<O: AsRef<ExId>, I: Into<CursorPosition>>( &self, obj: O, position: I, at: Option<&[ChangeHash]>, ) -> Result<Cursor, AutomergeError>

Obtain the stable address (Cursor) for a usize position in a Sequence (either ObjType::List or ObjType::Text).

fn get_cursor_moving<O: AsRef<ExId>, I: Into<CursorPosition>>( &self, obj: O, position: I, at: Option<&[ChangeHash]>, move_cursor: MoveCursor, ) -> Result<Cursor, AutomergeError>

Obtain the stable address (Cursor) for a usize position in a Sequence (either ObjType::List or ObjType::Text).

fn get_cursor_position<O: AsRef<ExId>>( &self, obj: O, address: &Cursor, at: Option<&[ChangeHash]>, ) -> Result<usize, AutomergeError>

Translate Cursor in a Sequence into an absolute position of type usize.

fn marks<O: AsRef<ExId>>(&self, obj: O) -> Result<Vec<Mark<'_>>, AutomergeError>

Get all marks on a current sequence

fn marks_at<O: AsRef<ExId>>( &self, obj: O, heads: &[ChangeHash], ) -> Result<Vec<Mark<'_>>, AutomergeError>

Get all marks on a sequence at a given heads

fn hydrate<O: AsRef<ExId>>( &self, obj: O, heads: Option<&[ChangeHash]>, ) -> Result<Value, AutomergeError>

fn get_marks<O: AsRef<ExId>>( &self, obj: O, index: usize, heads: Option<&[ChangeHash]>, ) -> Result<MarkSet, AutomergeError>

fn get<O: AsRef<ExId>, P: Into<Prop>>( &self, obj: O, prop: P, ) -> Result<Option<(Value<'_>, ExId)>, AutomergeError>

Get a value out of the document.

fn get_at<O: AsRef<ExId>, P: Into<Prop>>( &self, obj: O, prop: P, heads: &[ChangeHash], ) -> Result<Option<(Value<'_>, ExId)>, AutomergeError>

Get the value of the given key as at heads, see Self::get()

fn get_all<O: AsRef<ExId>, P: Into<Prop>>( &self, obj: O, prop: P, ) -> Result<Vec<(Value<'_>, ExId)>, AutomergeError>

Get all conflicting values out of the document at this prop that conflict.

fn get_all_at<O: AsRef<ExId>, P: Into<Prop>>( &self, obj: O, prop: P, heads: &[ChangeHash], ) -> Result<Vec<(Value<'_>, ExId)>, AutomergeError>

Get all possibly conflicting values for a key as at heads

fn parents<O: AsRef<ExId>>(&self, obj: O) -> Result<Parents<'_>, AutomergeError>

Get the parents of an object in the document tree.

fn parents_at<O: AsRef<ExId>>( &self, obj: O, heads: &[ChangeHash], ) -> Result<Parents<'_>, AutomergeError>

Get the parents of the object obj as at heads

fn get_missing_deps(&self, heads: &[ChangeHash]) -> Vec<ChangeHash>

Get the hashes of the changes in this document that aren’t transitive dependencies of the given heads.

fn get_change_by_hash(&self, hash: &ChangeHash) -> Option<&Change>

Get a change by its hash.

fn stats(&self) -> Stats

Return some statistics about the document

fn text_encoding(&self) -> TextEncoding

impl<'a> Transactable for Transaction<'a>

fn pending_ops(&self) -> usize

Get the number of pending operations in this transaction.

fn put<O: AsRef<ExId>, P: Into<Prop>, V: Into<ScalarValue>>( &mut self, obj: O, prop: P, value: V, ) -> Result<(), AutomergeError>

Set the value of property P to value V in object obj.

Errors

This will return an error if

• The object does not exist
• The key is the wrong type for the object
• The key does not exist in the object

fn splice<O: AsRef<ExId>, V: IntoIterator<Item = ScalarValue>>( &mut self, obj: O, pos: usize, del: isize, vals: V, ) -> Result<(), AutomergeError>

Splice new elements into the given sequence. Returns a vector of the OpIds used to insert the new elements

fn put_object<O: AsRef<ExId>, P: Into<Prop>>( &mut self, obj: O, prop: P, value: ObjType, ) -> Result<ExId, AutomergeError>

Set the value of property P to the new object V in object obj.

fn insert<O: AsRef<ExId>, V: Into<ScalarValue>>( &mut self, obj: O, index: usize, value: V, ) -> Result<(), AutomergeError>

Insert a value into a list at the given index.

fn insert_object<O: AsRef<ExId>>( &mut self, obj: O, index: usize, value: ObjType, ) -> Result<ExId, AutomergeError>

Insert an object into a list at the given index.

fn increment<O: AsRef<ExId>, P: Into<Prop>>( &mut self, obj: O, prop: P, value: i64, ) -> Result<(), AutomergeError>

Increment the counter at the prop in the object by value.

fn delete<O: AsRef<ExId>, P: Into<Prop>>( &mut self, obj: O, prop: P, ) -> Result<(), AutomergeError>

Delete the value at prop in the object.

fn splice_text<O: AsRef<ExId>>( &mut self, obj: O, pos: usize, del: isize, text: &str, ) -> Result<(), AutomergeError>

Like Self::splice but for text.

fn mark<O: AsRef<ExId>>( &mut self, obj: O, mark: Mark<'_>, expand: ExpandMark, ) -> Result<(), AutomergeError>

Mark a sequence

fn unmark<O: AsRef<ExId>>( &mut self, obj: O, name: &str, start: usize, end: usize, expand: ExpandMark, ) -> Result<(), AutomergeError>

Remove a Mark from a sequence

fn split_block<'p, O>( &mut self, obj: O, index: usize, ) -> Result<ExId, AutomergeError>

where O: AsRef<ExId>,

Insert a block marker into the text object obj at the given index.

fn join_block<O>(&mut self, text: O, index: usize) -> Result<(), AutomergeError>

where O: AsRef<ExId>,

Delete a block marker at index from the text object obj.

fn replace_block<'p, O>( &mut self, text: O, index: usize, ) -> Result<ExId, AutomergeError>

where O: AsRef<ExId>,

Replace a block marker at index in obj with a new marker and return the ID of the new marker

fn base_heads(&self) -> Vec<ChangeHash>

The heads this transaction will be based on

fn update_text<S: AsRef<str>>( &mut self, obj: &ExId, new_text: S, ) -> Result<(), AutomergeError>

Update the value of a string

fn update_spans<'b, O: AsRef<ExId>, I: IntoIterator<Item = BlockOrText<'b>>>( &mut self, text: O, new_text: I, ) -> Result<(), AutomergeError>

Update the blocks and text in a text object

fn update_object<O: AsRef<ExId>>( &mut self, obj: O, new_value: &Value, ) -> Result<(), UpdateObjectError>