Trait ReadDoc 

pub trait ReadDoc {
    // Required methods
    fn parents<O>(&self, obj: O) -> Result<Parents<'_>, AutomergeError>
       where O: AsRef<ExId>;
    fn parents_at<O>(
        &self,
        obj: O,
        heads: &[ChangeHash],
    ) -> Result<Parents<'_>, AutomergeError>
       where O: AsRef<ExId>;
    fn keys<O>(&self, obj: O) -> Keys<'_> 
       where O: AsRef<ExId>;
    fn keys_at<O>(&self, obj: O, heads: &[ChangeHash]) -> Keys<'_> 
       where O: AsRef<ExId>;
    fn iter_at<O>(&self, obj: O, heads: Option<&[ChangeHash]>) -> DocIter<'_> 
       where O: AsRef<ExId>;
    fn map_range<'a, O, R>(&'a self, obj: O, range: R) -> MapRange<'a> 
       where O: AsRef<ExId>,
             R: RangeBounds<String> + 'a;
    fn map_range_at<'a, O, R>(
        &'a self,
        obj: O,
        range: R,
        heads: &[ChangeHash],
    ) -> MapRange<'a> 
       where O: AsRef<ExId>,
             R: RangeBounds<String> + 'a;
    fn list_range<O, R>(&self, obj: O, range: R) -> ListRange<'_> 
       where O: AsRef<ExId>,
             R: RangeBounds<usize>;
    fn list_range_at<O, R>(
        &self,
        obj: O,
        range: R,
        heads: &[ChangeHash],
    ) -> ListRange<'_> 
       where O: AsRef<ExId>,
             R: RangeBounds<usize>;
    fn values<O>(&self, obj: O) -> Values<'_> 
       where O: AsRef<ExId>;
    fn values_at<O>(&self, obj: O, heads: &[ChangeHash]) -> Values<'_> 
       where O: AsRef<ExId>;
    fn length<O>(&self, obj: O) -> usize
       where O: AsRef<ExId>;
    fn length_at<O>(&self, obj: O, heads: &[ChangeHash]) -> usize
       where O: AsRef<ExId>;
    fn object_type<O>(&self, obj: O) -> Result<ObjType, AutomergeError>
       where O: AsRef<ExId>;
    fn marks<O>(&self, obj: O) -> Result<Vec<Mark>, AutomergeError>
       where O: AsRef<ExId>;
    fn marks_at<O>(
        &self,
        obj: O,
        heads: &[ChangeHash],
    ) -> Result<Vec<Mark>, AutomergeError>
       where O: AsRef<ExId>;
    fn get_marks<O>(
        &self,
        obj: O,
        index: usize,
        heads: Option<&[ChangeHash]>,
    ) -> Result<MarkSet, AutomergeError>
       where O: AsRef<ExId>;
    fn text<O>(&self, obj: O) -> Result<String, AutomergeError>
       where O: AsRef<ExId>;
    fn text_at<O>(
        &self,
        obj: O,
        heads: &[ChangeHash],
    ) -> Result<String, AutomergeError>
       where O: AsRef<ExId>;
    fn spans<O>(&self, obj: O) -> Result<Spans<'_>, AutomergeError>
       where O: AsRef<ExId>;
    fn spans_at<O>(
        &self,
        obj: O,
        heads: &[ChangeHash],
    ) -> Result<Spans<'_>, AutomergeError>
       where O: AsRef<ExId>;
    fn get_cursor<O, I>(
        &self,
        obj: O,
        position: I,
        at: Option<&[ChangeHash]>,
    ) -> Result<Cursor, AutomergeError>
       where O: AsRef<ExId>,
             I: Into<CursorPosition>;
    fn get_cursor_moving<O, I>(
        &self,
        obj: O,
        position: I,
        at: Option<&[ChangeHash]>,
        move_cursor: MoveCursor,
    ) -> Result<Cursor, AutomergeError>
       where O: AsRef<ExId>,
             I: Into<CursorPosition>;
    fn get_cursor_position<O>(
        &self,
        obj: O,
        cursor: &Cursor,
        at: Option<&[ChangeHash]>,
    ) -> Result<usize, AutomergeError>
       where O: AsRef<ExId>;
    fn get<O, P>(
        &self,
        obj: O,
        prop: P,
    ) -> Result<Option<(Value<'_>, ExId)>, AutomergeError>
       where O: AsRef<ExId>,
             P: Into<Prop>;
    fn get_at<O, P>(
        &self,
        obj: O,
        prop: P,
        heads: &[ChangeHash],
    ) -> Result<Option<(Value<'_>, ExId)>, AutomergeError>
       where O: AsRef<ExId>,
             P: Into<Prop>;
    fn hydrate<O>(
        &self,
        obj: O,
        heads: Option<&[ChangeHash]>,
    ) -> Result<Value, AutomergeError>
       where O: AsRef<ExId>;
    fn get_all<O, P>(
        &self,
        obj: O,
        prop: P,
    ) -> Result<Vec<(Value<'_>, ExId)>, AutomergeError>
       where O: AsRef<ExId>,
             P: Into<Prop>;
    fn get_all_at<O, P>(
        &self,
        obj: O,
        prop: P,
        heads: &[ChangeHash],
    ) -> Result<Vec<(Value<'_>, ExId)>, AutomergeError>
       where O: AsRef<ExId>,
             P: Into<Prop>;
    fn get_missing_deps(&self, heads: &[ChangeHash]) -> Vec<ChangeHash>;
    fn get_change_by_hash(&self, hash: &ChangeHash) -> Option<Change>;
    fn stats(&self) -> Stats;
    fn text_encoding(&self) -> TextEncoding;

    // Provided method
    fn iter(&self) -> DocIter<'_>  { ... }
}

Methods for reading values from an automerge document

Many of the methods on this trait have an alternate *_at version which takes an additional argument of &[ChangeHash]. This allows you to retrieve the value at a particular point in the document history identified by the given change hashes.

Required Methods

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

where O: AsRef<ExId>,

Get the parents of an object in the document tree.

See the documentation for Parents for more details.

Errors

Returns an error when the id given is not the id of an object in this document. This function does not get the parents of scalar values contained within objects.

Experimental

This function may in future be changed to allow getting the parents from the id of a scalar value.

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

where O: AsRef<ExId>,

Get the parents of the object obj as at heads

See Self::parents()

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

where O: AsRef<ExId>,

Get the keys of the object obj.

For a map this returns the keys of the map. For a list this returns the element ids (opids) encoded as strings.

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

where O: AsRef<ExId>,

Get the keys of the object obj as at heads

See Self::keys()

fn iter_at<O>(&self, obj: O, heads: Option<&[ChangeHash]>) -> DocIter<'_>

where O: AsRef<ExId>,

Iterate over the object obj as at heads

See Self::iter()

fn map_range<'a, O, R>(&'a self, obj: O, range: R) -> MapRange<'a>

where O: AsRef<ExId>, R: RangeBounds<String> + 'a,

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

If the object correspoding to obj is a list then this will return an empty iterator

The returned iterator yields (key, value, exid) tuples, where the third element is the ID of the operation which created the value.

fn map_range_at<'a, O, R>( &'a self, obj: O, range: R, heads: &[ChangeHash], ) -> MapRange<'a>

where O: AsRef<ExId>, R: RangeBounds<String> + 'a,

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

If the object correspoding to obj is a list then this will return an empty iterator

The returned iterator yields (key, value, exid) tuples, where the third element is the ID of the operation which created the value.

See Self::map_range()

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

where O: AsRef<ExId>, R: RangeBounds<usize>,

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

The reuturned iterator yields (index, value, exid) tuples, where the third element is the ID of the operation which created the value.

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

where O: AsRef<ExId>, R: RangeBounds<usize>,

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

The returned iterator yields (index, value, exid) tuples, where the third element is the ID of the operation which created the value.

See Self::list_range()

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

where O: AsRef<ExId>,

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

The returned iterator yields (value, exid) tuples, where the second element is the ID of the operation which created the value.

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

where O: AsRef<ExId>,

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

The returned iterator yields (value, exid) tuples, where the second element is the ID of the operation which created the value.

See Self::values()

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

where O: AsRef<ExId>,

Get the length of the given object.

If the given object is not in this document this method will return 0

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

where O: AsRef<ExId>,

Get the length of the given object as at heads

If the given object is not in this document this method will return 0

See Self::length()

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

where O: AsRef<ExId>,

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

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

where O: AsRef<ExId>,

Get all marks on a current sequence

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

where O: AsRef<ExId>,

Get all marks on a sequence at a given heads

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

where O: AsRef<ExId>,

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

where O: AsRef<ExId>,

Get the string represented by the given text object.

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

where O: AsRef<ExId>,

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

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

where O: AsRef<ExId>,

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

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

where O: AsRef<ExId>,

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

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

where O: AsRef<ExId>, I: Into<CursorPosition>,

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

This is equivalent to Self::get_cursor_moving() with move_cursor = MoveCursor::After.

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

where O: AsRef<ExId>, I: Into<CursorPosition>,

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

Use cases

• User cursor tracking, to maintain contextual position while merging remote changes.
• Indexing sentences in a text field.

Cursor movement

move_cursor determines how the cursor resolves its position if the item originally referenced at the given position is removed in later versions of the document. See MoveCursor for more details.

Start/end cursors

If you’d like a cursor which follows the start (position = 0) or end (position = sequence.length) of the sequence, pass CursorPosition::Start or CursorPosition::End respectively.

Conceptually, start cursors behaves like a cursor pointed an index of -1. End cursors behave like a cursor pointed at sequence.length.

Note that move_cursor does not affect start/end cursors, as the start/end positions can never be removed.

To translate a cursor into a position, see Self::get_cursor_position().

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

where O: AsRef<ExId>,

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

Applicable only for Sequences (either ObjType::List or ObjType::Text).

To reverse the operation, see Self::get_cursor().

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

where O: AsRef<ExId>, P: Into<Prop>,

Get a value out of the document.

This returns a tuple of (value, object ID). This is for two reasons:

1. If value is an object (represented by Value::Object) then the ID is the ID of that object. This can then be used to retrieve nested values from the document.
2. Even if value is a scalar, the ID represents the operation which created the value. This is useful if there are conflicting values for this key as each value is tagged with the ID.

In the case of a key which has conflicting values, this method will return a single arbitrarily chosen value. This value will be chosen deterministically on all nodes. If you want to get all the values for a key use Self::get_all().

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

where O: AsRef<ExId>, P: Into<Prop>,

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

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

where O: AsRef<ExId>,

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

where O: AsRef<ExId>, P: Into<Prop>,

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

If there are multiple conflicting values for a given key this method will return all of them, with each value tagged by the ID of the operation which created it.

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

where O: AsRef<ExId>, P: Into<Prop>,

Get all possibly conflicting values for a key as at heads

See Self::get_all()

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

Provided Methods

fn iter(&self) -> DocIter<'_>

Iterate over all the objects in the document

The returned iterator will iterate over DocObjItems, which are basically an (object ID, property) pair. The property is represented by either a MapRangeItem, ListRangeItem, or a text span represented by a ValueRef depending on the type of the object. The iterator iterates in “causal” order, which means that objects which were created “first” in the documents history are visited first, which in turn means that parent objects are visited before their children.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl ReadDoc for AutoCommit

impl ReadDoc for Automerge

impl ReadDoc for OwnedTransaction

impl ReadDoc for Transaction<'_>