Struct Block 

#[non_exhaustive]
pub struct Block {
    pub kind: BlockKind,
    pub page: usize,
    pub bbox: [f64; 4],
    pub text: String,
    pub spans: Vec<TextSpan>,
    pub index: usize,
    pub continues_previous: bool,
    pub confidence: Option<f64>,
    pub grid: Option<GridDoubt>,
    /* private fields */
}

One block of a document’s structured text: what a caller chunks, cites or embeds.

The fields are the ones the serializers consume (#572): the kind, where it is, what it says, what it was made of, and where it falls in the reading order of the whole document.

#[non_exhaustive], DECIDED AFTER TWO FIELDS HAD ALREADY BROKEN IT (codex on #1977 and #1989). This is a type callers READ: extract_blocks returns it and nothing outside this crate has a reason to build one. But it was an exhaustive public struct in a 1.0.0 crate, so confidence and then grid each made every downstream literal fail to compile – and the learned work has more of both coming, one per model that has something to say about a block. Closing it now means the next field costs nobody anything.

Construct one with Block::new and set the rest, which is what this crate’s own examples do.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

kind: BlockKind

What this block is.

page: usize

0-based page index the block was drawn on.

bbox: [f64; 4]

Bounding box in PDF user space, [x0, y0, x1, y1] with y up and y0 < y1. The union of the glyph boxes of every span in the block.

text: String

The block’s text, with the line breaks of the measure removed: lines are joined by a space, and a word the typesetter broke across a line is put back together.

spans: Vec<TextSpan>

Every span the block is made of, in the order the page DRAWS them: left to right, line by line.

Visual and not logical, which matters on a line of Arabic or Hebrew: the spans carry the geometry, and the geometry is visual, so extraction leaves them where the page put them and reorders only the text (TextBlock::text, #436). text above is therefore the logical reading and this is not, and a caller rebuilding the text from the spans of a right-to-left block has to reorder them itself (codex, round 1).

index: usize

Position of this block in the document’s reading order, counted from the first block of the first page.

The running heads a document repeats are not in that order: they carry the numbers after the last block of the body, which is where [crate::reading_order] puts them (#571).

continues_previous: bool

Whether the block continues the one before it in the reading order, because the page broke a paragraph in two (#571).

A RELATION AND NOT A MERGE. The two halves are set on two pages, so one paragraph there has two boxes and two page numbers, and a merged block could state neither: Self::bbox is one rectangle and Self::page is one page. The serializers join what this marks – crate::markdown writes the two as one paragraph – and a caller chunking the document joins it the same way, with the geometry of both halves still in front of it.

confidence: Option<f64>

How sure the learned model is of Self::kind, between 0 and 1, or None where no model spoke about this block (#624).

WHAT None MEANS, because it is not “we are unsure”. A block that no model has an opinion about carries the heuristics’ verdict, and the heuristics do not produce a probability – they produce a decision. So None is “nobody measured this”, and a caller that wants to route the doubtful cases somewhere must treat it as unknown rather than as low.

Today the only model on master that answers is the list-item one of #599, so a paragraph that model considered carries its probability and a heading carries None until #599’s heading model lands. The value is the model’s own probability for the decision it made, not a calibrated confidence over all kinds: 0.9 on a list item means the item model put 0.9 on “this is an item”, and says nothing about the alternative kinds.

AND IT IS THE PROBABILITY OF THE DECISION THAT PRODUCED THIS BLOCK’S KIND, which is not always the one the block began with (codex on #1977). A block the opens model cuts into three items has three pieces whose kinds come from three different lines’ probabilities, and each piece reports its own. A block whose kind the heuristics decided carries None even where a model ran on it and agreed, because a number about a decision nobody acted on would read as a number about this kind.

grid: Option<GridDoubt>

What the heuristic builder had to go on when it found this cell’s table, or None for a block that is not a table cell (#574).

See GridDoubt: five facts rather than a score, and a property of the table repeated on each of its cells.

Implementations

impl Block

pub fn new( kind: BlockKind, page: usize, bbox: [f64; 4], text: String, index: usize, ) -> Self

A block with the fields every kind has, and the rest left at their defaults: no confidence, no grid evidence, not a continuation.

The way to build one from outside this crate, now that Block is #[non_exhaustive]. The five arguments are the ones no block can do without – a kind, a page, a box, its text and its place in the reading order – and everything else is set afterwards on the returned value.

Trait Implementations

impl Clone for Block

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Block

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

Formats the value using the given formatter.