Struct Residue 

pub struct Residue {
    pub id: i32,
    pub insertion_code: Option<char>,
    pub name: String,
    pub standard_name: Option<StandardResidue>,
    pub category: ResidueCategory,
    pub position: ResiduePosition,
    /* private fields */
}

A residue within a biomolecular structure.

Residues capture crystallographic identifiers (sequence number and insertion code), the original and normalized names, classification metadata, and the atoms that belong to the residue. They are the primary unit passed between IO routines, topology builders, and structure editing operations.

Fields

id: i32

Author-provided sequence identifier (can be negative for certain files).

insertion_code: Option<char>

Optional insertion code differentiating records that share the same id.

name: String

Original residue name as encountered during parsing.

standard_name: Option<StandardResidue>

Canonical residue assignment if the name maps to a standard alphabet entry.

category: ResidueCategory

Category describing whether the residue is standard, heterogen, or ion.

position: ResiduePosition

Chain position annotation (terminus, internal, or nucleic end).

Implementations

impl Residue

pub fn new( id: i32, insertion_code: Option<char>, name: &str, standard_name: Option<StandardResidue>, category: ResidueCategory, ) -> Self

Creates a residue with the provided identifiers and classification.

The residue starts without atoms and defaults to ResiduePosition::None until the caller updates it based on chain topology.

Arguments

• id - Sequence number pulled from the original structure file.
• insertion_code - Optional insertion code for distinguishing alternate residues.
• name - Author-provided residue label (e.g., "ALA", "DN1").
• standard_name - Canonical assignment when the residue matches a standard entry.
• category - Classification describing standard, hetero, or ion behavior.

Returns

A Residue ready for atoms to be added.

pub fn is_standard(&self) -> bool

Reports whether the residue maps to a standard residue definition.

Returns

true when standard_name is set.

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

Appends an atom to the residue.

Duplicate atom names are guarded with a debug assertion to prevent inconsistent topologies while still allowing release builds to proceed.

Arguments

• atom - The atom to insert; ownership moves into the residue.

Panics

Panics in debug builds if an atom with the same name already exists.

pub fn remove_atom(&mut self, name: &str) -> Option<Atom>

Removes an atom by name and returns ownership to the caller.

Arguments

• name - Atom name to remove (case-sensitive).

Returns

Some(atom) if the atom existed, otherwise None.

pub fn atom(&self, name: &str) -> Option<&Atom>

Retrieves an immutable reference to an atom by name.

Arguments

• name - Atom name to search for.

Returns

Some(&Atom) when the atom exists, otherwise None.

pub fn atom_mut(&mut self, name: &str) -> Option<&mut Atom>

Retrieves a mutable reference to an atom by name.

Arguments

• name - Atom name to search for.

Returns

Some(&mut Atom) when the atom exists, otherwise None.

pub fn has_atom(&self, name: &str) -> bool

Checks whether an atom with the provided name exists.

Arguments

• name - Atom name to test.

Returns

true if the atom is present.

pub fn atoms(&self) -> &[Atom]

Returns an immutable slice of all atoms contained in the residue.

Enables zero-copy iteration when only read-only access is required.

Returns

A slice view over the internal atom vector.

pub fn atom_count(&self) -> usize

Counts the number of atoms owned by the residue.

Returns

Number of atoms currently stored.

pub fn is_empty(&self) -> bool

Indicates whether the residue has no atoms.

Returns

true if atom_count() equals zero.

pub fn iter_atoms(&self) -> Iter<'_, Atom>

Provides an iterator over immutable atom references.

This mirrors atoms() but allows idiomatic for loops without exposing the backing vector.

Returns

An iterator yielding &Atom values.

pub fn iter_atoms_mut(&mut self) -> IterMut<'_, Atom>

Provides an iterator over mutable atom references.

Returns

An iterator yielding &mut Atom values so callers can edit coordinates or metadata.

pub fn strip_hydrogens(&mut self)

Removes all hydrogen atoms from the residue.

Used by cleaning operations when preparing structures for solvation or heavy-atom analysis.

Trait Implementations

impl Clone for Residue

fn clone(&self) -> Residue

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Residue

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

Formats the value using the given formatter.

impl Display for Residue

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

Formats the residue with identifier, canonical name, category, and atom count.

impl PartialEq for Residue

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Residue