Crate use_ion 

use-ion

Small ion identity and charge primitives for RustUse chemistry crates.

use-ion represents charged atoms and charged groups with a formula, validated charge, optional name, optional oxidation-state label, and lightweight kind labels. It stays structural and intentionally avoids reaction modeling, electrochemistry simulation, acid/base behavior, naming engines, solubility rules, and common-ion databases.

What this crate provides

Item	Purpose
Ion	Formula-backed charged atom or group
IonName	Validated optional ion name
IonFormula	Ion-facing formula wrapper
IonCharge	Nonzero signed ionic charge
ChargeSign	Positive or negative charge sign
ChargeMagnitude	Nonzero charge magnitude
Cation	Positive-ion wrapper
Anion	Negative-ion wrapper
MonatomicIon	Monatomic-ion wrapper
PolyatomicIon	Polyatomic-ion wrapper
IonKind	Lightweight ion classification label
IonValidationError	Structured construction and validation error

Installation

[dependencies]
use-ion = "0.1.0"

Quick Examples

Create a monatomic cation

use use_chemical_formula::ChemicalFormula;
use use_ion::{Ion, IonCharge};

let sodium = Ion::new(
    ChemicalFormula::parse("Na")?,
    IonCharge::positive(1)?,
);

assert!(sodium.is_cation());
assert_eq!(sodium.charge().magnitude(), 1);
assert_eq!(sodium.to_string(), "Na+");

Create a polyatomic anion

use use_chemical_formula::ChemicalFormula;
use use_ion::{Ion, IonCharge, IonKind};

let sulfate = Ion::new(
    ChemicalFormula::parse("SO4")?,
    IonCharge::negative(2)?,
)
.with_kind(IonKind::Polyatomic);

assert!(sulfate.is_anion());
assert_eq!(sulfate.to_string(), "SO4^2-");

Use focused wrappers

use use_chemical_formula::ChemicalFormula;
use use_ion::{Cation, IonCharge, PolyatomicIon};

let calcium = Cation::new(ChemicalFormula::parse("Ca")?, 2)?;
let ammonium = PolyatomicIon::new(
    ChemicalFormula::parse("NH4")?,
    IonCharge::positive(1)?,
)?;

assert_eq!(calcium.to_string(), "Ca^2+");
assert_eq!(ammonium.to_string(), "NH4+");

Scope

• Represents ion identity, formula, nonzero charge, optional names, cation/anion labels, monatomic/polyatomic labels, optional oxidation-state labels, and stable display formatting.
• Uses use-chemical-formula for formula primitives and parsing examples.
• Keeps common-ion knowledge out of the crate. Callers provide formulas, charges, names, and labels.
• No electrochemical potential.
• No redox reactions.
• No acid/base behavior.
• No solubility rules.
• No compound naming.
• No oxidation-state inference.
• No hardcoded common-ion database.
• No runtime network access or external chemistry data.

Relationship to use-chemistry

use-ion is a focused child crate for ion identity and charge primitives. The use-chemistry umbrella crate reexports it alongside element, formula, bond, compound, molecule, isotope, periodic-table, atomic-number, atomic-mass, and electron-shell helpers. Ion identity and charge primitives.

Structs

Anion

A negative ion wrapper.

Cation

A positive ion wrapper.

ChargeMagnitude

A nonzero ionic charge magnitude.

Ion

A charged atom or charged group represented by formula and charge.

IonCharge

A nonzero signed ionic charge.

IonFormula

An ion-facing chemical formula wrapper.

IonName

A validated ion name.

MonatomicIon

A monatomic ion wrapper.

PolyatomicIon

A polyatomic ion wrapper.

Enums

ChargeSign

The sign of an ionic charge.

IonKind

A lightweight ion classification label.

IonValidationError

Errors returned when constructing ion values.