use-ion 0.1.0

Ion identity and charge primitives for RustUse
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

use std::fmt;

use use_chemical_formula::ChemicalFormula;

use crate::{IonCharge, IonFormula, IonKind, IonName, IonValidationError};

/// A charged atom or charged group represented by formula and charge.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Ion {
    formula: IonFormula,
    charge: IonCharge,
    name: Option<IonName>,
    kinds: Vec<IonKind>,
    oxidation_state_label: Option<String>,
}

impl Ion {
    /// Creates an ion from a parsed formula and validated charge.
    #[must_use]
    pub fn new(formula: ChemicalFormula, charge: IonCharge) -> Self {
        Self {
            formula: IonFormula::new(formula),
            charge,
            name: None,
            kinds: Vec::new(),
            oxidation_state_label: None,
        }
    }

    /// Returns the chemical formula.
    #[must_use]
    pub fn formula(&self) -> &ChemicalFormula {
        self.formula.as_formula()
    }

    /// Returns the ion formula wrapper.
    #[must_use]
    pub const fn ion_formula(&self) -> &IonFormula {
        &self.formula
    }

    /// Returns the ionic charge.
    #[must_use]
    pub const fn charge(&self) -> IonCharge {
        self.charge
    }

    /// Returns the optional ion name.
    #[must_use]
    pub const fn name(&self) -> Option<&IonName> {
        self.name.as_ref()
    }

    /// Returns ion kind labels in insertion order.
    #[must_use]
    pub fn kinds(&self) -> &[IonKind] {
        &self.kinds
    }

    /// Returns the optional oxidation-state label.
    #[must_use]
    pub fn oxidation_state_label(&self) -> Option<&str> {
        self.oxidation_state_label.as_deref()
    }

    /// Returns `true` when the ion has a positive charge.
    #[must_use]
    pub const fn is_cation(&self) -> bool {
        self.charge.is_cation()
    }

    /// Returns `true` when the ion has a negative charge.
    #[must_use]
    pub const fn is_anion(&self) -> bool {
        self.charge.is_anion()
    }

    /// Adds a kind label if it is not already present.
    #[must_use]
    pub fn with_kind(mut self, kind: IonKind) -> Self {
        if !self.kinds.contains(&kind) {
            self.kinds.push(kind);
        }
        self
    }

    /// Sets the ion name from a validated value.
    #[must_use]
    pub fn with_name(mut self, name: IonName) -> Self {
        self.name = Some(name);
        self
    }

    /// Sets the ion name after validation.
    ///
    /// # Errors
    ///
    /// Returns [`IonValidationError::EmptyName`] when `name` is empty after trimming.
    pub fn try_with_name(self, name: &str) -> Result<Self, IonValidationError> {
        Ok(self.with_name(IonName::new(name)?))
    }

    /// Sets the oxidation-state label from a prevalidated value.
    #[must_use]
    pub fn with_oxidation_state_label(mut self, label: String) -> Self {
        self.oxidation_state_label = Some(label);
        self
    }

    /// Sets the oxidation-state label after validation.
    ///
    /// # Errors
    ///
    /// Returns [`IonValidationError::EmptyOxidationStateLabel`] when `label` is empty after trimming.
    pub fn try_with_oxidation_state_label(self, label: &str) -> Result<Self, IonValidationError> {
        let trimmed = label.trim();
        if trimmed.is_empty() {
            Err(IonValidationError::EmptyOxidationStateLabel)
        } else {
            Ok(self.with_oxidation_state_label(trimmed.to_owned()))
        }
    }
}

impl fmt::Display for Ion {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        if self.charge.magnitude() == 1 {
            write!(formatter, "{}{}", self.formula, self.charge.sign())
        } else {
            write!(
                formatter,
                "{}^{}{}",
                self.formula,
                self.charge.magnitude(),
                self.charge.sign()
            )
        }
    }
}