Skip to content

API Reference

The crate's public surface is intentionally tiny. Everything lives at the crate root, so functions are imported directly:

use gold_melt_value::{purity, melt_value_grams, melt_value_dwt, melt_value_troy_oz, spot_per_gram};

Constants

GRAMS_PER_TROY_OZ

pub const GRAMS_PER_TROY_OZ: f64 = 31.1034768;

The number of grams in one troy ounce. Used internally to convert a per-ounce spot price into a per-gram price.

Unit Value
1 troy ounce 31.1034768 g
1 pennyweight 1.55517384 g
1 troy ounce 20 dwt

Functions

purity

pub fn purity(karat: u32) -> f64

Decimal purity (fineness) for a karat value, computed as karat / 24.

  • purity(24) → 1.0 (pure, 24-karat)
  • purity(22) → 0.9166…
  • purity(18) → 0.75 (18k)
  • purity(14) → 0.5833… (14k)
  • purity(10) → 0.4166… (10k)

Arguments

Name Type Description
karat u32 Karat rating from 0 to 24.

Returns f64 between 0.0 and 1.0.

use gold_melt_value::purity;

assert_eq!(purity(24), 1.0);
assert!((purity(18) - 0.75).abs() < 1e-9);
assert!((purity(14) - 0.5833333).abs() < 1e-6);

spot_per_gram

pub fn spot_per_gram(spot_per_troy_oz: f64) -> f64

Converts a per-troy-ounce spot price into a per-gram spot price, by dividing by GRAMS_PER_TROY_OZ (31.1034768).

Arguments

Name Type Description
spot_per_troy_oz f64 Spot price for one troy ounce, in any currency.

Returns The equivalent price per gram of pure metal.

use gold_melt_value::spot_per_gram;

// $3983.30/oz → ~$128.066/g
let per_g = spot_per_gram(3983.30);
assert!((per_g - 128.066).abs() < 0.001);

melt_value_grams

pub fn melt_value_grams(grams: f64, karat: u32, spot_per_troy_oz: f64) -> f64

Melt value for a weight expressed in grams.

melt_value_grams = grams × purity(karat) × (spot_per_troy_oz / 31.1034768)

Arguments

Name Type Description
grams f64 Weight of the piece in grams.
karat u32 Karat rating (0–24).
spot_per_troy_oz f64 Spot price per troy ounce, in the target currency.

Returns Melt value in the spot-price currency.

use gold_melt_value::melt_value_grams;

// 10 g of 14k at $3983.30/oz ≈ $747.05
let v = melt_value_grams(10.0, 14, 3983.30);
assert!((v - 747.05).abs() < 0.05);

// 1 g of pure 24k at $3983.30/oz ≈ $128.066
let pure = melt_value_grams(1.0, 24, 3983.30);
assert!((pure - 128.066).abs() < 0.001);

melt_value_dwt

pub fn melt_value_dwt(dwt: f64, karat: u32, spot_per_troy_oz: f64) -> f64

Melt value for a weight expressed in pennyweight (dwt). 1 dwt = 1/20 troy ounce, so this is equivalent to converting dwt to troy ounces and then applying purity.

melt_value_dwt = (dwt / 20) × purity(karat) × spot_per_troy_oz

Arguments

Name Type Description
dwt f64 Weight of the piece in pennyweight.
karat u32 Karat rating (0–24).
spot_per_troy_oz f64 Spot price per troy ounce, in the target currency.

Returns Melt value in the spot-price currency.

use gold_melt_value::melt_value_dwt;

// 20 dwt of 24k == 1 troy oz at spot
let v = melt_value_dwt(20.0, 24, 3983.30);
assert!((v - 3983.30).abs() < 1e-6);

melt_value_troy_oz

pub fn melt_value_troy_oz(troy_oz: f64, karat: u32, spot_per_troy_oz: f64) -> f64

Melt value for a weight already in troy ounces. No unit conversion is applied; only purity scales the spot price.

melt_value_troy_oz = troy_oz × purity(karat) × spot_per_troy_oz

Arguments

Name Type Description
troy_oz f64 Weight of the piece in troy ounces.
karat u32 Karat rating (0–24).
spot_per_troy_oz f64 Spot price per troy ounce, in the target currency.

Returns Melt value in the spot-price currency.

use gold_melt_value::melt_value_troy_oz;

// 0.5 troy oz of 18k at $3983.30/oz
let v = melt_value_troy_oz(0.5, 18, 3983.30);
// = 0.5 × 0.75 × 3983.30 ≈ 1493.74
assert!((v - 1493.74).abs() < 0.01);

Module karats

pub mod karats {
    pub const K24: u32 = 24;   // pure
    pub const K22: u32 = 22;
    pub const K18: u32 = 18;   // 75% gold
    pub const K14: u32 = 14;   // 58.3% gold (most common US jewelry)
    pub const K10: u32 = 10;   // 41.7% gold (US minimum for "gold")
}

Common US jewelry karat purities, as named constants for readability.

use gold_melt_value::{melt_value_grams, karats::K18};

let v = melt_value_grams(7.5, K18, 3983.30);

Numerical notes

  • All math is in f64. The crate is dependency-free and uses only std-level floating point, so results are suitable for display and comparison. For accounting-grade rounding, round the returned f64 to the cent in the calling code.
  • GRAMS_PER_TROY_OZ = 31.1034768 is the exact internationally agreed gram-to-troy-ounce ratio. pennyweight uses the exact 1 dwt = 1/20 oz t definition, so melt_value_dwt(20.0, 24, s) == melt_value_troy_oz(1.0, 24, s) to within floating-point epsilon.