Struct DependencyGraph 

pub struct DependencyGraph { /* private fields */ }

SoA-based dependency graph implementation

Implementations

impl DependencyGraph

pub fn range_expansion_limit(&self) -> usize

Expose range expansion limit for planners

pub fn get_config(&self) -> &EvalConfig

pub fn plan_dependencies<'a, I>( &mut self, items: I, policy: &CollectPolicy, volatile: Option<&[bool]>, ) -> Result<DependencyPlan, ExcelError>

where I: IntoIterator<Item = (&'a str, u32, u32, &'a ASTNode)>,

Build a dependency plan for a set of formulas on sheets

pub fn ensure_vertices_batch( &mut self, coords: &[(SheetId, PackedCoord)], ) -> Vec<(PackedCoord, u32)>

Ensure vertices exist for given coords; allocate missing in contiguous batches and add to edges/index. Returns a list suitable for edges.add_vertices_batch.

pub fn set_first_load_assume_new(&mut self, enabled: bool)

Enable/disable the first-load fast path for value inserts.

pub fn reset_ensure_touched(&mut self)

Reset the per-sheet ensure touch tracking.

pub fn store_asts_batch<'a, I>(&mut self, asts: I) -> Vec<AstNodeId>

where I: IntoIterator<Item = &'a ASTNode>,

Store ASTs in batch and return their arena ids

pub fn vid_for_sid_pc(&self, sid: SheetId, pc: PackedCoord) -> Option<VertexId>

Lookup VertexId for a (SheetId, PackedCoord)

pub fn vid_for_plan_idx( &self, plan: &DependencyPlan, idx: u32, ) -> Option<VertexId>

Helper to map a global cell index in a plan to a VertexId

pub fn assign_formula_vertex( &mut self, vid: VertexId, ast_id: AstNodeId, volatile: bool, )

Assign a formula to an existing vertex, removing prior edges and setting flags

pub fn add_edges_nobatch( &mut self, dependent: VertexId, dependencies: &[VertexId], )

Public wrapper for adding edges without beginning a batch (caller manages batch)

pub fn add_range_edges( &mut self, dependent: VertexId, ranges: &[ReferenceType], current_sheet_id: SheetId, )

Public wrapper to add range-dependent edges

pub fn iter_vertex_ids(&self) -> impl Iterator<Item = VertexId> + '_

Iterate all normal vertex ids

pub fn vertex_coord(&self, vid: VertexId) -> PackedCoord

Get current PackedCoord for a vertex

pub fn vertex_count(&self) -> usize

Total number of allocated vertices (including deleted)

pub fn build_edges_from_adjacency( &mut self, adjacency: Vec<(u32, Vec<u32>)>, coords: Vec<PackedCoord>, vertex_ids: Vec<u32>, )

Replace CSR edges in one shot from adjacency and coords

pub fn used_row_bounds_for_columns( &self, sheet_id: SheetId, start_col: u32, end_col: u32, ) -> Option<(u32, u32)>

Compute min/max used row among vertices within [start_col..=end_col] on a sheet.

pub fn finalize_sheet_index(&mut self, sheet: &str)

Build (or rebuild) the sheet index for a given sheet if running in Lazy mode.

pub fn set_sheet_index_mode(&mut self, mode: SheetIndexMode)

pub fn used_col_bounds_for_rows( &self, sheet_id: SheetId, start_row: u32, end_row: u32, ) -> Option<(u32, u32)>

Compute min/max used column among vertices within [start_row..=end_row] on a sheet.

pub fn sheet_has_formulas(&self, sheet_id: SheetId) -> bool

Returns true if the given sheet currently contains any formula vertices.

pub fn new() -> Self

pub fn new_with_config(config: EvalConfig) -> Self

pub fn begin_batch(&mut self)

Begin batch operations - defer CSR rebuilds until end_batch() is called

pub fn end_batch(&mut self)

End batch operations and trigger CSR rebuild if needed

pub fn default_sheet_id(&self) -> SheetId

pub fn default_sheet_name(&self) -> &str

pub fn set_default_sheet_by_name(&mut self, name: &str)

pub fn set_default_sheet_by_id(&mut self, id: SheetId)

pub fn sheet_id_mut(&mut self, name: &str) -> SheetId

Returns the ID for a sheet name, creating one if it doesn’t exist.

pub fn sheet_id(&self, name: &str) -> Option<SheetId>

pub fn sheet_name(&self, id: SheetId) -> &str

Returns the name of a sheet given its ID.

pub fn sheet_reg(&self) -> &SheetRegistry

Access the sheet registry (read-only) for external bindings

pub fn to_a1(&self, cell_ref: CellRef) -> String

Converts a CellRef to a fully qualified A1-style string (e.g., “Sheet1!A1”).

pub fn define_name( &mut self, name: &str, definition: NamedDefinition, scope: NameScope, ) -> Result<(), ExcelError>

Define a new named range

pub fn named_ranges_iter(&self) -> impl Iterator<Item = (&String, &NamedRange)>

Iterate workbook-scoped named ranges (for bindings/testing)

pub fn sheet_named_ranges_iter( &self, ) -> impl Iterator<Item = (&(SheetId, String), &NamedRange)>

Iterate sheet-scoped named ranges (for bindings/testing)

pub fn resolve_name( &self, name: &str, current_sheet: SheetId, ) -> Option<&NamedDefinition>

Resolve a named range to its definition

pub fn update_name( &mut self, name: &str, new_definition: NamedDefinition, scope: NameScope, ) -> Result<(), ExcelError>

Update an existing named range definition

pub fn delete_name( &mut self, name: &str, scope: NameScope, ) -> Result<(), ExcelError>

Delete a named range

pub fn get_range_dependencies( &self, vertex: VertexId, ) -> Option<&Vec<ReferenceType>>

Return the compressed range dependencies recorded for a formula vertex, if any. These are ReferenceType::Range entries that were not expanded into explicit cell edges due to range_expansion_limit or due to infinite/partial bounds.

pub fn sheet_index_mut(&mut self, sheet_id: SheetId) -> &mut SheetIndex

Get mutable access to a sheet’s index, creating it if it doesn’t exist This is the primary way VertexEditor and internal operations access the index

pub fn sheet_index(&self, sheet_id: SheetId) -> Option<&SheetIndex>

Get immutable access to a sheet’s index, returns None if not initialized

pub fn set_cell_value( &mut self, sheet: &str, row: u32, col: u32, value: LiteralValue, ) -> Result<OperationSummary, ExcelError>

Set a value in a cell, returns affected vertex IDs

pub fn reserve_cells(&mut self, additional: usize)

Reserve capacity hints for upcoming bulk cell inserts (values only for now).

pub fn set_cell_value_bulk_untracked( &mut self, sheet: &str, row: u32, col: u32, value: LiteralValue, )

Fast path for initial bulk load of value cells: avoids dirty propagation & dependency work.

pub fn bulk_insert_values<I>(&mut self, sheet: &str, cells: I)

where I: IntoIterator<Item = (u32, u32, LiteralValue)>,

Bulk insert a collection of plain value cells (no formulas) more efficiently.

pub fn set_cell_formula( &mut self, sheet: &str, row: u32, col: u32, ast: ASTNode, ) -> Result<OperationSummary, ExcelError>

Set a formula in a cell, returns affected vertex IDs

pub fn set_cell_formula_with_volatility( &mut self, sheet: &str, row: u32, col: u32, ast: ASTNode, volatile: bool, ) -> Result<OperationSummary, ExcelError>

Set a formula in a cell with a known volatility flag (context-scoped detection upstream)

pub fn get_cell_value( &self, sheet: &str, row: u32, col: u32, ) -> Option<LiteralValue>

Get current value from a cell

pub fn get_evaluation_vertices(&self) -> Vec<VertexId>

Get all vertices that need evaluation

pub fn clear_dirty_flags(&mut self, vertices: &[VertexId])

Clear dirty flags after successful evaluation

pub fn clear_volatile_flags(&mut self)

🔮 Scalability Hook: Clear volatile vertices after evaluation cycle

pub fn bulk_set_formulas<I>( &mut self, sheet: &str, items: I, ) -> Result<usize, ExcelError>

where I: IntoIterator<Item = (u32, u32, ASTNode)>,

Bulk set formulas on a sheet using a single dependency plan and batched edge updates.

pub fn add_dependency_edge(&mut self, dependent: VertexId, dependency: VertexId)

Public (crate) helper to add a single dependency edge (dependent -> dependency) used for restoration/undo.

pub fn add_range_deps_from_keys( &mut self, dependent: VertexId, keys: &[RangeKey], current_sheet_id: SheetId, )

Fast-path: add range dependencies using compact RangeKey without string conversions.

pub fn plan_spill_region( &self, anchor: VertexId, target_cells: &[CellRef], ) -> Result<(), ExcelError>

Plan a spill region for an anchor; returns #SPILL! if blocked

pub fn commit_spill_region_atomic_with_fault( &mut self, anchor: VertexId, target_cells: Vec<CellRef>, values: Vec<Vec<LiteralValue>>, fault_after_ops: Option<usize>, ) -> Result<(), ExcelError>

Commit a spill atomically with an internal shadow buffer and optional fault injection. If a fault is injected partway through, all changes are rolled back to the pre-commit state. This does not change behavior under normal operation; it’s primarily for Phase 3 guarantees and tests.

pub fn clear_spill_region(&mut self, anchor: VertexId)

Clear an existing spill region for an anchor (set cells to Empty and forget ownership)

pub fn get_formula(&self, vertex_id: VertexId) -> Option<ASTNode>

Get the formula AST for a vertex

pub fn get_value(&self, vertex_id: VertexId) -> Option<LiteralValue>

Get the value stored for a vertex

pub fn make_cell_ref(&self, sheet_name: &str, row: u32, col: u32) -> CellRef

Create a cell reference from sheet name and coordinates

pub fn get_vertex_id_for_address(&self, addr: &CellRef) -> Option<&VertexId>

Get vertex ID for a cell address

pub fn is_ref_error(&self, id: VertexId) -> bool

Check if a vertex has a #REF! error

pub fn get_vertex_for_cell(&self, addr: &CellRef) -> Option<VertexId>

Get vertex ID for specific cell address

pub fn get_coord(&self, id: VertexId) -> PackedCoord

Get coord for a vertex (public for VertexEditor)

pub fn get_sheet_id(&self, id: VertexId) -> SheetId

Get sheet_id for a vertex (public for VertexEditor)

pub fn vertices_in_sheet( &self, sheet_id: SheetId, ) -> impl Iterator<Item = VertexId> + '_

Get all vertices in a sheet

pub fn vertex_has_formula(&self, id: VertexId) -> bool

Does a vertex have a formula associated

pub fn vertices_with_formulas(&self) -> impl Iterator<Item = VertexId> + '_

Get all vertices with formulas

pub fn update_vertex_formula( &mut self, id: VertexId, ast: ASTNode, ) -> Result<(), ExcelError>

Update a vertex’s formula

pub fn mark_vertex_dirty(&mut self, vertex_id: VertexId)

Mark a vertex as dirty without propagation (for VertexEditor)

pub fn update_cell_mapping( &mut self, id: VertexId, old_addr: Option<CellRef>, new_addr: CellRef, )

Update cell mapping for a vertex (for VertexEditor)

pub fn remove_cell_mapping(&mut self, addr: &CellRef)

Remove cell mapping (for VertexEditor)

pub fn get_cell_ref_for_vertex(&self, id: VertexId) -> Option<CellRef>

Get the cell reference for a vertex

pub fn adjust_named_ranges( &mut self, operation: &ShiftOperation, ) -> Result<(), ExcelError>

Adjust named ranges during row/column operations

pub fn mark_as_name_error(&mut self, vertex_id: VertexId)

Mark a vertex as having a #NAME! error

impl DependencyGraph

pub fn add_sheet(&mut self, name: &str) -> Result<SheetId, ExcelError>

Add a new sheet to the workbook

Creates a new sheet with the given name. If a sheet with this name already exists, returns its ID without error (idempotent operation).

Arguments

• name - The name for the new sheet

Returns

The SheetId of the new or existing sheet

pub fn remove_sheet(&mut self, sheet_id: SheetId) -> Result<(), ExcelError>

Remove a sheet from the workbook

Removes the specified sheet and all its contents. This operation:

• Deletes all vertices (cells/formulas) in the sheet
• Updates all formulas that reference the deleted sheet to show #REF! errors
• Removes sheet-scoped named ranges
• Cleans up all internal structures

Arguments

• sheet_id - The ID of the sheet to remove

Errors

Returns an error if:

• The sheet doesn’t exist
• Trying to remove the last sheet (workbook must have at least one sheet)

pub fn rename_sheet( &mut self, sheet_id: SheetId, new_name: &str, ) -> Result<(), ExcelError>

Rename an existing sheet

Changes the name of a sheet while preserving all its contents and references. All formulas that reference the sheet by name are automatically updated.

Arguments

• sheet_id - The ID of the sheet to rename
• new_name - The new name for the sheet

Errors

Returns an error if:

• The sheet doesn’t exist
• The new name is already used by another sheet
• The new name is invalid (empty or too long)

pub fn duplicate_sheet( &mut self, source_sheet_id: SheetId, new_name: &str, ) -> Result<SheetId, ExcelError>

Duplicate an existing sheet

Creates a copy of a sheet with all its contents. The new sheet will have the specified name and contain copies of all cells, values, and formulas from the source sheet. Formula references within the sheet are updated to point to the new sheet.

Arguments

• source_sheet_id - The ID of the sheet to duplicate
• new_name - The name for the new sheet

Returns

The SheetId of the newly created sheet

Errors

Returns an error if:

• The source sheet doesn’t exist
• The new name is already used
• The new name is invalid

Trait Implementations

impl Debug for DependencyGraph

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

Formats the value using the given formatter.

impl Default for DependencyGraph

fn default() -> Self

Returns the “default value” for a type.