Struct DocumentMark 

pub struct DocumentMark {
    pub start: u32,
    pub end: u32,
    pub name: String,
    pub ordinal: u32,
}

One named position or range in the document’s addressable character space.

Fields

start: u32

[start, end) in the document’s addressable character space — the same space DocumentComment::start uses, and the same one TextDocument::to_addressable_text() reports. start == end is a point mark.

end: u32

name: String

The bookmark name, which is the whole message. See validate.

ordinal: u32

Which of several marks sharing this exact range comes first.

Zero for every mark that does not share its range with another, which is almost all of them, so it can be ignored by any caller that never emits two.

It exists because ties have to break the same way on both payloads. A comment and the mark carrying its identity are two objects the writers sort independently: DocumentComments breaks a tie on the comment’s uid, and this on the mark’s name. Where a name is derived from a uid by hashing — which is what a 40-character bookmark limit forces — the two orders are uncorrelated, so a document with two comments on the identical range can emit the annotations in one order and their marks in the other. A reader matching them by position then hands each comment the other’s identity, and the editor’s remark comes home on the wrong thread.

The producer knows the intended order and nothing else can recover it, so the producer says: set this from the same sequence the comments are built in.

#[serde(default)] because this field was added after the type shipped: a payload serialized before it exists has no ordinal, and reading it back must give 0 rather than fail. The default is also the correct answer for such a payload — it was written by a producer that stated no order.

Implementations

impl DocumentMark

pub fn point(at: u32, name: impl Into<String>) -> DocumentMark

A point mark at at.

pub fn range(start: u32, end: u32, name: impl Into<String>) -> DocumentMark

A range mark over [start, end).

pub fn with_ordinal(self, ordinal: u32) -> DocumentMark

This mark, ordered ahead of or behind others sharing its exact range.

See ordinal — required only when two marks can span the same characters, which for a host carrying comment identity means two comments on one paragraph.

pub fn is_point(&self) -> bool

True when this mark names a position rather than a span.

pub fn validate(&self) -> Result<(), String>

Check the name against the stricter of the two formats’ rules, and the range against itself.

Returns a description of the problem rather than a bool, because every caller of this wants to say what was wrong: these names are minted by the host from its own data, so a rejected one is a programming error and deserves to be reported as one — not silently dropped, which would leave an export that looks complete and cannot be read back.

Trait Implementations

impl Clone for DocumentMark

fn clone(&self) -> DocumentMark

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DocumentMark

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

Formats the value using the given formatter.

impl Default for DocumentMark

fn default() -> DocumentMark

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for DocumentMark

fn deserialize<__D>( __deserializer: __D, ) -> Result<DocumentMark, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for DocumentMark

impl PartialEq for DocumentMark

fn eq(&self, other: &DocumentMark) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for DocumentMark

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for DocumentMark