Crate use_oxidation_state 

use-oxidation-state

Small oxidation-state primitives for RustUse chemistry crates.

use-oxidation-state represents oxidation-state values, signs, magnitudes, Roman numeral labels, element assignments, formula-context assignments, and small assignment sets. It stays structural and intentionally avoids redox solving, reaction modeling, electrochemistry simulation, compound naming, oxidation-state inference, and common oxidation-state databases.

What this crate provides

Item	Purpose
OxidationState	Validated signed oxidation-state value
OxidationSign	Positive, negative, or zero sign
OxidationMagnitude	Bounded oxidation-state magnitude
RomanOxidationState	Roman numeral display for common magnitudes
ElementOxidationState	Element-symbol oxidation-state assignment
FormulaOxidationState	Formula/context assignment group
OxidationStateAssignment	Label plus oxidation-state entry
OxidationStateSet	Small insertion-order assignment collection
OxidationStateValidationError	Structured construction and validation error

Installation

[dependencies]
use-oxidation-state = "0.1.0"

Quick Examples

Create oxidation states

use use_oxidation_state::OxidationState;

let iron_ii = OxidationState::positive(2)?;
let oxygen = OxidationState::negative(2)?;
let elemental = OxidationState::zero();

assert_eq!(iron_ii.to_string(), "+2");
assert_eq!(oxygen.to_string(), "-2");
assert_eq!(elemental.to_string(), "0");
assert_eq!(iron_ii.to_roman(), Some(String::from("II")));

Display element oxidation states

use use_oxidation_state::{ElementOxidationState, OxidationState};

let iron_iii = ElementOxidationState::new("Fe", OxidationState::positive(3)?)?;
let copper_i = ElementOxidationState::new("Cu", OxidationState::positive(1)?)?;

assert_eq!(iron_iii.to_string(), "Fe(III)");
assert_eq!(copper_i.to_string(), "Cu(I)");

Store formula-context entries

use use_oxidation_state::{
    FormulaOxidationState, OxidationState, OxidationStateAssignment, OxidationStateSet,
};

let mut states = OxidationStateSet::new();
states.insert(OxidationStateAssignment::new("Fe", OxidationState::positive(3)?)?);
states.insert(OxidationStateAssignment::new("O", OxidationState::negative(2)?)?);

let hematite = FormulaOxidationState::new("Fe2O3", states)?;

assert_eq!(hematite.formula_label(), "Fe2O3");
assert_eq!(hematite.states().len(), 2);
assert_eq!(hematite.to_string(), "Fe2O3 [Fe: +3, O: -2]");

Scope

• Represents oxidation-state signs, magnitudes, zero states, positive states, negative states, Roman numeral labels, element assignments, formula-context assignments, and stable display formatting.
• Keeps all chemistry knowledge caller-provided. Callers choose symbols, labels, formulas, and state assignments.
• Uses no runtime network access and no external chemistry data.
• No redox balancing.
• No reaction logic.
• No oxidation-state inference from formulas.
• No compound naming.
• No electrochemical potentials.
• No hardcoded common oxidation-state table.
• No full chemistry toolkit behavior.

Relationship to use-chemistry

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

Structs

ElementOxidationState

An oxidation-state assignment for an element symbol.

FormulaOxidationState

Oxidation-state assignments in a formula or caller-defined formula context.

OxidationMagnitude

A bounded oxidation-state magnitude.

OxidationState

A validated oxidation-state value.

OxidationStateAssignment

A labeled oxidation-state assignment.

OxidationStateSet

A small insertion-order collection of oxidation-state assignments.

RomanOxidationState

A Roman numeral representation of a common oxidation-state magnitude.

Enums

OxidationSign

The sign of an oxidation-state value.

OxidationStateValidationError

Errors returned when constructing oxidation-state values.

Functions

roman_numeral

Returns the Roman numeral for a supported oxidation-state magnitude.