Struct Molecule 

pub struct Molecule { /* private fields */ }

Implementations

impl Molecule

pub fn atom_count(&self) -> usize

Number of heavy atoms (does not count implicit H).

pub fn bond_count(&self) -> usize

Number of bonds (edges).

pub fn atom(&self, idx: AtomIdx) -> &Atom

Borrow atom by index.

Panics

Panics if idx is out of range (should not happen with indices from this molecule).

For a non-panicking variant, use Self::atom_opt.

pub fn atom_opt(&self, idx: AtomIdx) -> Option<&Atom>

Borrow atom by index, returning None if out of range.

pub fn bond(&self, idx: BondIdx) -> &BondEntry

Borrow bond by index.

Panics

Panics if idx is out of range (should not happen with indices from this molecule).

For a non-panicking variant, use Self::bond_opt.

pub fn bond_opt(&self, idx: BondIdx) -> Option<&BondEntry>

Borrow bond by index, returning None if out of range.

pub fn atoms(&self) -> impl Iterator<Item = (AtomIdx, &Atom)>

Iterate over all atoms as (AtomIdx, &Atom).

pub fn bonds(&self) -> impl Iterator<Item = (BondIdx, &BondEntry)>

Iterate over all bonds as (BondIdx, &BondEntry).

pub fn neighbors( &self, idx: AtomIdx, ) -> impl Iterator<Item = (AtomIdx, BondIdx)> + '_

Iterate over neighbors of idx as (neighbor_atom_idx, bond_idx).

Panics

Panics if idx is out of range (should not happen with indices from this molecule).

For a non-panicking variant, use Self::neighbors_opt.

pub fn neighbors_opt(&self, idx: AtomIdx) -> Option<Vec<(AtomIdx, BondIdx)>>

Iterate over neighbors of idx as (neighbor_atom_idx, bond_idx), returning None if out of range.

pub fn degree(&self, idx: AtomIdx) -> usize

Degree (number of connected bonds) of atom idx.

Panics

Panics if idx is out of range (should not happen with indices from this molecule).

For a non-panicking variant, use Self::degree_opt.

pub fn degree_opt(&self, idx: AtomIdx) -> Option<usize>

Degree (number of connected bonds) of atom idx, returning None if out of range.

pub fn bond_between( &self, a: AtomIdx, b: AtomIdx, ) -> Option<(BondIdx, &BondEntry)>

Return the bond between a and b, or None if not connected or indices are out of bounds.

pub fn formula(&self) -> String

Molecular formula as a Hill-order string (C first, H second, then alphabetical).

impl Molecule

pub fn with_atom_added(&self, atom: Atom) -> (Molecule, AtomIdx)

Return a new Molecule with one extra atom appended, along with the index that the new atom will have in the returned molecule.

pub fn with_bond_added( &self, a: AtomIdx, b: AtomIdx, order: BondOrder, ) -> Result<(Molecule, BondIdx), MolError>

Return a new Molecule with one extra bond added, along with the index of the newly added bond in the returned molecule.

Returns Err if a == b or the bond already exists (same semantics as MoleculeBuilder::add_bond).

pub fn with_atom_charge(&self, idx: AtomIdx, charge: i8) -> Molecule

Return a new Molecule with the formal charge of atom idx changed.

pub fn with_atom_element(&self, idx: AtomIdx, el: Element) -> Molecule

Return a new Molecule with the element of atom idx changed.

Chirality and hydrogen count are reset to None when the element changes, since those properties are element-specific.

pub fn with_atom_removed( &self, idx: AtomIdx, ) -> (Molecule, Vec<Option<AtomIdx>>)

Return a new Molecule with atom idx and all bonds involving it removed. Atom indices of survivors shift down past the removed slot.

The returned tuple also includes a mapping from old AtomIdx to new AtomIdx (indices that fall below idx are unchanged; indices above idx decrease by 1).

pub fn implicit_hydrogen_count(&self, idx: AtomIdx) -> u8

Implicit hydrogen count for atom idx based on valence rules.

Delegates to crate::valence::implicit_hcount.

pub fn total_formula(&self) -> String

Hill-order molecular formula including implicit hydrogens.

Unlike Self::formula (which counts only explicit heavy atoms), this method adds the implicit H count for every atom so the result reflects the true molecular composition (e.g. methane → “CH4”).

pub fn formula_with_isotopes(&self) -> String

Hill-order molecular formula with isotope labels.

Like Self::formula but prefixes each element symbol with its isotope number when atom.isotope is Some(n). Example: a molecule with one ¹³C and one O → "¹³CO".

pub fn with_atom_aromatic(&self, idx: AtomIdx, aromatic: bool) -> Molecule

Return a new Molecule with atom idx’s aromatic flag changed.

pub fn with_bond_order(&self, idx: BondIdx, order: BondOrder) -> Molecule

Return a new Molecule with bond idx’s order changed.

pub fn with_bond_removed(&self, idx: BondIdx) -> Molecule

Return a new Molecule with bond idx removed.

Atom indices are unchanged. Bond indices of survivors shift down.

impl Molecule

pub fn add_atom(&mut self, atom: Atom) -> AtomIdx

Append a new atom and return its index.

pub fn remove_atom(&mut self, idx: AtomIdx) -> Vec<Option<AtomIdx>>

Remove atom idx and all bonds involving it.

Returns a remapping table: remap[old_idx] gives the new AtomIdx for surviving atoms, or None for the removed atom. Atom indices of atoms after the removed slot shift down by 1.

pub fn add_bond( &mut self, a: AtomIdx, b: AtomIdx, order: BondOrder, ) -> Result<BondIdx, MolError>

Add a bond between a and b with the given order.

Returns Err if a == b or the bond already exists.

pub fn remove_bond(&mut self, idx: BondIdx)

Remove bond idx. Atom indices are unchanged; bond indices of surviving bonds shift down past the removed slot.

pub fn set_charge(&mut self, idx: AtomIdx, charge: i8)

Set the formal charge of atom idx in-place.

pub fn set_element(&mut self, idx: AtomIdx, el: Element)

Set the element of atom idx in-place.

Chirality and hydrogen count are reset (element-specific properties).

pub fn set_cip_code(&mut self, idx: AtomIdx, code: Option<CipCode>)

Set the CIP stereo code of atom idx in-place.

pub fn stereo_groups(&self) -> &[StereoGroup]

Return the enhanced stereo groups attached to this molecule.

pub fn set_stereo_groups(&mut self, groups: Vec<StereoGroup>)

Replace the stereo group list in-place.

pub fn add_stereo_group(&mut self, group: StereoGroup)

Add a single stereo group in-place.

pub fn stereo_neighbor_order(&self, idx: AtomIdx) -> Option<&[u32]>

SMILES-text-order neighbor sequence for a chiral atom.

Returns None for atoms not parsed from SMILES or without stereo. The slice contains neighbor atom indices in SMILES text order; STEREO_H_SENTINEL (u32::MAX) marks the implicit bracket-H slot.

pub fn set_stereo_neighbor_order(&mut self, idx: AtomIdx, order: Vec<u32>)

Set the SMILES stereo neighbor order for atom idx.

impl Molecule

pub fn is_connected(&self) -> bool

Return true if the molecule has exactly one connected component (i.e. every atom can be reached from every other atom).

pub fn fragments(&self) -> Vec<Molecule>

Split the molecule into its connected components.

Returns a Vec of sub-molecules, one per component. Atoms are renumbered within each sub-molecule starting at index 0.