Skip to main content

Crate inchi

Crate inchi 

Source
Expand description

Safe, idiomatic Rust bindings to the IUPAC InChI reference library for generating InChI and InChIKey chemical identifiers.

The InChI C library is vendored and statically linked through the inchi-sys crate, so there is nothing to install and no network access at build time. This crate wraps it in a panic-free, Result-based API where every native allocation is released automatically (RAII) and no unsafe is exposed at the public boundary.

§Quickstart

Generate an InChI and InChIKey from a Molfile. Pass () for default options (or Options to customize):

use inchi::{from_molfile, inchikey};

// A minimal V2000 Molfile for methane (one carbon; hydrogens are implicit).
let methane = "\n  example\n\n  1  0  0  0  0  0  0  0  0  0999 V2000\n\
    \x20   0.0000    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\nM  END\n";

let result = from_molfile(methane, ())?;
assert_eq!(result.inchi(), "InChI=1S/CH4/h1H4");

let key = inchikey(result.inchi())?;
assert_eq!(key, "VNWKTOKETHGBQD-UHFFFAOYSA-N");

Or build a structure programmatically:

use inchi::{Molecule, Atom, BondOrder};

let mut ethanol = Molecule::new();
let c1 = ethanol.add_atom(Atom::new("C"));
let c2 = ethanol.add_atom(Atom::new("C"));
let o = ethanol.add_atom(Atom::new("O"));
ethanol.add_bond(c1, c2, BondOrder::Single)?;
ethanol.add_bond(c2, o, BondOrder::Single)?;

assert_eq!(ethanol.to_inchi(())?.inchi(), "InChI=1S/C2H6O/c1-2-3/h3H,2H2,1H3");

§API overview

This crate wraps the complete InChI generation, parsing, and validation API. For concepts and worked examples (standard vs. non-standard InChI, stereo conventions, polymers), see the guide.

Structure → InChI

InChI → structure

InChI → InChIKey (feature key)

Conversion & validation

Generation is tuned through Options, including the experimental Polymers extension. Native allocations are released automatically.

§Feature flags

FeatureDefaultDescription
keyyesEnables inchikey/inchikey_with_hashes (GetINCHIKeyFromINCHI).
regenerate-bindingsnoRegenerates the FFI bindings with bindgen (needs libclang).

§Thread safety

The underlying InChI C library keeps internal static state and is not guaranteed to be re-entrant, so every call into it is serialized behind a global lock. All functions in this crate are therefore safe to call from multiple threads, but calls do not run concurrently with one another. The public types are Send and Sync.

§Minimum supported Rust version

This crate supports Rust 1.77 and later. Raising the MSRV is treated as a semver-breaking change.

Modules§

guide
User guide — concepts and worked examples.

Structs§

Atom
A single atom in a Molecule.
ExtendedStructure
A Structure together with any polymer data recovered from an InChI by struct_from_inchi_ex.
InchiKeykey
An InChIKey together with the optional 256-bit hash extensions.
InchiOutput
The successful result of generating an InChI.
Molecule
A molecular structure assembled programmatically from atoms, bonds, and 0D stereo descriptors.
Options
A builder for InChI generation options.
PolymerUnit
A single polymer structural repeating unit (CTFile Sgroup).
Structure
A molecular structure recovered from an InChI string.
StructureAtom
One atom of a Structure recovered from an InChI.
StructureBond
One bond of a Structure, referencing atoms by index.

Enums§

BondOrder
The order of a covalent bond.
ImplicitH
How many implicit hydrogens an atom carries.
InchiError
The error type returned by all fallible operations in this crate.
InchiKeyValidity
The verdict returned by check_inchikey for an InChIKey string.
InchiValidity
The verdict returned by check_inchi for an InChI string.
Parity
A 0D stereo parity (used when no coordinates disambiguate the geometry).
PolymerConnection
The CTFile SCN connection scheme of a PolymerUnit.
PolymerSubtype
The CTFile SST unit subtype of a PolymerUnit.
PolymerUnitKind
The CTFile STY unit type of a PolymerUnit.
Polymers
How polymer structural-repeating-unit (SRU) data is processed.
Radical
The unpaired-electron (radical) state of an atom.
Status
The status class returned by the InChI C library.
Stereo
A single 0D stereo element, referencing atoms by their index in the Molecule.
StereoMode
How stereochemistry is interpreted during InChI generation.

Functions§

check_inchi
Checks whether a string is a valid InChI.
check_inchikey
Checks whether a string is a syntactically valid InChIKey.
from_molfile
Generates an InChI directly from a Molfile (V2000/V3000 SDF text).
inchi_to_inchi
Re-derives an InChI from an existing InChI string.
inchikeykey
Computes the 27-character InChIKey for an InChI string.
inchikey_with_hasheskey
Computes the InChIKey and, optionally, its two 256-bit hash extensions.
struct_from_aux_info
Reconstructs a Structure from the AuxInfo emitted alongside an InChI.
struct_from_inchi
Parses an InChI string into its atom/bond/stereo Structure.
struct_from_inchi_ex
Parses an InChI into its structure and polymer data via the extended GetStructFromINCHIEx entry point.

Type Aliases§

Result
A specialized Result for InChI operations.