Struct Digested 

pub struct Digested(/* private fields */);

An Rc-guarded abstraction for any object encountered at the “digested” phase of processing

Implementations

impl Digested

pub fn data(&self) -> &DigestedData

immutably borrow the inner Digested data

pub fn cycle_fingerprint(&self) -> u64

A content-aware but COST-BOUNDED fingerprint for the stomach cycle guard (crate::cycle_guard).

Design tension: it must (a) distinguish boxes by content so two different boxes that merely share a shape (e.g. two Lists of equal length but different children) don’t collide into a false cycle, yet (b) be cheap on the digestion path. We reconcile both with a hard node budget: at most FP_BUDGET sub-boxes are ever visited (a depth-first sample of the content), so cost is O(1) per box regardless of how large or deeply nested the structure is, while the sample is rich enough that real content differences change the hash. (It is also only ever invoked once box_list has already blown past the stomach guard’s activation size, so ordinary conversions never pay for it at all.) NOT a stable cross-process hash — for in-run loop detection only.

pub fn estimate_bytes(&self) -> usize

A COST-BOUNDED estimate of the heap bytes this digested box (and its nested content) occupies. Used by the stomach’s portable memory-budget guard (crate::stomach) to detect a runaway by the resource that actually matters — bytes — rather than box COUNT, since per-box weight varies several-fold (a bare text box vs a deeply nested \hbox{\raise…\hbox{…}}). Traversal is capped at EB_BUDGET sub-boxes (depth-first) so the estimate stays O(1) per box; deeply nested boxes beyond the budget are under-counted, which is safe (the guard only needs a monotone lower bound to catch unbounded growth).

pub fn value_of(&self) -> i64

Obtain the i64 value of the digested object, iff it wraps a RegisterValue

pub fn get_dimension(&self) -> Option<Dimension>

Obtain a Dimension from the digested object, iff it wraps a RegisterValue

pub fn pt_value(&self, prec: Option<u8>) -> f64

Obtain the f64 value of the digested object, iff it wraps a RegisterValue

pub fn any<F>(&self, check: F) -> bool

where F: FnMut(&Self) -> bool,

Predicate check - true if any element of the current object passes the check

pub fn all<F>(&self, check: F) -> bool

where F: FnMut(&Self) -> bool,

Predicate check - true if all elements of the current object passes the check

pub fn is_empty(&self) -> Result<bool>

Predicate check - delegates to .is_empty() of the underlying data

pub fn is_skippable(&self) -> bool

Check if all items are “empty” or only spaces or otherwise skippable in a table cell. Perl: isSkippable (Alignment.pm L484-508)

pub fn raw_tokens(&self) -> Option<&Tokens>

Provide a way of emulating an Undigested argument, by requesting raw tokens, only when they are preserved – empty otherwise.

pub fn to_attribute(&self) -> String

builds an attribute-friendly String form of the digested object, suitable for XML attributes

pub fn untex(&self) -> Result<String>

Reverts a digested object to Tokens and extracts a TeX-near string representation of its content

pub fn alignment_cell(&self) -> Option<&RefCell<Alignment>>

Trait Implementations

impl BoxOps for Digested

fn get_font(&self) -> Result<Option<Rc<Font>>>

The box’s font as a SHARED handle.

This used to return Cow<'_, Font>, which was a false promise on exactly the path that matters: the payloads live behind a RefCell, so a Cow::Borrowed cannot outlive the borrow guard and every arm was forced through Cow::Owned(v.into_owned()) — a deep Font clone on every call, even though Tbox/List/Whatsit all already hold an Rc<Font>.

That clone was the single largest allocation in a conversion. Measured 2026-07-29 with --features dhat-heap on 100k words of plain prose: Rc<Font>::new accounted for 392 MB of the 840 MB peak (47 %) across 1,196,000 blocks of 344 B — one per box absorbed — reached via List::new ← append_node_box ← open_text ← absorb. The digested boxes themselves came to 164 MB, so the font attached to each box cost 2.4x the box. No caller ever used Cow’s one advantage (to_mut).

fn compute_size( &self, options: HashMap<Stored>, ) -> Result<(Dimension, Dimension, Dimension)>

Note the difference between calling compute_size on a Digested object, and calling it on a concrete box type. When called on Digested it will opt for caching the computed sizes, but when called on the concrete types it will always compute sizes fresh.

fn unlist(&self) -> Vec<Digested>

If composite, unwrap into the contained digested objects (or return self)

fn unlist_ref(&self) -> Vec<Cow<'_, Digested>>

fn be_absorbed(&self, document: &mut Document) -> Result<Vec<Node>>

absorb the current object into the Document XML - returning the corresponding nodes

fn with_properties<R, FnR>(&self, caller: FnR) -> R

where FnR: FnOnce(&HashMap<Stored>) -> R,

execute a function using this object’s named properties

fn set_property<T: Into<Stored>>(&mut self, key: &str, value: T)

set a named property (allows all Stored types for values)

fn get_property(&self, key: &str) -> Option<Cow<'_, Stored>>

get a single named property (with special “isSpace” check)

fn get_string(&self) -> Result<Cow<'_, str>>

build a string representation of the underlying digested data

fn has_property(&self, key: &str) -> bool

checks if a property key has been set

fn get_body(&self) -> Result<Option<Digested>>

obtains the “body” of a digested object which captured it

fn get_property_bool(&self, key: &str) -> bool

obtains a boolean property value (false unless Stored::Bool)

fn be_absorbed_mut(&mut self, _document: &mut Document) -> Result<Vec<Node>>

be_absorbed but with allowed side-effects on the carrier (for Alignment only)

fn get_tokens(&self) -> Option<&Tokens>

get the underlying tokens (preceding digestion)

fn get_properties(&self) -> &HashMap<Stored>

deprecated: get the map of named properties. This can not be usable as long as we have any data behind a RefCell wrapper. Use with_properties instead.

fn get_properties_mut(&mut self) -> &mut HashMap<Stored>

get a mutable reference to the map of named properties

fn get_property_string(&self, key: &str) -> String

fn get_property_mut(&mut self, key: &str) -> Option<&mut Stored>

get a mutable reference to a single named property (does NOT have the “isSpace” check)

fn set_font(&mut self, _font: Rc<Font>)

sets an associated font

fn set_width<T: Into<Stored>>(&mut self, width: T)

sets a “width” property, for sizing

fn get_width( &self, options: Option<HashMap<Stored>>, ) -> Result<Option<RegisterValue>>

gets the “width” property value, if any

fn set_height<T: Into<Stored>>(&mut self, width: T)

sets a “height” property value, for sizing

fn get_height(&self) -> Option<RegisterValue>

gets the “height” property value, if any. Checks “height”, then “cached_height”, then computes from font if needed.

fn set_depth<T: Into<Stored>>(&mut self, width: T)

sets a “depth” property value, for sizing

fn get_depth(&self) -> Option<RegisterValue>

gets the “depth” property value, if any. Checks “depth”, then “cached_depth”, then computes from font if needed.

fn get_size( &mut self, options: Option<HashMap<Stored>>, ) -> Result<(Dimension, Dimension, Dimension, Dimension, Dimension, Dimension)>

gets the box size as a triple of (width, height, depth) the generic implementation is immutable and will recompute the size on each call see Digested::get_size for a variant with interior mutability which caches the box size

fn compute_size_and_cache( &mut self, options: HashMap<Stored>, ) -> Result<(Dimension, Dimension, Dimension)>

computes and caches (via named properties) the size of a box-like object. Perl #2798 (S5, padding slice): after computing the size, add any requested pad{top,bottom,left,right} to the computed dimensions. This is the SAFE part of computeSizeStore — additive and inert until the app layer sets a pad* property (display math \abovedisplayskip/\belowdisplayskip, \overline/\underline 2pt, items/equations). The riskier requested-vs- computed merge + full-spec bypass + isEmpty are deliberately NOT included here — a mechanical port of those regressed (Rust boxes don’t use width/height/depth uniformly as “requested box size”); see SYNC_STATUS U2.

impl Clone for Digested

fn clone(&self) -> Digested

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Digested

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

Formats the value using the given formatter.

impl Default for Digested

fn default() -> Self

Returns the “default value” for a type.

impl Display for Digested

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

Formats the value using the given formatter.

impl<'a> From<&'a Digested> for Option<Digested>

fn from(value: &'a Digested) -> Option<Digested>

Converts to this type from the input type.

impl<'a> From<&'a String> for Digested

fn from(value: &'a String) -> Digested

Converts to this type from the input type.

impl From<&Digested> for Stored

fn from(value: &Digested) -> Self

Converts to this type from the input type.

impl From<Alignment> for Digested

fn from(value: Alignment) -> Digested

Converts to this type from the input type.

impl From<Box<Digested>> for Stored

fn from(value: Box<Digested>) -> Self

Converts to this type from the input type.

impl From<Comment> for Digested

fn from(value: Comment) -> Digested

Converts to this type from the input type.

impl From<Digested> for Stored

fn from(value: Digested) -> Self

Converts to this type from the input type.

impl From<Digested> for Result<Digested>

fn from(value: Digested) -> Result<Digested>

Converts to this type from the input type.

impl From<Digested> for Result<Vec<Digested>>

fn from(value: Digested) -> Result<Vec<Digested>>

Converts to this type from the input type.

impl From<Digested> for Result<Option<Digested>>

fn from(value: Digested) -> Result<Option<Digested>>

Converts to this type from the input type.

impl From<KeyVals> for Digested

fn from(value: KeyVals) -> Digested

Converts to this type from the input type.

impl From<List> for Digested

fn from(value: List) -> Digested

Converts to this type from the input type.

impl From<RegisterValue> for Digested

fn from(value: RegisterValue) -> Digested

Converts to this type from the input type.

impl From<String> for Digested

fn from(value: String) -> Digested

Converts to this type from the input type.

impl From<SymbolU32> for Digested

fn from(sym: SymStr) -> Digested

Converts to this type from the input type.

impl From<Tbox> for Digested

fn from(value: Tbox) -> Digested

Converts to this type from the input type.

impl From<Tokens> for Digested

fn from(value: Tokens) -> Digested

Converts to this type from the input type.

impl From<Whatsit> for Digested

fn from(value: Whatsit) -> Digested

Converts to this type from the input type.

impl IntoDigestedResult<Result<Vec<Digested>, Error>> for Digested

fn into_digested_result(self) -> Result<Vec<Digested>>

Performs the conversion, used for DefPrimitive return values etc

impl Object for Digested

fn revert(&self) -> Result<Tokens>

The source tokens this digested value came from — digestion run backwards, delegated to whichever variant is held.

What \meaning-style introspection and the tex attribute are built on: a construct that has already become boxes, a whatsit or an alignment can still show the LaTeX that produced it. A Postponed variant is already tokens and reverts to itself.

fn stringify(&self) -> String

fn get_locator(&self) -> Option<Locator>

The object’s stored source locator, if it has one. None is the honest “no recorded source position” (replacing the old Locator::default() file!()/line!() sentinel). For “where the parser is now” (error reporting, box creation), use the free fn gullet::get_locator().

fn isa_box(&self) -> bool

fn is_expandable(&self) -> bool

fn is_definition(&self) -> bool

fn is_comment(&self) -> bool

fn be_digested(self) -> Result<Digested>

where Self: Sized + Debug,

impl PartialEq for Digested

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

Equality operator ==.

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

Inequality operator !=.